sg245460
WebSphere Application Servers:
Standard and Advanced Editions
Barry Nusbaum, Matias Djunatan, Wakako Jinno, Peter Kelley
International Technical Support Organization
http://www.redbooks.ibm.com
SG24-5460-00
International Technical Support Organization
WebSphere Application Servers:
Standard and Advanced Editions
July 1999
SG24-5460-00
Take Note!
Before using this information and the product it supports, be sure to read the general information in Appendix B,
“Special Notices” on page 459.
First Edition (July 1999)
This edition applies to V2.02 of WebSphere Application Server for WIndows NT and AIX.
Comments may be addressed to:
IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 678
P.O. Box 12195
Research Triangle Park, NC 27709-2195
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way
it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1999. All rights reserved.
Note to U.S Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions
set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
The Team That Wrote This Redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Comments Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
© Copyright IBM Corp. 1999
Chapter 1. Planning for the IBM WebSphere Application Server .
1.1 Overview of WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . .
1.1.2 WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.3 WebSphere Performance Pack . . . . . . . . . . . . . . . . . . . . . .
1.1.4 WebSphere Site Analysis . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 The Value of a Web Application Server . . . . . . . . . . . . . . . . . . . .
1.3 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 Web Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2 Servlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3 Java Server Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4 Java Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5 Enterprise Java Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6 Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.7 XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.8 XSL Stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.9 e-business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.10 Component Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.11 Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.12 Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.13 CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.14 RMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.15 IIOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.16 JNDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.17 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.18 Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.19 Bean Managed Persistence. . . . . . . . . . . . . . . . . . . . . . . .
1.3.20 Container Managed Persistence . . . . . . . . . . . . . . . . . . . .
1.4 Planning for WebSphere Standard Edition . . . . . . . . . . . . . . . . .
1.5 Planning for WebSphere Advanced Edition . . . . . . . . . . . . . . . . .
1.6 Infrastructure Used in This Project . . . . . . . . . . . . . . . . . . . . . . .
1.7 WebSphere Components Overview. . . . . . . . . . . . . . . . . . . . . . .
1.7.1 Static HTML Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.2 Servlet Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.3 JSP Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.4 EJB Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. .1
. .1
. .2
. .4
. .5
. .5
. .5
. .5
. .5
. .5
. .6
. .6
. .6
. .6
. .6
. .6
. .7
. .7
. .7
. .7
. .7
. .7
. .7
. .7
. .8
. .8
. .8
. .8
. .9
.10
.11
.11
.12
.13
.18
.19
Chapter 2. Installation of WebSphere and Associated Products
2.1 Infrastructure Installation for Windows NT V4.0. . . . . . . . . . . . .
2.1.1 JDK 1.1.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.2 HTTP Server V1.3.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.3 Server Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.4 Domino Go Webserver . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.5 Netscape SuiteSpot V3.x for Windows NT. . . . . . . . . . . . .
2.1.6 Microsoft IIS V4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.7 DB2 Universal Database (UDB) for Windows NT. . . . . . . .
2.1.8 Lotus Domino R5 Server for Windows NT . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.29
.29
.30
.32
.34
.37
.41
.47
.52
.57
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
iii
2.2 WebSphere Installation on Windows NT . . . . . . . . .
2.3 Infrastructure Installation for AIX V4.3.2 . . . . . . . . .
2.3.1 JDK 1.1.6 Installation and Setup Procedure . . .
2.3.2 IBM HTTP Server V1.3.3 for AIX . . . . . . . . . . .
2.3.3 Domino Go Webserver. . . . . . . . . . . . . . . . . . .
2.3.4 Netscape SuiteSpot V3.X for AIX . . . . . . . . . . .
2.3.5 DB2 Universal Database (UDB) for AIX . . . . . .
2.3.6 Lotus Domino R5 Server for AIX . . . . . . . . . . .
2.4 WebSphere Installation on AIX . . . . . . . . . . . . . . . .
2.5 Using WebSphere for the First Time . . . . . . . . . . . .
2.6 Setting Up a Development System . . . . . . . . . . . . .
2.6.1 Setting Up VisualAge for Java . . . . . . . . . . . . .
2.6.2 Setting Up and Using Command Line Session .
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
63
67
67
70
72
72
74
77
79
82
86
87
89
Chapter 3. Content Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1 How to Deploy and Configure a Servlet . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Placing Class Files on the Application Server . . . . . . . . . . . . . . . .
3.1.2 Placing HTML, JSP, and SHMTL Files on the Application Server. .
3.1.3 Configuring a Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.4 Monitoring Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Java Server Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 JSP Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 JSP File Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 <SERVLET> Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4 JSP Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5 JSP APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.6 JSP Sample1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.7 JSP Sample 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.8 Tools for Creating JSP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Using the WebSphere XML Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Setting Up the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.3 Processing XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.4 XML Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.5 XML Style Sheets and LotusXSL . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.6 Example: Using XSL and XML to Format DB2 Data . . . . . . . . . . . .
3.3.7 Installing Later Versions of the XML Tools . . . . . . . . . . . . . . . . . . .
. 91
. 91
. 92
. 94
. 96
116
120
120
123
124
127
140
141
145
152
152
153
154
154
163
164
166
185
Chapter 4. Enterprise Java Services . . . . . . . . . . . . . . . . . . . . . .
4.1 The EJS Java Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Configuring Enterprise Java Services . . . . . . . . . . . . . . . . . . . .
4.2.1 Setting Up the Environment . . . . . . . . . . . . . . . . . . . . . . . .
4.2.2 Working with Containers . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.3 Deploying an EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.4 Working with Deployment Descriptors Using the Jet Tool .
4.3 Coding WebSphere EJB Clients . . . . . . . . . . . . . . . . . . . . . . . .
4.3.1 Finding EJBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.2 Monitoring EJS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 Running the EJS Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.1 EJS Sample Configuration Steps . . . . . . . . . . . . . . . . . . . .
4.4.2 Running the EJS Samples . . . . . . . . . . . . . . . . . . . . . . . . .
187
187
188
188
189
192
197
207
207
213
215
216
217
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
..
..
..
..
Chapter 5. Designing Applications for WebSphere . . . . . . . . . . . . . . . . . 221
5.1 Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
iv
WebSphere Application Servers - Standard and Advanced
5.1.1 Maintaining HTTP Sessions . . . . . . . . . . . . . . .
5.1.2 Session Tracking in the WebSphere Application
5.1.3 Session Object Sample . . . . . . . . . . . . . . . . . . .
5.1.4 Session Clustering . . . . . . . . . . . . . . . . . . . . . .
5.2 User Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1 Setting Up User Profiles . . . . . . . . . . . . . . . . . .
5.2.2 How to Use UserProfile in Your Servlet . . . . . . .
5.2.3 UserProfile Sample . . . . . . . . . . . . . . . . . . . . . .
5.2.4 Linking User Profiles to Sessions . . . . . . . . . . .
5.2.5 Extending the UserProfile Class . . . . . . . . . . . .
5.3 Using the Personalization Utilities . . . . . . . . . . . . . . .
5.3.1 Creating Bulletins . . . . . . . . . . . . . . . . . . . . . . .
5.3.2 Web Site Messaging . . . . . . . . . . . . . . . . . . . . .
5.4 Connection Pooling . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1 Key Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2 Connection Manager Architecture . . . . . . . . . . .
5.4.3 Creating Connection Manager Applications . . . .
......
Server
......
......
......
......
......
......
......
......
......
......
......
......
......
......
......
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.221
.225
.233
.248
.253
.253
.255
.256
.265
.271
.286
.286
.295
.306
.306
.307
.320
Chapter 6. Enterprise Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.1 JDBC Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.2 Using JDBC in Java Programs . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.3 SQLJ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.4 Using SQLJ in Java Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Using DB2 UDB for WebSphere Applications . . . . . . . . . . . . . . . . . . . .
6.2.1 DB2 Java Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.2 Setting Up DB2 Java Support for the WebSphere Environment . . .
6.2.3 DB2 Java Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 Using Oracle for WebSphere Applications. . . . . . . . . . . . . . . . . . . . . . .
6.3.1 Oracle Java Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.2 Setting Up Oracle Java Support for the WebSphere Environment .
6.3.3 Oracle Java Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4 Using MQSeries for WebSphere Applications . . . . . . . . . . . . . . . . . . . .
6.4.1 MQSeries Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4.2 MQSeries for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4.3 MQSeries for Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5 Using TXSeries for WebSphere Application . . . . . . . . . . . . . . . . . . . . .
6.5.1 IBM CICS Gateway for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5.2 Setting Up CICS Gateway for Java for WebSphere . . . . . . . . . . . .
6.5.3 CICS Gateway for Java Example . . . . . . . . . . . . . . . . . . . . . . . . .
.331
.332
.332
.337
.340
.345
.349
.350
.353
.353
.356
.356
.359
.359
.362
.363
.365
.371
.375
.376
.381
.383
Chapter 7. WAS 3.0, Site Analyzer Technology Preview .
7.1 Installing WebSphere Site Analyzer . . . . . . . . . . . . . . .
7.1.1 First Time Setup . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 A First Look at the Site Analyzer . . . . . . . . . . . . . . . . . .
7.2.1 Site Analyzer Users. . . . . . . . . . . . . . . . . . . . . . . .
7.2.2 Site Analyzer Analysis and Projects . . . . . . . . . . .
7.2.3 Site Analyzer Architecture . . . . . . . . . . . . . . . . . . .
7.3 Content Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3.1 Using Content Analysis . . . . . . . . . . . . . . . . . . . . .
7.4 Usage Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.1 Web Server Log Files . . . . . . . . . . . . . . . . . . . . . .
7.4.2 Using Usage Analysis . . . . . . . . . . . . . . . . . . . . . .
.387
.387
.390
.392
.393
.394
.394
.394
.396
.399
.400
.401
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
v
7.5 Site Surveyor . . . . . .
7.6 Reports and Details .
7.6.1 Report Element
7.6.2 Report . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
404
406
406
408
Chapter 8. Problem Determination . . . . . . . . . . . . . . . . . . . . . . . .
8.1 WebSphere Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.1 Overall Log Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.2 The JVM Standard Error Log . . . . . . . . . . . . . . . . . . . . . . .
8.1.3 The JVM Standard Output Log. . . . . . . . . . . . . . . . . . . . . .
8.1.4 The IBM HTTP Server Information Log . . . . . . . . . . . . . . .
8.1.5 The IBM HTTP Server Error Log . . . . . . . . . . . . . . . . . . . .
8.1.6 The WebSphere Trace Log . . . . . . . . . . . . . . . . . . . . . . . .
8.1.7 The Servlet Admin Service Error Log . . . . . . . . . . . . . . . . .
8.1.8 The Servlet Admin Service Event Log . . . . . . . . . . . . . . . .
8.1.9 The Servlet Admin Service Access Log . . . . . . . . . . . . . . .
8.1.10 The Servlet Service Error Log . . . . . . . . . . . . . . . . . . . . .
8.1.11 The Servlet Service Event Log . . . . . . . . . . . . . . . . . . . . .
8.1.12 The Servlet Service Access Log . . . . . . . . . . . . . . . . . . .
8.1.13 The WebSphere Engine Tracing Log . . . . . . . . . . . . . . . .
8.2 The Application Server Debug Console . . . . . . . . . . . . . . . . . . .
8.2.1 Enabling the Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2 The Server Console Monitor . . . . . . . . . . . . . . . . . . . . . . .
8.2.3 The Trace Enabler Page . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.4 The Exceptions Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.5 The EJS Status Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.6 The Resource Usage Monitor . . . . . . . . . . . . . . . . . . . . . .
8.2.7 The Loaded Servlets Monitor . . . . . . . . . . . . . . . . . . . . . . .
8.2.8 The Sessions Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.9 The Pooled Connections Monitor . . . . . . . . . . . . . . . . . . . .
8.3 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.1 Tracers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.2 Trace Output Handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.3 Running the Socket Server Trace Console . . . . . . . . . . . .
8.3.4 Setting Trace Properties Using the Debug.properties File .
8.3.5 Creating Your Own Tracers . . . . . . . . . . . . . . . . . . . . . . . .
8.3.6 Creating Your Own Trace Output Handlers . . . . . . . . . . . .
8.4 The Server Execution Analysis Pages . . . . . . . . . . . . . . . . . . . .
8.4.1 The JVM Debug Page . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.2 The Settings Pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.3 The Error Log Settings Page . . . . . . . . . . . . . . . . . . . . . . .
8.4.4 The Event Log Settings Page . . . . . . . . . . . . . . . . . . . . . .
8.4.5 The Dump Panel Setup Page. . . . . . . . . . . . . . . . . . . . . . .
8.4.6 The Log Output Monitor Page . . . . . . . . . . . . . . . . . . . . . .
8.5 Miscellaneous Debugging Tools . . . . . . . . . . . . . . . . . . . . . . . .
8.5.1 DB2 CLI Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.5.2 JDBC Output Redirection . . . . . . . . . . . . . . . . . . . . . . . . . .
8.5.3 Running the EJS Processes Stand-alone. . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
411
411
411
412
413
413
414
414
415
416
416
417
418
418
418
418
418
419
420
421
422
422
423
424
424
424
425
427
427
428
430
431
435
436
436
438
439
440
441
442
442
444
445
Appendix A. WebSphere Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
A.1 Other Configuration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
A.1.1 Samples From the Samples Web Page . . . . . . . . . . . . . . . . . . . . . . . . .456
vi
WebSphere Application Servers - Standard and Advanced
Appendix B. Special Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Appendix C. Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.1 International Technical Support Organization Publications. . . . . . . . . . . . . .
C.2 Redbooks on CD-ROMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3 Other Publications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4 Web Sites Referenced in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
461
461
461
461
461
How to Get ITSO Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .465
IBM Redbook Fax Order Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .467
ITSO Redbook Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .469
vii
viii
WebSphere Application Servers - Standard and Advanced
Preface
IBM WebSphere is a collection of software products that work on IBM and
non-IBM platforms to help you develop and manage Web sites. The WebSphere
Application Servers help provide the infrastructure for deploying your Web
applications.
In this book we show how to plan for, install and use the WebSphere Application
Servers on the AIX and NT platforms. Explanations are given for common
Internet-related terms with pointers to examples of how to implement many of
them within the WebSphere structure. Details are provided on how to build
applications and connect to back-end DB2 and Oracle databases. In addition to
building applications we take a first look at how to manage Web sites and how to
perform problem determination.
This book can be used by webmasters and HTML coders to help efficiently design
their application infrastructure. In addition, anyone building a new WebSphere
environment from scratch will greatly benefit from the step-by-step approach that
is shown in the installation chapter.
The Team That Wrote This Redbook
This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization Raleigh Center.
Barry Nusbaum is a Consulting International Technical support representative at
the International Technical Support Organization, Raleigh Center. He writes
extensively and teaches IBM classes worldwide on all areas of systems
management on the NT and AIX platform. He is also currently working on projects
related to the e-business Application Framework and WebSphere. Before joining
the ITSO seven years ago, he worked in Professional Services in the United
States as a National Communications Specialist. You can reach him by e-mail at
[email protected]
Matias Djunatan is a solution architect in PT. Mitra Integrasi Komputindo (MIK),
Indonesia. He has eight years of experience in developing applications on various
IBM platforms. He holds a degree in Computer Science from the University of
New South Wales, Australia. His areas of expertise include finance/banking
information technology, middleware, distributed component architecture and Java
application developments.
Wakako Jinno is an I/T engineer in Japan. She has experience in designing and
developing Web applications associated with RDB, with Java, embedded SQL,
etc. She has worked at Internet Systems, IBM Japan Systems Engineering for
two years. Her areas of expertise include WebSphere, RDB such as DB2, Oracle,
Sybase.
Peter Kelley is an advisory technical specialist at the Sydney Solution
Partnership Centre in Australia. He has 10 years of experience working with IBM
software technologies, including three years with Java. He holds a Bachelor of
Science degree from the University of Sydney. His areas of expertise include
Java, VisualAge for Java and WebSphere. He has completed one previous
redbook on the OS/2 Workplace Shell.
© Copyright IBM Corp. 1999
ix
Thanks to the following people for their invaluable contributions to this project:
Scott Boag
Lotus Development Corp.
Elias Bayeh, Arnold Goldberg, Jason McGee, Michael Morton, Spike Washburn
IBM WebSphere Development Team
Chris Beckett, Mark Fisher, Tom Hartrick, Ken McCauley, Lisa Morley, Jeff Reser
IBM WebSphere Development Team
Shawn Walsh
International Technical Support Organization, Raleigh Center
Comments Welcome
Your comments are important to us!
We want our redbooks to be as helpful as possible. Please send us your
comments about this or other redbooks in one of the following ways:
• Fax the evaluation form found in “ITSO Redbook Evaluation” on page 469 to
the fax number shown on the form.
• Use the online evaluation form found at http://www.redbooks.ibm.com/
• Send your comments in an Internet note to [email protected]
x
WebSphere Application Servers: Standard and Advanced Editions
Chapter 1. Planning for the IBM WebSphere Application Server
In this book the following conventions apply:
• Directory paths on AIX and Windows NT have slashes that go in different
directions. In all cases when you see slashes going the opposite way from the
platform that you are working on they can be reversed.
For example
<Server Root>\servlets\WebBank\CreateAccountServlet.servlet
in this book for Windows NT is the same as
<Server Root>/servlets/WebBank/CreateAccountServlet.servlet
when you are working on AIX, and vice versa.
• The symbol <Server Root> refers to the root directory where the IBM
WebSphere Application Server is installed. By default this will be
C:\WebSphere\AppServer on Windows NT and /usr/WebSphere/AppServer on
AIX, but your installation may vary.
• The symbol <your web server> refers to the Web address of the machine on
which you have the WebSphere Application Server installed. This may be as
simple as localhost if the machine you are working on is the local machine or
something like server.your.company.com if WebSphere is installed on another
(remote) machine.
1.1 Overview of WebSphere
The IBM WebSphere products are a group of products designed to assist Web
application developers to develop, deploy and manage advanced Web sites. The
WebSphere product range includes the following:
• WebSphere Application Server for the deployment of Web applications (the
subject of this book). WebSphere Application Server V2.02 currently comes in
both a Standard and an Advanced Edition. See 1.1.1, “WebSphere Application
Server” on page 2 for more details.
• WebSphere Studio for the development of Web applications. See 1.1.2,
“WebSphere Studio” on page 4 for more details.
• WebSphere Performance Pack for enhancing and managing the performance
of WebSphere Web sites. See 1.1.3, “WebSphere Performance Pack” on
page 5 for more details.
• WebSphere Site Analysis for monitoring client requests to a WebSphere Web
site and analyzing links on that site (see Chapter 7, “WAS 3.0, Site Analyzer
Technology Preview” on page 387 for more details). WebSphere Site Analysis
is now included as part of WebSphere Application Server Version 3.0 and not
as a separate product. It is included in this book as a technology preview. That
means that some of the screens and functions will change when the product is
generally available.
Although we refer to the other components in the WebSphere product line we
primarily are concerned with the WebSphere Application Server and to some
extent with WebSphere Site Analysis. The terms WebSphere and WebSphere
Application Server (or WAS) will be used interchangeably even though
© Copyright IBM Corp. 1999
1
WebSphere refers to the entire product line. Other products will be referred to by
their full names.
1.1.1 WebSphere Application Server
The WebSphere Application Server (WAS) is a Java application server designed
to facilitate the management and deployment of Web applications. These
deployed applications are typically composed of either Enterprise Java Beans
(EJBs), Java Server Pages (JSPs) and/or Java servlets and they communicate to
clients using a Web browser client interface. Each of the different types of Java
applications that run in the WebSphere environment can also make use of Java
Beans (which are different from Enterprise Java Beans). WebSphere provides the
environment and infrastructure required to install and manage these types of
applications.
WAS does not operate in isolation. It needs to be installed on a host Web server
that handles HTTP requests from browsers and delivers HTML back to them
using the HTTP protocol. When WebSphere is installed, it modifies the
configuration of its host Web server to redirect certain requests to WebSphere for
processing rather than letting the Web server handle them. WebSphere can be
installed on a number of supported Web servers (see 1.5, “Planning for
WebSphere Advanced Edition” on page 10) and it also ships with the IBM HTTP
Server, which is based on the popular Apache Web server but adds SSL support.
The WebSphere application server processes can either run as part of the Web
Server processes or separately, using interprocess communication to talk to the
Web server.
WebSphere makes use of a Java development and run-time environment on the
host machine. This Java environment allows WebSphere to execute the Java
programs that make up the Web applications.
WebSphere is administered through the use of a Java-capable Web browser that
supports HTML V4, such as Netscape Navigator or Microsoft Internet Explorer
(seeTable 1., “AIX Requirements” on page 9 for supported browsers). This is
done by using an HTTP administration interface that allows remote administration
of the server. The administration interface can be accessed by loading the URL
http://<your web server>:9527/ into a Web browser. If your Web browser is on the
same system as your server you can also perform the administration.
WebSphere Advanced uses a database (see 1.5, “Planning for WebSphere
Advanced Edition” on page 10) to provide persistence (see 1.3.18, “Persistence”
on page 8) services for storing EJBs. If a database is not installed or available on
the machine on which WebSphere is installed, then DB2 UDB V5.2 is installed
during the WAS installation for use with WAS only. A limited function version of
DB2 is packaged with WebSphere on the product CD.
WebSphere Application Server V2.02 comes in two editions: Standard and
Advanced. The Standard Edition includes support for Java Server Pages (JSPs)
and servlets as well as XML document structure services and session
management. The Advanced Edition has all of the same functions as the
Standard Edition, plus it has an EJB engine and a database to act as a persistent
store for EJB information. A third edition, called Enterprise Edition, will be
available later in 1999 when WebSphere V3.0 is delivered.
2
WebSphere Application Servers: Standard and Advanced Editions
The features in WebSphere Application Server Standard Edition are:
• IBM HTTP Server
WebSphere Application Server ships with IBM HTTP server, which can be
installed as part of the WebSphere Application Server installation process if
no other Web server is installed (See Chapter 2, “Installation of WebSphere
and Associated Products” on page 29 for more information on WebSphere
installation). The IBM HTTP Server is based on the Apache freeware Web
server with added SSL support.
• Servlet support
WebSphere includes a servlet engine for running Java Servlets. See 3.1, “How
to Deploy and Configure a Servlet” on page 91 for more information on
servlets.
• Support for Lotus Domino Version 5.0
See 2.1.8, “Lotus Domino R5 Server for Windows NT” on page 57 for more
information on installing WebSphere with Lotus Domino Version 5.0.
• Administration interface
WebSphere is administered using a Web-based Java administration interface.
• XML Document Structure Services
WebSphere provides XML Document Structure Services to allow the
generation and manipulation of XML-formatted data using Java. See 3.3,
“Using the WebSphere XML Tools” on page 152 for more information on
working with XML Document Structure Services.
• Integration with VisualAge for Java
IBM VisualAge for Java includes a WebSphere test environment to allow the
development and testing of WebSphere applications within the VA Java IDE.
See
http://www7.software.ibm.com/vad.nsf/Data/Document3172?OpenDocument&SubMast=1
for more information on integrating VisualAge for Java and WebSphere.
1.1.1.1 Features in WebSphere Application Server Advanced Edition
The following additional features are present in the Advanced Edition:
• Enterprise JavaBeans Server allows the deployment of EJBs
EJBs provide a platform-independent way to provide business logic in a
managed environment.
• A naming service accessible through JNDI to facilitate the location and usage
of EJBs by remote clients
A naming service is used by EJB clients to locate references to EJBs deployed
on the WebSphere server.
• CORBA support to allow EJBs deployed in WebSphere to be accessed by
remote CORBA objects
CORBA support facilitates interoperability with CORBA objects on non-EJB
servers.
These features are together called Enterprise Java Services (EJS) and are
described in Chapter 4, “Enterprise Java Services” on page 187.
Planning for the IBM WebSphere Application Server
3
1.1.2 WebSphere Studio
WebSphere Studio is a collection of development tools that are used to develop
the components necessary to produce a Web site. WebSphere Studio includes
IBM VisualAge for Java Professional Edition, Net Objects Fusion, Net Objects
Bean Builder, Net Objects Script Builder and the WebSphere Studio Workbench
and Wizards. Version 3.0 will include the Wallop Build-IT product as well.
1.1.2.1 IBM VisualAge for Java
IBM VisualAge for Java, or VA Java, is an integrated enterprise Java development
environment. It is a repository-based tool that allows incremental compilation of
Java source as well as powerful version control features. It includes a visual
programming environment for Java component assembly and many features that
assist the development of enterprise Java programs. It provides strong support
for databases and other back-end systems as well as Java Beans and Enterprise
Java Beans. It comes in Entry, Professional and Enterprise versions. For more
information see http://www.software.ibm.com/ad/vajava.
For additional details and examples about VA Java go to
http://www.redbooks.ibm.com and download the following books:
• VisualAge for Java Enterprise Version 2: Data Access Beans - Servlets - CICS
Connector, SG24-5265
• Using VisualAge for Java Enterprise Edition Version 2 to Develop CORBA EJB
Applications, SG24-5276
• Programming with VisualAge for Java Version 2, SG24-5264
1.1.2.2 Net Objects Fusion
Net Objects Fusion is a tool that allows the creation of entire Web sites using a
template-based approach. Each template captures a particular look and feel with
facilities to add different Web site components such as text, graphics and plug-ins
to each page as it is created. For more information see
http://www.netobjects.com/products/html/nf3i.html.
1.1.2.3 Net Objects Bean Builder
Net Objects Bean Builder is a Java Bean assembly tool. It allows you to visually
assemble Java Beans and link their behavior. The finished code can then be
packaged as a Java Bean or applet as well as to a variety of other formats. For
more information see http://www.netobjects.com/products/html/nbb1.html.
1.1.2.4 Net Objects Script Builder
Net Objects Script Builder is an integrated development environment for
developing scripting for Web pages. It includes support for the scripting
technologies used in Web servers from IBM, Sun, Microsoft and Netscape. The
IDE supports syntax highlighting for scripting languages and there is an
integrated debugger. For more information see
http://www.netobjects.com/products/html/nsb3.html.
1.1.2.5 WebSphere Studio Workbench and Wizards
The WebSphere Studio Workbench is a workbench that groups together all of the
files that make up a Web site under development. Each file, or group of files, can
be edited with any of the Studio development tools and new tools can be added.
The wizards facility allows the easy creation of Java servlets (see 1.3.2,
4
WebSphere Application Servers: Standard and Advanced Editions
“Servlets” on page 5) to access databases, use server-side Java Beans and
capture information about site visitors. For more information see
http://www.software.ibm.com/webservers/studio/doc/wsguide.pdf.
1.1.3 WebSphere Performance Pack
For more information, see http://www.redbooks.ibm.com and download IBM
WebSphere Performance Pack Usage and Administration, SG24-5233.
1.1.4 WebSphere Site Analysis
IBM WebSphere Site Analysis is a tool used to provide basic traffic measurement
functions for a Web site. It allows users to gauge traffic volume (hits, visits),
identify traffic sources (domains, subdomains, referrers), and manage site
integrity (link verification, site conformance). For more information see
http://www.software.ibm.com/webservers/analysis or Chapter 7, “WAS 3.0, Site
Analyzer Technology Preview” on page 387.
1.2 The Value of a Web Application Server
A Web application server, such as WebSphere, is a key component in a three-tier
(or n-tier) e-business solution. It acts as an integration point between the
enterprise data and applications on the back end and a nearly universal client,
the browser, on the front end. This allows both a low-cost client platform with low
configuration overhead and access for a wide variety of client devices without
changing the application. It also shields the back-end servers from interference
generated by client requests and improves application scalability by allowing
resource pooling at the middle tier.
A complete discussion of the architecture and thinking behind three-tier
computing is probably beyond the scope of this book. However, there is a good
set of white papers on the subject at
http://www.software.ibm.com/ebusiness/library.html, and in particular the
architecture overview white paper at
http://www.software.ibm.com/ebusiness/arch_overview.html is very interesting.
1.3 Terminology
The following are some terms used in this book.
1.3.1 Web Application Servers
A Web application server is a software program designed to manage applications
at the second-tier of three-tier computing, that is, the business logic components.
A Web application server manages applications that use data from back-end
systems, such as databases and transaction systems, and provides output to a
Web browser on a client. For more information see
http://www.software.ibm.com/ebusiness/appsrvsw.html.
1.3.2 Servlets
Servlets are Java classes that run on Web servers to provide dynamic HTML
content to clients. They take as input the HTTP request from the client and output
dynamically generated HTML. For more information on servlets see 3.1, “How to
Planning for the IBM WebSphere Application Server
5
Deploy and Configure a Servlet” on page 91 and also
http://www.software.ibm.com/ebusiness/pm.html#Servlets.
1.3.3 Java Server Pages
Java Server Pages are HTML source files that include Java extensions to provide
dynamic content and increased functionality. Java Server Pages are compiled
into Servlets before deployment. See
http://www.software.ibm.com/ebusiness/pm.html#Java Server Pages and 3.2, “Java
Server Pages” on page 120 for more information.
1.3.4 Java Beans
Java Beans are Java components designed to be used on client systems. They
are Java classes that conform to certain coding standards. They can be
described in terms of their properties, methods and events. Java Beans may be
packaged with a special descriptor class called a BeanInfo class and special
property editor classes in a JAR file. Java Beans may or may not be visual
components. See http://www.javasoft.com/beans/docs for more information.
1.3.5 Enterprise Java Beans
Despite the name, Enterprise Java Beans or EJBs are not Java Beans. Enterprise
Java Beans are server-side Java components that are designed for distributed
environments. They do not exist in isolation but are rather deployed in containers
that provide services such as security, naming and directory services and
persistent storage. WebSphere Application Server is just such a container. See
http://java.sun.com/products/ejb/ for more information.
1.3.6 Connectors
The term connectors, or e-business connectors, is used to describe gateway
products from IBM that allow access to enterprise data on back-end systems over
the Internet. They include direct browser access to back-end systems such as
DB2 through Net.data and also Java access through products such as the CICS
gateway for Java. See http://www.software.ibm.com/ebusiness/connectors.html for
more information.
1.3.7 XML
XML, or eXtensible Markup Language, is a platform-independent and
application-independent way of describing data using tags. XML (a subset of
SGML) is similar to HTML in that it uses tags to describe document elements but
different in that the tags describe the structure of the data rather than how the
data is to be presented to a client. XML has the facility to allow data providers to
define new tags as needed to better describe the data domain being represented.
For more information see http://www.software.ibm.com/xml and 3.3, “Using the
WebSphere XML Tools” on page 152.
1.3.8 XSL Stylesheets
XSL stylesheets are documents that describe a mapping between XML
documents and visual data that can be presented to a client in a browser. XSL
was a draft standard when this book was being written. The draft can be found at
http://www.w3.org/TR/WD-xs. An example of using XSL stylesheets with
6
WebSphere Application Servers: Standard and Advanced Editions
WebSphere can be found in 3.3.6.4, “Developing an XSL Style Sheet” on page
169.
1.3.9 e-business
e-business is a term used by IBM to describe the use of Internet technologies to
transform business processes. What this means in practice is using Internet
clients such as Web browsers as front ends for applications that access back-end
legacy systems to allow greater access. See
http://www.software.ibm.com/ebusiness for more information.
1.3.10 Component Broker
Component Broker is an IBM CORBA management server product that provides
an object request broker (ORB) to facilitate the deployment of CORBA objects.
The EJB deployment engine in WebSphere is based largely on similar services in
Component Broker. See http://www.software.ibm.com/ad/cb. for more information.
1.3.11 Scalability
Scalability is an abstract attribute of software that refers to its ability to handle
increased data throughput without modification. WebSphere handles scalability
by allowing execution on a variety of hardware platforms that allow increased
performance and clustering.
1.3.12 Clustering
Clustering is a technique used to provide scalability through the use of multiple
copies of an application on the same or separate machines. Careful management
of the different applications is necessary to ensure that they work together
effectively. WebSphere has limited clustering support in Version 2.x and more
support in Version 3.0.
1.3.13 CORBA
Common Object Request Broker Architecture (CORBA) is a cross-platform,
industry-standard distributed object protocol. CORBA is used to locate and use
objects on a variety of platforms, written in a variety of languages across a
network. See http://www.omg.org for more information on CORBA.
1.3.14 RMI
Remote Method Invocation (RMI) is a lightweight distributed object protocol that
allows Java objects to call each other across a network. RMI is part of the core
Java specification. See http://java.sun.com/products/jdk/rmi/index.html for more
information.
1.3.15 IIOP
Internet Inter ORB Protocol (IIOP) is an internet protocol used for CORBA object
communication. For more information see http://www.whatis.com/iiop.htm.
1.3.16 JNDI
Java Naming and Directory Interface (JNDI) is an API that allows Java programs
to interface and query naming and directory services in order to find information
about network resources. JNDI is used in WebSphere to provide a directory of
Planning for the IBM WebSphere Application Server
7
Enterprise Java Beans. See http://java.sun.com/products/jndi/index.html for
more information.
1.3.17 JDBC
JDBC is a Java API that allows Java programs to communicate with different
database management systems in a platform-independent manner. Database
vendors provide JDBC drivers for their platforms that implement the API for their
database, allowing the Java developer to write applications to a consistent API no
matter which database is used. For more information see 6.1, “JDBC” on page
332.
1.3.18 Persistence
Persistence is a term used to describe the storage of objects in a database to
allow them to persist over time rather than being destroyed when the application
containing them terminates. Enterprise Java Bean containers such as
WebSphere provide persistence services for EJBs deployed within them. For
more information see 1.3.19, “Bean Managed Persistence” and 1.3.20,
“Container Managed Persistence”.
1.3.19 Bean Managed Persistence
Bean Managed Persistence (BMP) is a term used to describe a type of entity EJB
where the bean developer specifies how the bean is to be persisted to a database
by writing Java code in the appropriate methods to perform the tasks required.
See 1.3.20, “Container Managed Persistence”.
1.3.20 Container Managed Persistence
Container Managed Persistence (CMP) is a term used to describe a type of entity
EJB where the code to persist the bean to a database is generated at deployment
time by the EJB container. See 1.3.19, “Bean Managed Persistence”.
8
WebSphere Application Servers: Standard and Advanced Editions
1.4 Planning for WebSphere Standard Edition
The hardware and software requirements for IBM WebSphere Application Server
Standard Edition on AIX and Windows NT are as follows.
Table 1. AIX Requirements
Operating System
•
•
•
•
•
IBM AIX Version 4.2.1 or Higher
Supported Web Server
IBM HTTP Server V1.3.3 (on WAS installation CD)
Apache Server V1.3.2 for AIX
Domino V5.0 for AIX
Lotus Domino Go Webserver V4.6.2.5 for AIX
Netscape Enterprise Server V3.01 and V3.51 for
AIX (recommend V3.5.1)
Netscape FastTrack Server V3.01 for AIX
JDK
JDK 1.1.6 with patch PTF2 or higher
Supported Web Browsers
A browser that supports JDK1.1:
Netscape Navigator 4.06 or higher
Microsoft Internet Explorer 4.01 with the fix pack, or
higher
Sun HotJava 1.1 or higher
RS/6000 or RS/6000 SP running AIX V4.2.1, or later
Support for an appropriate network interface
Minimum 45 MB of free disk space for installation
CD-ROM drive
Minimum 64 MB of memory, 128 MB recommended
Table 2. Windows NT Requirements
Operating System
Windows NT Server with Service Pack 3
Supported Web Server
IBM HTTP Server V1.3.3 for NT (available during
Application Server install)
Apache Server V1.3.2 for NT
Domino V5.0 for Windows NT
Lotus Domino Go Webserver V4.6.2.5 for NT
Microsoft IIS V3.x and V4.0 for NT
Netscape Enterprise Server V3.01 and V3.51 for NT
(recommend V3.5.1)
Netscape FastTrack Server V3.01 for NT
JDK
JDK 1.1.6
(JDK 1.1.7 from IBM or Sun may also work)
Supported Web Browsers
A browser that supports JDK1.1:
Netscape Navigator 4.06 or higher
Microsoft Internet Explorer 4.01 with the fix pack, or
higher.
Sun HotJava 1.1 or higher
The software requirements are:
•
•
•
•
•
Any Intel-based PC running Windows NT Server V4.0
Support for a communications adapter
Minimum 40 MB of free disk space for installation
CD-ROM drive
Minimum 64 MB of memory, 128 MB recommended
Planning for the IBM WebSphere Application Server
9
1.5 Planning for WebSphere Advanced Edition
The hardware and software AIX requirements for IBM WebSphere Application
Server Advanced Edition are as follows:
Table 3. AIX Requirements
Operating System
IBM AIX Version 4.2.1 or Higher
Supported Web Server
IBM HTTP Server V1.3.3 (on WAS installation CD)
Apache Server V1.3.2 for AIX
Domino V5.0 for AIX
Lotus Domino Go Webserver V4.6.2.5 for AIX
Netscape Enterprise Server V3.01 and V3.51 for
AIX (recommend V3.5.1)
JDK
JDK 1.1.6 with patch PTF2 or higher
Supported Web Browsers
A browser that supports JDK1.1:
Netscape Navigator 4.06 or higher
Microsoft Internet Explorer 4.01 with the fix pack, or
higher
Sun HotJava 1.1 or higher
Supported Databases
Any database supporting JDBC Version 1.1
• RS/6000 or RS/6000 SP running AIX V4.2.1, or later
• Support for an appropriate network interface
• Minimum 45 MB of free disk space for installation; 128 MB recommended,
especially if installing DB2
• CD-ROM drive
• Minimum 128 MB of memory; 256 MB recommended
Table 4. Windows NT Requirements
Operating System
10
Windows NT Server with Service Pack 3
Supported Web Server
IBM HTTP Server V1.3.3 for NT (available during
Application Server install)
Apache Server V1.3.2 for NT
Domino V5.0 for Windows NT
Lotus Domino Go Webserver V4.6.2.5 for NT
Microsoft IIS V3.x and V4.0 for NT
Netscape Enterprise Server V3.01 and V3.51 for NT
(recommend V3.5.1)
JDK
JDK 1.1.6
(JDK 1.1.7 from IBM or Sun may also work)
Supported Web Browsers
A browser that supports JDK1.1:
Netscape Navigator 4.06 or higher
Microsoft Internet Explorer 4.01 with the fix pack, or
higher
Sun HotJava 1.1 or higher
Supported Databases
DB2 UDB 5.2 or higher
DB2 UDB 5.0 with FixPak US9077 may work but is
not supported
WebSphere Application Servers: Standard and Advanced Editions
The Windows NT hardware requirements are:
• Support for a communications adapter
• Minimum 40 MB of free disk space for installation; 128 MB recommended,
especially if installing DB2
• CD-ROM drive
• Minimum 128 MB of memory; 256 MB recommended
1.6 Infrastructure Used in This Project
The following is a list of hardware and software that was used for this project:
RS/6000:
•
•
•
•
RS/6000 43P-140 (7043-140)
Single 332 MHz PowerPC_604 Processor
256 MB RAM
2 * 4.5GB SCSI HDD
Intel:
•
•
•
•
Netfinity 3000 (8476-21U)
Single 350 MHz Pentium II Processor
1 * 4GB SCSI HDD
128 MB RAM
AIX Software:
• AIX 4.3.2
• WebSphere Application Server Standard V2.02
• WebSphere Application Server Advanced V2.02
1.7 WebSphere Components Overview
Figure 1 on page 12 is a logical diagram showing the various flows in an
operating WebSphere system. Although there is a lot of information contained
here, the data flows that we are concerned with can be broken down into several
categories:
• Static HTML requests - See 1.7.1, “Static HTML Requests” on page 12.
• Servlet requests - See 1.7.2, “Servlet Requests” on page 13.
• JSP page requests - See 1.7.3, “JSP Requests” on page 18.
• EJB interactions - See 1.7.4, “EJB Interactions” on page 19.
Planning for the IBM WebSphere Application Server
11
Data
Request
Servlet
Call
Data
Response
Static Content
Servlet
Engine
Static
Content
Request
Servlet
Servlet
Repository
Compiled
JSP
JSP
Compiler
Static
Content
Response
Servlet
Request
HTML
Output
JSP Request
Web Server
Compile
Request
JSP Repository
Persist EJB
EJB Containers
HTTP
Request
HTTP
Response
Load EJB
EJB
Request
Client
Database
EJB
Response
Data
Response
Data
Request
Back End
Servers
Figure 1. WebSphere Data Flows
1.7.1 Static HTML Requests
Serving static HTML is perhaps the simplest task that a Web server can perform
and it does not use the capabilities of WebSphere at all. Instead, it relies entirely
on the host Web server. Figure 2 on page 13 shows the flow of data that occurs in
servicing a static HTML page request. Upon receiving a request from the client,
the Web server retrieves the correct document from the server’s file system and
sends it to the client. There may be minimal work done by the Web server to
translate the name of the document requested by the client into the correct name
of the document on the file system.
12
WebSphere Application Servers: Standard and Advanced Editions
Data
Request
Servlet
Call
Data
Response
Static Content
Servlet
Engine
Static
Content
Request
Servlet
Servlet
Repository
Compiled
JSP
JSP
Compiler
Static
Content
Response
Servlet
Request
HTML
Output
JSP Request
Web Server
Compile
Request
JSP Repository
Persist EJB
EJB Containers
HTTP
Response
Client
HTTP
Request
Database
Load EJB
EJB
Response
EJB
Request
Data
Response
Data
Request
Back End
Servers
Figure 2. Static HTML Request Data Flows
Although WebSphere does not get involved in this process it is important to
realize that most Web sites will have some static HTML pages included alongside
the dynamic content provided by WebSphere. The WebSphere Studio tools allow
you to generate this static content, and the static components of the more
dynamic Web pages (such as those created using JSPs), with a consistent look
and feel so that the end user does not notice a difference in the pages. Net
Objects Fusion is typically used to perform this task.
1.7.2 Servlet Requests
Servlets provide the base level of WebSphere functions. A servlet is a Java
program that produces HTML dynamically for a given client request. The client
request is passed as a parameter to the servlet from the application server along
with a parameter containing the data structure to be used in constructing the
servlet response.
Figure 3 shows the data flows possible for servlet calls.
Planning for the IBM WebSphere Application Server
13
Data
Request
Servlet
Call
Data
Response
Static Content
Servlet
Engine
Static
Content
Request
Servlet
Servlet
Repository
Compiled
JSP
JSP
Compiler
Static
Content
Response
HTML
Output
Servlet
Request
JSP Request
W eb Server
Compile
Request
JSP Repository
Persist EJB
EJB Containers
HTTP
Response
HTTP
Request
Load EJB
EJB
Request
Client
Database
EJB
Response
Data
Response
Data
Request
Back End
Servers
Figure 3. Servlet Request Data Flows
When the Web server receives a request for a servlet it redirects the request to
WebSphere. This is accomplished by a change to the Web server configuration
files during the WebSphere installation to call WebSphere when a servlet request
comes in (see 2.2, “WebSphere Installation on Windows NT” on page 63 for
details). WebSphere then loads the correct servlet from the servlet repository
(actually a directory on the application server classpath, typically <Server
Root>\servlets) into the servlet engine and runs it. The input to the servlet will be
the HTTP request originally sent to the Web server by the client. The servlet’s
output is usually an HTML document (or a part of an HTML document), which is
then passed to the Web server for transmission to the client. This behavior is
slightly different when servlet filtering and chaining are used (see 1.7.2.1,
“Servlet Filtering and Chaining” on page 16), which is shown in the diagram by
the servlet engine calling itself.
Servlets, which are actually Java classes, can also make calls to back-end
systems using the appropriate API calls (for example, JDBC, JTS). The data
returned may be used in the construction of the HTML output stream. They may
also make calls to Java Beans, Enterprise Java Beans or even other servlets to
obtain data. In the case of EJB calls, the servlet is acting as an EJB client to the
14
WebSphere Application Servers: Standard and Advanced Editions
WebSphere EJS Server. This is why there are no lines linking the servlet engine
and the EJB containers in Figure 3; the client interfaces described in 1.3.5,
“Enterprise Java Beans” on page 6 are used.
Figure 4 on page 16 shows the Java program listing for a simple servlet. The
important points to note are the parameters passed to the servlet of type
HttpRequest (the variable named request) and HttpResponse (the variable
named response). The request is queried through request.getParameterNames()
and request.getParameter(key) to find if a Name parameter was specified on the
HTTP request. If not, the name is set to "Hello". The next few lines set the MIME
type of the response to "text/html" for output to a browser and some other fields
for the response. Next, the program queries the HttpResponse to get its output
stream (the PrintWriter out) and writes HTML back to the client.
Planning for the IBM WebSphere Application Server
15
import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;
// Step 1: Extend HttpServlet.
public class ServletSample extends HttpServlet {
// Step 2: Specify the required methods.
public void doGet (HttpServletRequest request, HttpServletResponse
response)
throws ServletException, IOException
{
// Step 3: Get the HTTP request information, if any.
Enumeration keys;
String key;
String myName = "";
keys = request.getParameterNames();
while (keys.hasMoreElements())
{
key = (String) keys.nextElement();
if (key.equalsIgnoreCase("myName"))
myName = request.getParameter(key);
}
System.out.println("Name = ");
if (myName == "")
myName = "Hello";
// Step 4: Create the HTTP response.
response.setContentType("text/html");
response.setHeader("Pragma", "No-cache");
response.setDateHeader("Expires", 0);
response.setHeader("Cache-Control", "no-cache");
PrintWriter out = response.getWriter();
out.println("<html>");
out.println("<head><title>Just a basic servlet</title></head>");
out.println("<body>");
out.println("<h1>Just a basic servlet</h1>");
out.println ("<p>" + myName + ", this is a very basic servlet that
writes an HTML page. The source code for more interesting sample servlets is
in the Application Server samples/ directory.");
out.println ("<p>For instructions on running those samples on your
Application Server, open the page:");
out.println("<pre>http://<em>your.server.name</em>/IBMWebAs/samples/index.
html</pre>");
out.println("where <em>your.server.name</em> is the hostname of your
Application Server.");
out.println("</body></html>");
out.flush();
}
}
Figure 4. ServletSample.java
1.7.2.1 Servlet Filtering and Chaining
If multiple servlets are needed to produce a response to a particular client
request then the normal procedure for producing HTML responses becomes a
16
WebSphere Application Servers: Standard and Advanced Editions
little more complex. There are two ways for multiple servlets to collaborate on the
response: filtering and chaining.
In servlet filtering the servlet changes the MIME type of the response it sends
from text/html (which would be sent by WebSphere straight back to the client) to a
user-defined MIME type. WebSphere is then configured to associate the
user-defined MIME type with a particular servlet and the output of the first servlet
is used as the input to the second servlet. In this way servlets can filter the input
to other servlets, forming a filter chain if necessary.
HTTP
Request
From Client
Servlet 1
MIME
Type 1
Servlet 2
MIME
Type 2
Servlet 3
MIME
Type
text/html
for client
Figure 5. Servlet Filtering
In servlet chaining, multiple servlets are called for a single client HTTP request,
each servlet providing part of the HTML output. Each servlet receives the original
client HTTP request as input and each servlet produces its own output
independently. This is accomplished by defining a servlet alias that is specified on
the original request and specifying multiple servlets as the target. Each servlet is
called in the order specified on the alias and the output HTML is made up of the
output from all of the servlets.
Note: This is different from the way that other Web servers perform servlet
chaining. Other servers use the output of the first servlet in the chain as the input
request to the second servlet in the chain and so on. To achieve this functionality
with WebSphere, servlet filtering must be used.
HTTP
Request
from Client
Servlet 1
HTML
Part 1
Servlet 2
HTML
Part 2
Servlet 3
HTML
Part 3
Composite
HTML to
Client
Figure 6. Servlet Chaining
Servlet filtering and chaining have the advantage of allowing the Web developer
to create modular servlets that can, for example, output standard HTML headers
and footers or provide common dynamic content for pages.
Planning for the IBM WebSphere Application Server
17
1.7.3 JSP Requests
Java Server Pages (JSPs) are a way for developers who are familiar with HTML to
easily create servlets. They are also useful for applications where servlets and
other generators of dynamic HTML content must be integrated with static HTML.
JSPs, although quite different from servlets at development time, are actually
precompiled into servlets at run time. Each JSP is stored in the Web server’s
normal document hierarchy and the first time it is invoked by a client it is compiled
to a servlet by the JSP compiler. It is then stored in the servlet repository
(JSP-generated servlets are stored under the directory <Server
Root>/servlets/pagecompile) and treated as a servlet for the rest of its life. If the
JSP is changed at any time, WebSphere detects the change and recompiles the
JSP into an updated version of the servlet, and then runs the new servlet for the
client.
Figure 7 shows the data flows for JSP requests in WebSphere. Note that the "JSP
Repository" shown in the diagram is a logical entity only. JSP source files are
stored in the Web server document hierarchy just like static HTML files.
Servlet
Call
Data
Request
Data
Response
Static Content
Servlet
Engine
Static
Content
Request
Servlet
Servlet
Repository
Compiled
JSP
JSP
Compiler
Static
Content
Response
HTML
Output
Servlet
Request
JSP Request
Web Server
Compile
Request
JSP Repository
Persist EJB
EJB Containers
HTTP
Request
HTTP
Response
Load EJB
EJB
Request
Client
Database
EJB
Response
Data
Response
Data
Request
Back End
Servers
Figure 7. JSP Request Data Flows
If the JSP consists only of HTML tags, the servlet produced by the compiler
simply sets the correct fields on the response, opens an output stream to the
client and writes the HTML. If other JSP tags are used then the compiler will
create Java code in the servlet to perform the requested functions as well as
writing the static pieces of the page. The other tags may include snippets of Java
18
WebSphere Application Servers: Standard and Advanced Editions
code or directives to access back-end servers. See 3.2, “Java Server Pages” on
page 120 for more details on creating and running Java Server Pages.
1.7.4 EJB Interactions
Note: Enterprise Java Services, which is the WebSphere component that
provides Enterprise Java Bean Support, is not included in WebSphere Application
Server Version 2.x Standard Edition.
Enterprise Java Beans are the most powerful feature of the WebSphere
Application Server environment. They build on the philosophy that the application
programmer should not have to worry about the infrastructure, but merely about
the application. This means that the server that deploys the EJBs must provide a
number of services to EJBs in order to manage them properly. These services
are provided by an entity called an EJB Container.
Figure 8 shows a simplified diagram of client EJB interactions:
Data
Request
Servlet
Call
Data
Response
Static Content
Servlet
Engine
Servlet
Servlet
Repository
Compiled
JSP
JSP
Compiler
Static
Content
Response
Static
Content
Request
HTML
Output
Servlet
Request
JSP Request
Web Server
Compile
Request
JSP Repository
Persist EJB
EJB Containers
HTTP
Response
HTTP
Request
Load EJB
EJB
Request
Client
Database
EJB
Response
Data
Response
Data
Request
Back End
Servers
Figure 8. EJB Data Flows
Planning for the IBM WebSphere Application Server
19
The Enterprise Java Beans specification (see
ftp://ftp.javasoft.com/docs/ejb/ejb.10.pdf) defines two types of Enterprise Java
Beans: Session Beans (see 1.7.4.4, “The Life Cycle of a Stateful Session Bean”
on page 25) and Entity Beans (see 1.7.4.3, “The Life Cycle of an Entity Bean” on
page 22). WAS supports both types of EJB. Session beans are further divided
into stateless and stateful session beans while entity beans are further divided
into beans with Bean Managed Persistence (BMP) and Container Managed
Persistence (CMP).
1.7.4.1 EJB Architecture
Figure 9 shows a diagram of client-to-EJB interaction in more detail:
WebSphere Application Server
EJB Container
EJB
EJB Home
Database
EJB Object
Client
Figure 9. EJB Interaction Detail
In order for the management of EJBs to be handled by the server properly, a
client must access EJBs only through a proxy provided by the EJB container. This
allows the container to control persistence, security, caching and connection
management with no knowledge by the client that all of these functions are
occurring with no code in the EJB to control these functions. In order to facilitate
this, all client access to EJBs is done by means of instances of the EJB Home
and the EJB Object interfaces, that are created by the developer during
development. This allows the server to perform management tasks under the
covers by mapping the calls to these interfaces to appropriate calls to the EJB
20
WebSphere Application Servers: Standard and Advanced Editions
itself and also by calling infrastructure methods on the EJB to control transactions
and storage to databases.
The EJB Home interface instance is responsible for allowing clients to find and
create EJBs. For entity beans the home interface includes methods for finding
single beans or groups of beans based on certain criteria including at least one
method that allows the location of a bean in a database using a primary key
class. For both entity and session beans the home interface includes methods to
create new instances of an EJB inside the container and return a reference to an
EJB Object interface instance for the bean. Note that there is one EJB Home
interface instance per class of EJB in a container, but there may be many EJB
Object interface instances depending upon how many actual instances of the EJB
class are present.
The EJB Object interface is responsible for providing access to the operations of
an EJB. Each call to an EJB Object interface instance is mapped to a
corresponding call to a bean instance by the container, subject to security
considerations. Because of the separation from the actual bean, the container is
free to release resources used by the bean, such as database connections or
even the bean instance itself to other uses and restore the EJB instance when a
call is made to it by a client.
1.7.4.2 Steps in Using an EJB
WebSphere Application Server
EJB Container
EJB
Naming Service
4
7
EJB Home
2
EJB Object
3
1
5
Client
6
Figure 10. Steps Used to Call Methods on an EJB
Planning for the IBM WebSphere Application Server
21
Figure 10 shows the steps involved in a client accessing an EJB:
1. The client requests from the naming service (provided as one of the
components of WebSphere) a reference to the EJB Home interface of a
particular class of EJBs.
2. The naming service replies with the location of the Home interface instance for
the EJB class in the container in which the EJB is deployed.
3. The client performs either a create (for a new bean instance) or a find (for an
existing entity bean instance) on the EJB Home interface instance.
4. The EJB Home interface instance locates or creates the EJB instance and
places it in the container and creates the EJB Object interface instance.
5. The EJB Home interface instance replies to the client with a reference to the
EJB Object instance.
6. The client calls methods on the EJB Object interface instance to access
business logic on the EJB.
7. The EJB Object interface instance calls the corresponding methods on the
EJB while the container manages the resources needed to accomplish this
task.
1.7.4.3 The Life Cycle of an Entity Bean
Entity Beans are so called because they typically represent entities, objects with
a persistent state. The Enterprise Java Beans specification (see
ftp://ftp.javasoft.com/docs/ejb/ejb.10.pdf) defines an entity bean as a typical entity
object with the following characteristics:
•
•
•
•
•
It
It
It
It
It
represents data in the database
is transactional
allows shared access from multiple users
can be long-lived (lives as long as the data in the database)
survives crashes of the EJB server; a crash is transparent to the client
A typical EJB server and container provide a scalable run-time environment for a
large number of concurrently active entity objects.
Entity beans typically represent objects with a persistent state, that is data that
needs to be remembered for an indefinite period. They are usually stored as a
single row in a relational database table. The server controls whether or not the
data from the database table is loaded into memory. Similarly the server controls
how many entity EJBs are instantiated in the container and which entities they
represent.
Entity beans come in two flavors: beans with container managed persistence
(CMP) and beans with bean managed persistence (BMP). With CMP beans, the
person deploying the bean specifies which fields in the bean are to be stored in a
database and the deployment tools generate code to load and store the EJB.
With BMP beans the developer adds code to standard methods in the EJB Object
interface to load and save the bean to the database. The advantage of CMP over
BMP is that it requires less code to be written but the disadvantage is that it
provides less flexibility than BMP.
The EJB server manages entity beans in such a way as to keep a logical
separation between the instance of the bean running in the container and the
entity in the database it represents. This allows the container to maintain a pool of
22
WebSphere Application Servers: Standard and Advanced Editions
entity beans available for use and to load the data for different entities in the
database into specific bean instances as needed. To put it another way, the
server may at any time tell an instantiated entity bean to unload its data to the
database and load the data for some other entity. This allows the management of
a pool of instantiated entity beans and accompanying resources to maximize the
performance of the server transparently to both the EJB developer and the client.
To look at this in more detail look at the state transition diagram shown in Figure
11 on page 24. Each entity bean can be in one of three states:
1. Does Not Exist: The entity bean does not exist in memory at all.
2. Pooled: The entity bean has been instantiated, but it does not represent any
particular entity at this time.
3. Ready: The entity bean has been instantiated in memory, and it represents a
particular entity.
Note: BMP beans and CMP beans have the same life cycle as shown by the
diagram, the only difference being in the way the database code is generated.
To put a bean into the Pooled state from the Does Not Exist state, that is to create
an instance ready for the loading of data, the server calls the EJB methods
newInstance() to create the bean, and setEntityContext() to give the bean a
reference to the container in which it exists. Conversely, if the server decides that
there are too many beans in the Pooled state it calls unsetEntityContext() and
finalize(). The server has complete control over the number of beans that exist in
the Pooled state and creates them or destroys them at will based on performance
criteria. In WebSphere the performance criteria is set by the server developers
and is not configurable by server administrators.
Planning for the IBM WebSphere Application Server
23
Does Not Exist
Action Initiated By Client
Action Initiated by Container
unsetEntityContext()
finalise()
newInstance()
setEntityContext()
findxxxx(args)
ejbFindxxxx(args)
Pooled
create(args)
remove()
ejbCreate(args)
ejbPostCreate(args)
ejbPassivate()
ejbActivate()
ejbRemove()
Ready
ejbLoad()
ejbStore()
Business Method
Figure 11. Entity Bean Life Cycle State Transition Diagram
Beans that are in the Pooled state can have several things happen to them. As
mentioned previously they can be selected for removal and destroyed by calling
unsetEntityContext() and finalize(). If the client calls one of the find methods to
locate a bean or group of beans, then one of the beans in the Pooled state is
selected by the server as all of the find methods are static, that is, they do not
refer to a particular instance of the bean class but rather to the class as a whole.
If the client calls a create method then a bean is selected from the pool to hold
the data for the new entity being created and the appropriate ejbCreate() method
is called with the arguments passed by the client followed by the ejbPostCreate()
method. It is now put in the Ready state ready for use by a client. Finally, if the
server decides that a bean needs to be made ready, potentially as the result of a
client calling one of the business methods on the EJB Object interface instance,
the ejbActivate method is called on the pooled bean, which causes it to load all of
its data from the database and become ready.
Beans that are in the Ready state are associated with an entity and ready for use.
If a client calls a business method on the EJB Object instance the bean business
method is called and the bean remains in the Ready state. Similarly, the
ejbLoad() and ejbStore() methods may be called by the server to load and store
information respectively in the underlying database. This is used by the server to
synchronize the information with the database as needed. The only way that the
24
WebSphere Application Servers: Standard and Advanced Editions
bean can be returned to the Pooled state is if the server decides, based on
certain criteria, to passivate the bean by calling its ejbPassivate() method. This
has the effect of causing the bean to write all of its data to the database and
return to the Pooled state.
All of this interaction is transparent to the client and to the EJB programmer
(provided all of the required methods are implemented correctly) with the server
making the decisions. This allows the server to optimize the performance of the
system by allocating resources to particular EJBs as required.
WebSphere provides transaction support for entity beans in accordance with the
EJB specification (see ftp://ftp.javasoft.com/docs/ejb/ejb.10.pdf Section 11, page
95). These transaction characteristics can be specified through the use of the
deployment descriptor in the EJB JAR file. See 4.2.4, “Working with Deployment
Descriptors Using the Jet Tool” on page 197 for details on how to specify
transaction attributes for entity beans and methods.
1.7.4.4 The Life Cycle of a Stateful Session Bean
The first of the two types of session beans is the so-called stateful session bean
(as opposed to stateless session beans (see 1.7.4.5, “The Life Cycle of a
Stateless Session Bean” on page 27). Stateful session beans are designed for
client interactions where there may be a number of interactions with the bean by a
single client and there needs to be data or state stored between interactions. This
is often referred to as a session with the EJB.
There are two important differences to note between stateful session beans and
entity beans, which could also be said to store state information. The first is that
the state does not persist and is not stored anywhere outside of a particular
session. This means that if the session is ended for any reason such as when
WebSphere is restarted or the session exceeds a timeout value (see “Working
with Session Beans” on page 200 for details on how to set this), then the session
information will be lost. The second difference is that session beans are designed
to be used by a single client whereas entity beans are designed to be used by
multiple clients. Thus, there are no "findXXXX" methods on a session bean’s EJB
home interface for clients to find particular session beans, only create and
remove methods.
Planning for the IBM WebSphere Application Server
25
Does Not Exist
create(args)
remove()
newInstance()
Action Initiated By Client
setSessionContext()
ejbCreate(args) ejbRemove() Action Initiated by Container
Non Transaction
Method
ejbPassivate()
Method
Ready
Passive
ejbActivate()
Commit()
Transaction
Method
beforeCompletion()
afterCompletion(true)
Rollback()
afterBegin()
Transaction
Method
afterCompletion(false)
Transaction
Method
Ready
Non Transaction
ERROR
Method
Figure 12. Stateful Session Bean State Transition Diagram
The other important note about stateful session beans is that their transactional
state (for example, whether the bean is currently involved in a transaction)
restricts the possible method calls that are allowable. Each method has a
transaction attribute that is defined either at the bean level or at the method level
(see “Working with Session Beans” on page 200 for details on how to specify
transaction attributes). If a method must execute in the context of a transaction it
is referred to as a transactional method. If a method cannot execute in the context
of a transaction then it is a non-transaction method. There are methods that can
execute either in the context of a transaction or without one.
Figure 12 is a state transition diagram that shows the possible states that a
stateful session bean may be in on the server. The possible states are:
• The bean does not exist.
• The bean is method ready: No transaction has been created on the bean and
it is ready to accept method calls.
• The bean is transaction method ready: A transaction has been created for the
bean and it is ready to accept transaction method calls.
• The bean is passive: The server has decided to release resources used by the
bean and move it to a Passive state.
26
WebSphere Application Servers: Standard and Advanced Editions
From the Does Not Exist state the server calls the newInstance() method to
create a new stateful session bean, the setSessionContext() method, to attach
the bean to its container and the ejbCreate(args) method to instantiate the bean
in the container in response to a create(args) method call made by the client. This
puts the bean in the Method Ready state.
From the Method Ready state a number of things can happen. If the client calls
remove(), then the server calls ejbRemove() and the bean is removed. If the
server decides that it needs to free resources then it might passivate the bean by
calling ejbPassivate() in which case the bean is moved to the Passive state.
Business methods that do not require transactions may be called, in which case
the bean is returned to the Method Ready state. Finally, a transaction method
may be called that causes the container to create a new transaction and then to
call the afterBegin()method. The business method is then called and the bean is
moved to the transaction method Ready state.
While the bean is in the transaction method Ready state, only methods that can
execute on transactions may be called. If a non-transaction method is called then
the server issues a java.rmi.RemoteException. This includes things like the client
calling remove(), which is considered a non-transaction method, or a
non-transaction business method. It is also an error to call a method that requires
a new transaction that is different from the one in which the bean is currently
executing. When a transactional business method is called the bean returns to
the transaction method Ready state. If the client issues a commit() then the
server calls the beforeCompletion() method on the bean to allow it to write any
information to the database and then afterCompletion(true). If the client calls
rollback, then beforeCompletion() is not called and afterCompletion(false) is
executed. Note that the bean will not be passivated while in the transaction
method Ready state.
If the bean is in the Passive state then the server may activate it in response to a
request from the client to execute a business method.
Stateful session beans may have a timeout value specified that limits the amount
of time a session can be kept open by a client before the server can reclaim the
bean instance for other uses. Only beans in the Method Ready and Passive
states can be timed out. Beans with current transactions, for example, those in
the transaction method Ready state, will not be timed out on the server.
1.7.4.5 The Life Cycle of a Stateless Session Bean
Life for a stateless session bean is much simpler than that of the other sorts of
beans. The server maintains a pool of stateless session beans and creates new
ones by calling the newInstance(), setSessionContext() and ejbCreate() methods.
If a request to execute a business method comes in, the server selects a session
bean instance from the method ready pool to service the client request and
executes the method. Finally the server removes beans from the method ready
pool as required by calling the ejbRemove method. Figure 13 on page 28 shows a
diagram of this interaction.
Planning for the IBM WebSphere Application Server
27
Does Not Exist
newInstance()
setSessionContext()
ejbCreate()
ejbRemove()
Business
Method
Action Initiated By Client
Action Initiated by Container
Method
Ready Pool
Figure 13. Stateless Session Bean State Transition Diagram
28
WebSphere Application Servers: Standard and Advanced Editions
Chapter 2. Installation of WebSphere and Associated Products
WebSphere Application Server provides an environment for running applications
on the Web. These applications often require services from other products such
as Web and database servers. This chapter describes the steps needed to install
WebSphere Application Server and to configure it to work with the associated
products. We don’t cover the installation processes for other products, but only
some configuration setup that is related to the WebSphere environment. In this
document, we limit our discussions to the Windows NT and AIX platforms. We
used the Standard and Advanced Editions of the WebSphere V2.02.
Before you install WebSphere, you have to make sure that your system has met
the hardware and operating systems requirements that are described in 1.4,
“Planning for WebSphere Standard Edition” on page 9 and 1.5, “Planning for
WebSphere Advanced Edition” on page 10.
A typical application environment consists of:
• A Java engine
• A Web server
• The WebSphere Application Server
• A back-end database
• A development environment
• A Site Analyzer
• A front-end client
Since WebSphere requires a Java engine and updates your Web server
environment, you should install WebSphere only after your Java engine and Web
server have been installed and set up. Other components (for example, Site
Analyzer or VA Java) can be installed independently.
We don’t explain configuring the Web server in great detail. We discuss only the
basic things that are necessary to build a Web site.
After all of your components are installed, you should configure the related
parameters for each component in order to make them work together. The
following sections describe that process.
2.1 Infrastructure Installation for Windows NT V4.0
The products that we installed were:
•
•
•
•
•
•
•
© Copyright IBM Corp. 1999
JDK 1.1.6
HTTP Server V1.3.3
Domino Go Webserver
Netscape SuiteSpot V3.x
Microsoft IIS V4.0
DB2 UDB
Domino R5 Server
29
2.1.1 JDK 1.1.6
The Java Development Kit (JDK) contains a basic set of software and libraries
that are needed to compile, debug and run Java applets and applications. A
separate package without the tools is available in the Java Runtime Environment
(JRE). Developers might want to use the JRE for testing applications in a similar
environment that end users would run.
The original JDK implementation is available from Sun. You can download it for
free according to the license agreement, from Sun’s Java site at
http://java.sun.com. As of now, JDK 1.2, which is also known as JDK 2.0, is
available. Since Java is undergoing a rapid change, the JDK is incorporating
more and more APIs. Your JDK might not include the latest APIs. In that case,
you have to obtain them separately. WebSphere V2.02 does not support JDK 2.0.
IBM has its own JDK implementations on AIX, OS/2, OS/390, OS/400, VM/ESA
and Win32 platforms. The reason for having these vendor-specific
implementations is for optimization, stability, and IBM service and support on
these platforms. The JDKs are available from the IBM JCentral site at
http://www.ibm.com/java/jdk/. Since IBM delivers JRE only on the Win32 and
OS/2 platforms, end users for other platforms should already have the required
level of JDK installed in their production system.
Figure 14. The IBM JCentral JDK Site at http://www.ibm.com/java/jdk/
When running applications on WebSphere platforms, we recommend that you use
the IBM JDK implementations. It will ensure a robust and smooth integration with
WebSphere products.
2.1.1.1 Installation and Setup Procedure
On Win32 platforms, the JDK is distributed in a zip file or in an InstallShield
self-extracting file. The zip format file does not provide download languages other
than English.
30
WebSphere Application Servers: Standard and Advanced Editions
To install the JDK, you have to download the appropriate file to your hard disk.
After that, simply execute the InstallShield file or unpack the zip file into the
appropriate directory.
The installation program adds an entry to the Windows registry that specifies
JavaHome directory (see Figure 15 on page 31). WebSphere will read these
registry entries to locate JDKs in your system. You can install more than one JDK
version. In this case, the registry will contain several JDK version entries. The
"CurrentVersion" key indicates and sets the active JDK version.
\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\
Name: "CurrentVersion" Data: "1.1"
\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\1.1\
Name: "JavaHome" Data: "D:\jdk1.1.6"
Figure 15. Registry Entries for JDK Installation
Since the installation program does not create or alter the CLASSPATH
environment variable, you have to add the CLASSPATH variable using Start >
Settings > Control Panel > System > Environment and put in the appropriate
CLASSPATH values (see Figure 16 and “System CLASSPATH Environment
Variable” on page 32).
Figure 16. Setting the CLASSPATH Variable
Note: If you install WebSphere V2.02 from a CD, JDK V1.1.6 is located on the CD
and it can be invoked from the WAS setup program.
2.1.1.2 Additional Java Libraries
Developers might require additional Java APIs for developing applications using
some of the advanced features of WebSphere Application Server. The DB2/UDB
Installation of WebSphere and Associated Products
31
package delivers JDBC drivers and SQLJ libraries. The WebSphere Application
Server incorporates JSDK, JSP, JNDI, XSL, XML4J and WebSphere specific
class libraries. Table 5 on page 32 lists APIs with the JDK, DB2/UDB and
WebSphere package. You can also obtain information and download these APIs
and the latest APIs from the JavaSoft site at http://www.javasoft.com or from the
Sun Java Developer Connection site at http://developer.java.sun.com.
Table 5. Java API Package Names and Locations
API
Package Name
Location
JDBC
java.sql
[JDKRoot]\lib\classes.zip
DB2 JDBC driver
com.ibm.jdbc
%DB2PATH%\java\db2java.zip
DB2 SQLJ support
com.ibm.sqlj
%DB2PATH%\java\sqlj.zip
%DB2PATH%\java\runtime.zip
JSDK
javax.servlet
[WASRoot]\lib\jsdk.jar
JSP
com.sun.server.http
[WASRoot]\lib\jst.jar
JNDI
javax.naming
[WASRoot]\lib\jndi.jar
Lotus XSL
com.lotus.xsl
[WASRoot]\lib\lotusxsl.jar
XML4J
com.ibm.xml
org.xml
[WASRoot]\lib\xml4j.jar
IBM WebAS servlet
com.ibm.servlet
[WASRoot]\lib\ibmwebas.jar
IBM Data Access Beans
com.ibm.db
[WASRoot]\lib\databeans.jar
IBM EJS
com.ibm.CORBA
com.ibm.ejb
com.ibm.ejs
com.transarc.encina
javax.ejb
javax.jts
org.omg.CORBA
[WASRoot]\lib\ejs.jar
[WASRoot]\lib\ejsclientruntime.jar
2.1.1.3 System CLASSPATH Environment Variable
The JDK will automatically locate its default Java library, classes.zip. You do not
need to specify it in the CLASSPATH variable. WebSphere will let you choose
between its own CLASSPATH or the system CLASSPATH. It will automatically
recognize paths to its Java libraries. WebSphere will not work if you include the
paths to the system CLASSPATH.
Set or verify your system CLASSPATH to include the remaining libraries:
• %DB2PATH%/java/db2java.zip;%DB2PATH%/java/sqlj.zip;
%DB2PATH/java/runtime.zip or other database JDBC/SQLJ driver libraries
• Paths to additional JAVA API class libraries either in directory, JAR or zip
formats
• Path to your project class libraries for development purposes
2.1.2 HTTP Server V1.3.3
For the Windows NT platform, the IBM HTTP Server is distributed on the
WebSphere CD or you can download it from the IBM Web site,
32
WebSphere Application Servers: Standard and Advanced Editions
http://www.software.ibm.com/webservers. The installation program, which is
setup.exe, will automatically install the Web server into your system. During
installation, you will have to supply a user ID to run the service as shown in
Figure 17. You can always change it later by using the Start > Setting > Control
Panel > Services > Startup dialog box (see Figure 18 on page 34).
Figure 17. Specifying the User ID to Run IBM HTTP Server
The installation adds some entries into the registry as shown below:
\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\HTTPServer\1.3.3
Name: "FolderName" Data: "IBM HTTP Server"
Name: "PATH" Data: "C:\Program Files\IBM\GSK\lib"
Name: "ServerRoot" Data: "C:\Program Files\IBM HTTP Server"
The Web server is installed as a service. By default it is set to run automatically
after you reboot your system. You can change this behavior by setting the Startup
Type to Manual in the Start > Setting > Control Panel > Services > Startup
dialog box as shown in Figure 18. You can start or stop the Web server by either:
• Invoking the Windows start menu program using:
Start > Program > IBM HTTP Server > Start / Stop
• Or entering the following command in the Windows console:
net start "IBM HTTP Server"
or
net stop "IBM HTTP Server"
Installation of WebSphere and Associated Products
33
Figure 18. Specifying IBM HTTP Server to Manually Start Up Using a Specific Account
2.1.3 Server Modules
The IBM HTTP Server follows the Apache Web server architecture by using
modular structures. The HTTP Server consists of modules, each of which
provides a particular service. This approach simplifies the addition or modification
of services in the server. Each module is implemented by a single object file or a
DLL file. The LoadModule directives in the configuration file specifies which
module needs to be loaded as an active module. When the Web server starts, it
scans the configuration file and loads every module specified by the LoadModule
directive.
The default server configuration consists of several base modules. Other than
these base modules, many third-party vendors provide various modules for
different type of services. WebSphere provides its service on the HTTP Server by
using a plug-in module. It is implemented using a module named
mod_ibm_app_server which corresponds to the DLL file
mod_ibm_app_server.dll.
2.1.3.1 Configuring IBM HTTP Server
You can set the Web Server configuration in the <ServerRoot>\conf\httpd.conf
file. This file controls how the server runs. Server parameters are specified as
directives. A directive can be either a one-line directive or a section directive.
Section directives can also be nested. For example:
34
WebSphere Application Servers: Standard and Advanced Editions
# A Comment ..
# One line directive
DirectiveName directive-values
# Section directive
<SectionName SectionParams>
Directive1 directive1-value
Directive2 directive2-value
...
</SectionName>
The installation process provides you with the default directives values that are
sufficient to make the server run. You can also specify names, addresses,
additional modules, access structure and security. To do that, there are some
basic directives that have to be set up. You can obtain these other directives
either from the IBM HTTP Server online configuration manual or from the Apache
site at http://www.apache.org.
ServerAdmin Directive
This directive specifies an e-mail address where clients can write for information.
This e-mail address normally appears in any error message that is sent to the
client. The syntax of this directive is:
ServerAdmin webmaster_email_address
ServerName Directive
This directive sets your site’s host name according to this directive.
ServerName your.host.name
ServerRoot Directive
The server will find all resources and configuration files relative to a root
directory.
ServerRoot directory_absolute_pathname
DocumentRoot Directive
This directive gives an absolute path to the root of your document tree. Any URL
that refers to URL paths other than Alias will be mapped relative to the document
root.
DocumentRoot document_root_absolute_pathname
Alias Directive
This directive allows you to map any URL path to the given directory path name.
Alias url_path directory_absolute_pathname
LoadModule Directive
The LoadModule directive lists a module as a server active module to be loaded
at Web server initialization. It also specifies actual module implementation using
<filename>. In the Win32 platform, a file name is normally a DLL file name.
LoadModule module_name filename
Installation of WebSphere and Associated Products
35
Deny Directive
The server will deny all access from specified hosts.
deny from all | host_list
Allow Directive
The server will grant access from specified hosts.
allow from all | host_list
Order Directive
This directive specifies the order of access checking:
• Verify Deny lists first: [deny,allow].
• Verify Allow lists: [allow,deny].
• Grant access to any host that appears in the Allow list but not in the Deny list
[mutual-failure].
order [deny,allow] | [allow,deny] | [mutual-failure]
Directory Directive
This section directive groups a set of directives that apply to the specified
directory.
<Directory directory_name> .. </Directory>
Limit Directive
This section directive groups a set of directives that apply to specified access
methods. The method can be GET, POST, PUT, DELETE, CONNECT or
OPTIONS.
<Limit access_method_lists> .. </Limit>
Locate Directive
This section directive groups a set of directives that apply to a given URL.
<Location URL> .. </Location>
2.1.3.2 Configuring httpd.conf for WebSphere Applications
The default WebSphere installation modifies the httpd.conf file. It adds a
LoadModule directive to register the plug-in module ibm_app_server_module as
an active module. The installation also specifies a default alias as well as module
parameters:
LoadModule ibm_app_server_module
D:/WebSphere/AppServer/plugins/nt/mod_ibm_app_server.dll
Alias /IBMWebAS/samples/ "D:/WebSphere/AppServer/samples/"
Alias /IBMWebAS/ "D:/WebSphere/AppServer/web/"
NcfAppServerConfig BootFile
D:\WEBSPH~1\APPSER~1\properties\bootstrap.properties
NcfAppServerConfig LogFile D:\WebSphere\AppServer\logs\apache.log
NcfAppServerConfig LogLevel TRACE|INFORM|ERROR
You can change or add additional directives as needed. You can set the host
name, change the document tree structure, create new aliases, set access
control or update user authentication.
2.1.3.3 Controlling User Access
Apache provides two methods for controlling access to documents:
36
WebSphere Application Servers: Standard and Advanced Editions
1. Domain level access control
2. User Authentication
You can use these methods to provide server-wide or per-directory access
control:
• Server-wide access control is set using a global Access Control File (ACF) in
<ServerRoot>/conf/access.conf.
• Per-directory access control is set using <Directory>, <Limit> and <Location>
section directives, or per-directory ACFs.
Domain Level Access Control Example
To limit access to documents under your.domain.name/secret/docs URL to only
GET or POST requests and to deny all access except from a specific domain, use
a Location section directive:
<Location /secret/docs>
<Limit GET POST>
order deny,allow
deny from all
allow from some.domain.com
</Limit>
</Location>
User Authentication Example
To limit access to documents to only GET requests and deny all access except for
the users tony, tims and johny, in domain some.domain.com use a Directory
section directive:
<Directory /www/html/secret/docs>
AuthUserFile /system/passwords/passwordfile
AuthType Basic
<Limit Get>
require user tony tims johny
order deny,allow
deny from all
allow from some.domain.com
</Limit>
</Directory>
2.1.4 Domino Go Webserver
Domino Go Webserver is a Web server product from Lotus. It is also known as
the IBM Internet Connection Server. The product is available on many platforms,
including Windows NT, AIX, Solaris, HP/UX, OS/2 and OS/390. Lotus has
integrated the Webserver into its Lotus Domino R5 server family. It is the Web
services component in the Domino R5 Application Server product. For Windows
NT platforms, the Web server was included in the WebSphere 1.0 package. For
later versions of Websphere, you need to obtain the Domino Go Webserver
installation package separately.
2.1.4.1 Configuring Domino Go Webserver
Domino Go Webserver provides Web-based configuration and administration
forms. You can access these online forms by accessing
http://<your.domain.name>/admin-bin/cfgin/initial, as shown in Figure 19.
These forms are easy to use with a complete description and examples for each
Installation of WebSphere and Associated Products
37
parameter. As an alternative, you may configure the Web server directly using its
configuration file: httpd.cnf.
Figure 19. Domino Go Webserver Configuration and Administration Forms
The configuration file, httpd.cnf, specifies Web server parameters by using
directives. Table 6 lists several important directives. They need to be tailored
according to your Web site’s requirements.
Table 6. Lotus Domino Go Webserver Basic Directives
Directive
38
Syntax
Description
ServerRoot
ServerRoot <path>
Set Web server root directory to
<path>.
Hostname
Hostname <your.domain.name>
Set Web server host name.
Port
Port <port>
Set port used by the Web server.
Exec
Exec <url_template> <path>
For executable resources (such
as cgi programs),
map <url_template> to <path>
WebSphere Application Servers: Standard and Advanced Editions
Directive
Syntax
Description
Map
Map <url_template>
<another_url>
Forward any request for
<url_template> to <another_url>
Fail
Fail <url_template>
Block access to <url_template>
Redirect
Redirect <url_template>
<fully_qualified_server_url>
Forward any request for
<url_template> to fully qualified
server URL
Pass
Pass <url_template> <path>
Translate any request for
<url_template> as an access to
<path> .
Protection
Protection <prot_name> {
<prot_directives> }
Define a protection rule setup,
<prot_name> , by using
<prot_directives> rules.
The rules can be constructed
using UserID, GroupID, ServerID,
AuthType,GetMask,PutMask,
PostMask, DeleteMask, Mask,
ACLOverride,PasswdFile, or
GroupFile directives.
Protect
Protect <url_template>
<prot_name>
Protect <url_template> with
protection rules <prot_name>.
Note: <url_template> and <another_url> are relative to <your.domain.name>
URL. They can specify a particular Web document or use wild cards such as *,
*.gif, or *.html. The <path> is a fully qualified physical directory name such as
C:\WWW\admin, C:\WWW\html.
Some important settings that need to be configured in constructing a Web site:
• Basic settings: host name, default port number, and server root. To configure
these parameters select Basic in the Configuration and Administration forms.
These settings correspond to Hostname, Port and ServerRoot directives.
• Mapping rules that map a request URL to a physical file or to another URL.
Use the Directories and Welcome Pages administration forms. These settings
corresponds to Exec, Map, Fail, Redirect and Pass directives.
• Access control to protect documents and authenticate users. Use the Access
Control administration forms. These settings correspond to Protection and
Protect directives in the httpd.cnf file.
• Manage users using Administration of Users in the Configuration and
Administration page.
As an example, look at the following sections of the httpd.cnf file:
# This is a comment
# The Domino Go Webserver root directory
ServerRoot C:\WWW\Bin
#Web server fully qualified hostname
Hostname wsnt00.itso.ral.ibm.com
#Web server port
Installation of WebSphere and Associated Products
39
Port 80
...
# Define protection rules setup.
Protection MYPROJECT-PROT {
PasswdFile
C:\WINNT\admin.pwd
Mask
[email protected](*)
PostMask
[email protected](*)
PutMask
[email protected](*)
GetMask
[email protected](*)
AuthType
Basic
ServerID
Private_Authorization
}
# Protect these resources using MYPROJECT-PROT setup.
Protect /myproject/* MYPROJECT-PROT
Protect /mydocs/*.pdf MYPROJECT-PROT
...
#
# Mapping rules: Exec, Map, Redirect. They are applied in the order they appear
# in this file.
Exec /admin-bin/* C:\WWW\Admin\*
Exec /cgi-bin/* C:\WWW\CGI-Bin\*
# Map WebSphere samples using Map then Pass directives.
Map /sample/* /IBMWebAS/samples/*
Pass /IBMWebAS/samples/* D:\WebSphere\AppServer\samples\*
# Redirect URL for WebSphere Administration Tool.
Redirect /WASAdmin http://wsnt00.itso.ral.ibm.com:9527
# Don’t touch my project source code.
Fail /myproject/*.java
# This is for my project.
Pass /myproject/* D:\WebSphere\AppServer\servlets\XtremeTravel\*
# Pass the rest to look for in c:\WWW\html directory.
Pass /* C:\WWW\html
...
2.1.4.2 WebSphere Plug-In for Domino Go Webserver on Windows NT
WebSphere can run on top of Domino Go Webserver by using a plug-in. For
Domino Go Webserver 4.x or later on Windows NT, the plug-in file is go46.dll.
During installation the WebSphere installation program adds several entries into
the httpd.cnf file:
ServerInit D:\WebSphere\AppServer\plugins\nt\go46.dll:init_exit
D:\WebSphere\AppServer\properties\bootstrap.properties
ServerTerm D:\WebSphere\AppServer\plugins\nt\go46.dll:term_exit
Pass
/IBMWebAS/samples/*
D:\WebSphere\AppServer\samples\*
Pass
/IBMWebAS/*
D:\WebSphere\AppServer\web\*
40
WebSphere Application Servers: Standard and Advanced Editions
The first and second entries map server initialization and termination functions
into a corresponding API entry in the go46.dll. The other entries are Websphere
default mapping rules.
2.1.5 Netscape SuiteSpot V3.x for Windows NT
Netscape SuiteSpot is a family of server products used to create a complete Web
site. SuiteSpot server products include the Enterprise Server, Fasttrack Server,
Messaging Server, Directory Server, Proxy Server, and Media Server. Netscape
Enterprise is the Web server product in the SuiteSpot family. Since we worked
with installing a Web server for WebSphere, we limited our discussion to the
Enterprise Server. You can obtain more information about Netscape SuiteSpot
products at http://www.netscape.com/servers.
When you install your first Netscape SuiteSpot server product, the Installation
process creates the Administration Server. You have to supply an administrator
port number, and a superuser’s user ID and password. In the next SuiteSpot
server installation, you won’t have to re-create another Administration Server. You
can use the superuser for granting administrator privilege to another user. For
details on the Netscape SuiteSpot installation, you can refer to the SuiteSpot
installation documentation.
The Administration Server is a tool that is used for configuring any Netscape
SuiteSpot server product. In the Administration Server, each SuiteSpot server
has its own Server Manager, which has the same look and feel for every server. A
Server Manager has a collection of forms that you use to configure the SuiteSpot
server.
The Administration Server is a Web-based service using a predefined port
number. To access this facility, you should be the Administration Server
superuser or have an administrator user ID. The superuser privilege allows you to
access all Server Manager forms. The administrator ID limits access only to the
Server Manager forms for a specified SuiteSpot server. Using a Web browser,
you can enter the URL of your domain followed by administrator port number. For
example, if your domain name is www.your-domain.com and the port number is
8301, you can browse to:
http://www.your-domain.com:8301
2.1.5.1 Setting Up a Netscape Enterprise Web Server
To set up a Web server, you need to be an Administrator superuser. After
successfully authenticating the user ID, the server will bring up the Server
Administration page as shown in Figure 20.
Installation of WebSphere and Associated Products
41
Figure 20. Server Administration Page in the Netscape Administration Server
In the General Administration section of this page, you can see a list of servers,
grouped by product name, along with the server’s status and its name. In this
section, you can either create, remove or configure servers. If you click Create
New Netscape Enterprise Server 3.61, the server will show a Server Manager
form for Netscape Enterprise Server Installation, as shown in Figure 21.
42
WebSphere Application Servers: Standard and Advanced Editions
Figure 21. Netscape Enterprise Server Setup Form
In this form, you can set up a Web server by providing the following information:
• The Server Name specifies your fully qualified domain name.
• The Bind address specifies an IP address that is not the default IP address to
be used for this Web server. This applies only if the machine supports multiple
IP addresses.
• The Server Port specifies the TCP port number where the Web server should
listen. The port number must be unique for each SuiteSpot server.
• The Server Identifier specifies the name of the server as seen in the Server
Administration page.
• The Document Root specifies the root directory for your Web documents.
After completing the form, click OK to create a new Web server.
2.1.5.2 WebSphere Plug-In for Netscape Enterprise on Windows NT
The WebSphere Application Server can run on top of a Netscape Enterprise Web
server by using a plug-in module. You should install this plug-in only after you
have set up the corresponding Netscape Enterprise server. In the WebSphere
installation process, the installation program will ask you to select the appropriate
Web server plug-in (see also Figure 42 on page 66). It will also ask for the
location of the Enterprise configuration file (see Figure 44 on page 67).
Installation of WebSphere and Associated Products
43
The Netscape Enterprise configuration file is:
<SuiteSpotRoot>\https-<ServerIdentifier>\config\obj.conf
The WebSphere installation program will automatically insert the following lines
inside the obj.conf file:
Init fn="load-modules" funcs="init_exit,service_exit,term_exit"
shlib="D:/WebSphere/AppServer/plugins/nt/ns35.dll"
Init fn="init_exit"
bootstrap.properties="D:/WebSphere/AppServer/properties/bootstrap.properties"
NameTrans from="/IBMWebAS/samples" fn="pfx2dir"
dir="D:/WebSphere/AppServer/samples"
NameTrans from="/IBMWebAS" fn="pfx2dir" dir="D:/WebSphere/AppServer/web"
The first line indicates that in the Web server initialization, the Web server should
load the WebSphere plug-in module, ns35.dll. The second line tells the Web
server to invoke init_exit method for initializing the module using specified
bootstrap properties. The third and fourth line specify directory aliases for the
WebSphere default document directories.
Normally, the obj.conf file is set by the Administration Server only. Therefore, after
installing WebSphere, you should apply these changes into the Web server. You
can do this by clicking the Apply button on any Server Manager form for the
corresponding Web server.
2.1.5.3 Setting Up Directory Alias
The Directory Alias function maps a URL path name, relative to the domain
name, into the path name of the directory that contains Web documents. To set
up the Directory Alias in Netscape Enterprise, you should log in to the
Administration Server as either a superuser or a Web server administrator. On
the top of the Server Manager form, click the Content Management button to
invoke the Content Management form, as shown in Figure 22. For now, we are
concerned with three of the items on the left side of the window:
1. Primary Document Directory - establishes the root directory for your Web
document primary tree. This root directory maps to your domain URL.
2. Additional Document Directories - specifies aliases into the root of secondary
document trees.
3. URL Forwarding - maps a URL path name, relative to the domain name, into
another URL.
44
WebSphere Application Servers: Standard and Advanced Editions
Figure 22. Content Management Form for Setting Up Directory Alias
2.1.5.4 Virtual Servers
Virtual servers are servers that have different addresses but refer to the same
Web server. You can set up virtual servers in the Content Management form
shown in Figure 22. Netscape provides you with two ways of creating this feature:
1. Hardware Virtual Servers
Several servers with different IP addresses (possibly with different domain
names) are located in the same machine and served by the same Web server.
To provide Hardware Virtual Servers, your machine must support multiple IP
addresses. Netscape Enterprise maps the Virtual Server IP address into the
Virtual Server root document directory.
2. Software Virtual Servers
Several servers with different domain names are served by the same machine,
the same IP address and served by the same Web server. Netscape
Enterprise maps Virtual Server domain name, in URL format, into the Virtual
Server root document directory.
2.1.5.5 Setting Up Access Control
Access Control determines which users can access specific Web documents and
what actions they can perform. To configure access control in Netscape
Enterprise, you log on to the Administration Server as a superuser or as the Web
server administrator. In the top frame of the Server Manager form, click the
Server Preferences button and select Restrict Access in the left-hand frame.
This will bring up the Access Control List Management form, as shown in Figure
23 on page 46. The Access Control List (ACL) is a set of rules that controls user
access to Web documents. Netscape Enterprise lets you create resource-based
ACLs or named ACLs.
Installation of WebSphere and Associated Products
45
• To create a resource-based ACL, choose the resources that you want to
protect in the Pick a resource field, by browsing the directory or supplying file
type wildcards. After that, click the Edit Access Control button to invoke the
Edit Access Control form as shown in Figure 24 on page 47.
• To modify an ACL, select the ACL from a drop-down list in the Pick an existing
ACL field, and click the corresponding Edit Access Control button.
• To create a named ACL, enter an ACL name in the Type in the ACL name field
and click the corresponding Edit Access Control button.
Figure 23. Restrict Access Form for Controlling User Access
When you click one of the Edit Access Control buttons, the server will show the
Edit Access Control form (Figure 24 on page 47). This form allows you to specify
Access Control rules. The form consists of two frames. The top frame is for
specifying rules, the bottom frame is for selecting parameter values.
The Access Control rules are specified by:
• Specifying rule action
Allow or deny action for users or machines that match the rule’s conditions.
• Specifying rule conditions that are based on:
• User/Group
46
WebSphere Application Servers: Standard and Advanced Editions
You can specify that the Web server authenticates the user with the user ID
and password against an authentication database. You can limit access to
only specified users or groups.
• Machine
You can enter host names or IP addresses as rule conditions.
• Specifying access rights for the following operations: read, write, execute, and
delete.
After specifying the rule, click Submit to activate the rule.
Figure 24. Editing Access Control Rules
2.1.6 Microsoft IIS V4.0
Microsoft Internet Information Server (IIS) is the Web server product in the
Microsoft Windows family. IIS V4.0 can be installed with the Windows NT 4.0
Option Pack. In this document, we don’t discuss the installation process for IIS.
We describe only some items that may be used in setting up the WebSphere
environment. You can read the IIS manuals that are available as HTML
documents from the Windows NT task bar.
Note: WAS supports IIS 3.0 but the Internet Service Managers interface is
different.
Installation of WebSphere and Associated Products
47
2.1.6.1 Managing Microsoft IIS
IIS provides easy-to-use utility tools for managing Internet services. The tool
comes in two forms:
1. As a part of Microsoft Management Console (MMC) (see Figure 25 on page
48), which you can access from Start > Program > Windows NT 4.0 Option
Pack > Microsoft Internet Information Server > Internet Service Manager.
Figure 25. Internet Service Manager Functions in Microsoft Management Console
2. As an IIS Internet Service manager Web application (Figure 26 on page 49),
which you can access by browsing the IIS Administrator site
htp://localhost:<port>. The <port> is the IIS Administrator port number. If you
do not know this port number, you can see it in the right frame of the Microsoft
Management Console.
The Web version of Internet Service Manager provides the same functions as
the Microsoft Management Console.
48
WebSphere Application Servers: Standard and Advanced Editions
Figure 26. IIS Internet Service Manager
2.1.6.2 Setting Up a Web Server
To set up a Web server, you can use either IIS Microsoft Management Console or
the Internet Service Manager Web application (Figure 26 on page 49). If you are
using the Web version of Internet Service Manager, the right frame of the Internet
Service Manager shows site structures for all sites in a particular machine
(localhost). To create a new Web server, you should be the local administrator
and perform the following steps:
• Select localhost in the right frame, then click New Web in the left frame.
• Enter the name of the new Web site and click OK .
• You should see your new Web site on the right frame of the Internet Service
Manager.
• At this point, you still can’t start the Web site, since you have not bound it to a
Web address.
• Double-click the new Web site to bring up the Web Site Identification form
(Figure 27 on page 50). Enter the IP address and port number for this Web
site. Then click Save.
Installation of WebSphere and Associated Products
49
Figure 27. Binding Web Address to New Web Site in IIS Internet Service Manager
• Your new Web site is now ready to be used. However, you still need to add
Web documents to this new site. This is described in the following section.
2.1.6.3 Configuring a Web Server
To configure a Web server, you can use either the IIS Microsoft Management
Console or the Internet Service Manager Web application. If you are using the
Web version of Internet Service Manager to configure the Web site directory,
perform the following steps:
• Double-click the Web site entry in site structures, then select Home Directory
on the left frame to bring up the Directory Properties form (Figure 28 on page
51).
• This form defines the mapping of a request to a particular physical location to
another URL. You can:
• Map the request to a physical directory in the local machine.
• Map the request to a shared directory in another machine.
• Redirect it to another URL.
50
WebSphere Application Servers: Standard and Advanced Editions
• In this form, the term Application represents the Document Root. The Starting
Point defines the root URL for this particular Document Root. The name in the
square brackets represents the root URL of the Web site.
Figure 28. Setting Directory Properties in IIS Internet Service Manager
2.1.6.4 WebSphere Plug-In for Microsoft IIS
WebSphere runs on top of IIS by using a plug-in. The plug-in for IIS is iis20.dll,
which is loaded when IIS starts. The WebSphere installation program will add the
following entries into the Windows registry:
\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\VirtualRoots
Name: "/IBMWebAS" Data: "D:\WebSphere\AppServer\web"
Name: "/IBMWebAS/samples" Data: "D:\WebSphere\AppServer\web\samples,,1"
Name: "/sePlugins" Data: "D:\WebSphere\AppServer\nt,,5"
\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\WebSphere Application Server\2.0
Name: "iisextensionloc" Data: "/sePlugins/iis20.dll"
These registry entries identify the location of the plug-in and specify the
WebSphere default root document directory.
Installation of WebSphere and Associated Products
51
2.1.7 DB2 Universal Database (UDB) for Windows NT
To work with the WebSphere application environment, the database system must
support Java. DB2 UDB comes with full Java support. It provides JDBC and SQLJ
drivers for a smooth integration of the WebSphere application server. Section 6.2,
“Using DB2 UDB for WebSphere Applications” on page 349 describes techniques
for accessing DB2 databases.
If your environment does not have DB2, the WebSphere installation will
automatically install DB2 Universal Database (UDB), but it is then limited to only
development purposes. For an end-user production environment, you should
obtain the DB2 package separately. For more information about DB2 products,
you can go to http://www.ibm.com/data/db2.
In this document, we don’t describe the installation of the DB2 products. We limit
our discussion to setting up DB2 in the WebSphere environment and configuring
the remote interface between the DB2 Client and DB2 Server components. For
more information about DB2 installation and setup guidelines, you can refer to the
Quick Beginnings for DB2 manual. This manual is also available as online
documentation after the DB2 UDB installation.
2.1.7.1 DB2 Products on Windows NT
DB2 delivers its database components in several products. For the Windows NT
platform, DB2 provides DB2 UDB, DB2 Client Application Enabler (CAE) and DB2
Software Development Kit (SDK). Each product contains a set of components.
Some of the components are included in more than one product.
DB2 UDB
On Windows NT, DB2 delivers DB2 UDB as the database server product. It
contains:
• The DB2 Server component, which provides the database engine and
run-time environment
• The DB2 Client component
• The DB2 Communication support component
• DB2 Java support components
In the DB2 environment, applications require DB2 Client components to access
the Server component. Practically, the DB2 Client component is the only interface
used for accessing the Server component. The applications are considered part
of the database client, even if they are running on the application server.
If you install DB2 UDB in the same machine as the Web server, you do not need
to install the client software. The DB2 UDB already includes the DB2 Client
component in the product.
If DB2 UDB and the Web Server are in different machines, you need a DB2 Client
component in the Web server and a remote connection between the client and
the DB2 Server. To service remote clients, DB2 uses the DB2 Communication
Support component. This communication infrastructure is available in several
protocols, including TCP/IP, APPC, NetBIOS and IPX/SPX.
DB2 UDB comes in several editions: DB2 for Workgroup, DB2 Enterprise Edition,
and DB2 Extended Enterprise Edition. Currently, the latest edition for Windows
52
WebSphere Application Servers: Standard and Advanced Editions
NT is DB2 UD2 5.2. The minimum DB2 level that has Java support is DB2 5.0.
The DB2 UDB installation CD also includes DB2 CAE and DB2 SDK.
DB2 Client Application Enabler (CAE)
Database client machines require DB2 CAE to provide DB2 client services. The
DB2 CAE contains:
• DB2 Client component
• DB2 Communication support
• DB2 Java support
To support various client platforms, DB2 provides CAE on various platforms. The
CAE is platform dependent, but provides the same functions across different
implementation platforms. DB2 CAE is available on the DB2 UDB installation CD
or from separate media for a particular platform.
DB2 Software Development Kit (SDK)
The DB2 SDK provides software and tools to build database applications using
DB2. The DB2 SDK contains:
• DB2 Client component
• DB2 Java support
Since DB2 SDK also includes the DB2 Client component, developers do not need
to install CAE separately.
2.1.7.2 Setting Up DB2 in WebSphere Environment
In the WebSphere environment, if you are installing the products separately you
should install the DB2 Client and DB2 Java support components. If you installed
WAS Advanced from the product CD, DB2 V5.2 is packaged with it and
automatically installed. Otherwise, DB2 Client and DB2 Java support are
available in the DB2 UDB, CAE and SDK products. If you install from the DB2
UDB installation CD, carry out the following steps:
• Log on as a local administrator.
• Run the DB2 installation program setup.exe from the installation CD.
• The installation program will ask you to select the appropriate DB2 products,
as shown in Figure 29 on page 54. If the data server and WebSphere are in
the same machine, select DB2 Universal Database. Otherwise, select either
DB2 Software Developer's Kit or DB2 Client Application Enabler.
Installation of WebSphere and Associated Products
53
Figure 29. Choosing Appropriate DB2 Products during DB2 Installation
Setting Up Java Environments
To use DB2 in the WebSphere environment, you need to add DB2 Java class
paths and native implementation library paths into the system environment and
WebSphere Java engine setup. The Java path information in the system
environment is required for the DB2 Client component or for developing
applications.
The class libraries are in the %DB2PATH%\java directory. The native
implementation library is in the %DB2PATH%\bin directory. If our DB2PATH is
D:\SQLLIB, we can add these paths into system variables using the following
steps:
• Invoke Windows NT System Properties dialog by using Start > Settings >
Control Panel > System > Environment .
• Select CLASSPATH from the System Variables list and append the following
entries into the Value text field:
D:\SQLLIB\java\db2.zip;D:\SQLLIB\java\sqlj.zip;D:\SQLLIB\java\runtime.zip
• Select PATH from the System Variable list and append the following entries
into the Value text field:
D:\SQLLIB\bin
• Click OK to save and apply the settings.
To add the path information into the WebSphere Java engine setup, follow these
steps:
• Log on to the WebSphere Administration Tool as an administrator.
• On the left frame, select Setup > Java Engine. This will bring up the Java
Engine setup dialog box as shown in Figure 30 on page 55.
• On the Paths tab, append the following entries into the Application Server
Classpath field:
D:\SQLLIB\java\db2.zip;D:\SQLLIB\java\sqlj.zip;D:\SQLLIB\java\runtime.zip
• Append the following entry into the User Libpath field:
54
WebSphere Application Servers: Standard and Advanced Editions
D:\SQLLIB\bin
• Click Save and log out from the Administration Tool.
• Stop and restart the Web server to activate the new settings.
Figure 30. Setting Up DB2 Java Path in WebSphere Administration Tool
2.1.7.3 Configuring Remote Interface
A remote interface is required if the application server and the database server
are not in the same machine. The remote interface links the DB2 Client
component to a remote database. Configuring a remote interface involves setting
up server communication profiles and defining a remote database connection in
the client machine.
Configure Server Communication Profile
For the TCP/IP protocol, a DB2 remote interface requires two TCP services: one
for the connection service and another for interrupt connection services. In
Windows NT, you can set these services using the DB2 Control Center, as shown
in Figure 31 on page 56, and follow these steps:
• Invoke this tool, by using Start > Programs > DB2 for Windows NT >
Administration Tools > Control Center. That will bring up the Control Center
main window.
• On the left frame, expand the machine node until you find the DB2 instance
that has the remote interface.
• Select the instance and right-click it to bring up a contextual pop-up menu.
From the menu, choose Configure. This will show the Configure Instance
dialog box as shown in Figure 32 on page 56.
Installation of WebSphere and Associated Products
55
• Select the Communications tab. The Control Center provides a list of
supported communication protocols, along with their current parameter
settings.
• Select the protocol (as an example, we selected TCP/IP ), and update the
TCP/IP Service name or use the supplied default service name.
• Click OK . In Windows NT, the Control Center will automatically allocate the
TCP port number for the service and allocate another port for the interrupt
connection service.
At that point, the database instance is ready for accepting remote connections.
Figure 31. DB2 Control Center
Figure 32. Configure Instance Dialog Box on DB2 Control Center
Setting Up a Remote Database Connection in DB2 Client
You can configure a DB2 Client by using the Client Configuration Assistant
(CCA). You can access this tool by invoking Start > Programs > DB2 for
56
WebSphere Application Servers: Standard and Advanced Editions
Windows NT > Client Configuration Assistant . To set up a remote database
connection, follow these instructions:
• On the CCA main dialog box, click the Add button to call the Add Database
SmartGuide window, which consists of a sequence of dialogs.
• In the first dialog box, select Manually Configure connection to a Database.
• The next dialog box will ask you to supply protocol parameters.
• The SmartGuide will show you a list of accessible databases in your network.
Choose a database to which you want to connect.
• The last dialog box asks for a database alias name. All applications in this
client machine will use that alias name to refer to the remote database.
• Click OK to save and activate the settings. That brings you back to the CCA
main dialog box.
At that point, the database should appear in the Available DB2 Database list. To
verify a connection, select a database and click the Test button. The system asks
you for a user ID and password. Then, a message will notify you if your
connection was successful.
Figure 33. Client Configuration Assistant
2.1.8 Lotus Domino R5 Server for Windows NT
Lotus Domino R5 Server is a family of servers that consists of integrated
messaging and Web application software and tools. There are three server
products in the family: Domino Mail Server, Domino Application Server, and
Domino Enterprise Server. These servers have a common architecture and can
be integrated smoothly to create a wide range of applications, from messaging,
collaboration, Web application, to mission-critical enterprise applications. In this
section, we limit our discussion to the Web server component of the Domino
Installation of WebSphere and Associated Products
57
Application Server. You can find more information about other Domino products,
components and features from its Web site at: http://www.lotus.com/r5.
Domino provides an HTTP engine (Web server) with its Application Server
product. The Web server provides other Domino servers the capability to deliver
services through the Web. WebSphere Application Server can utilize this Web
server and make use of some of the features of Domino servers. The integration
of WebSphere and Domino products is beyond the scope of this document. There
is a separate project that will address this integration.
To use the HTTP engine, you can either choose to install the Domino Application
Server product, or manually select the Domino Web Services component during
the custom installation (Figure 34 on page 58). For detailed installation
instructions, we recommend you use the Lotus Domino Yellowbook Setting up a
Domino Server, which is available online at http://www.notes.net/notesua.nsf.
Figure 34. Selecting Domino Web Services in Domino R5 Server Installation
2.1.8.1 Setting Up a Domino Web Server on Windows NT
In the Domino environment, the Web server is delivered as a part of a Domino
server. Therefore, to create a Web server, you should create a Domino server and
specify the server to provide Web services. To create a Domino server, perform
the following steps:
• Start Domino by using Start > Programs > Lotus Applications > Lotus
Domino Server from the Windows NT Taskbar. If you are creating a Domino
server for the first time, Domino will bring you directly to the setup.nsf
application (Figure 35 on page 59). This application consists of a sequence of
forms.
• In the first form for the Domino Server Setup, if you are creating a new server
for a new domain, select First Domino Server. If you are adding a new server
into an existing domain, select Additional Domino Server. Proceed to the
next form by clicking on the ">" button.
58
WebSphere Application Servers: Standard and Advanced Editions
Figure 35. Creating a New Domino Server using Domino Server Setup
• In the Select a Setup Method form (Figure 36 on page 60), select Advanced
Configuration , then go to the next form.
• In the Server Audience form (Figure 37 on page 61), choose the services that
you want to provide to your client. Select the HTTP check box to include Web
services.
• In the Administration Settings form (Figure 38 on page 62), specify a domain
name, Domino server name, fully qualified domain name as Server’s
Hostname, as well as the server’s administrator user ID and password.
• Click on Finish to create a new Domino server.
Installation of WebSphere and Associated Products
59
Figure 36. Select a Setup Method in Domino Server Setup
60
WebSphere Application Servers: Standard and Advanced Editions
Figure 37. Server Audience in Domino Server Setup
Installation of WebSphere and Associated Products
61
Figure 38. Administration Setting in Domino Server Setup
2.1.8.2 Domino Web Server Configuration Files
As an independent service component, the Domino Web Server has its own
configuration files: httpd.cnf and domino.cnf. When the Web server is started, it
generates domino.cnf from the Domino databases, then it reads domino.cnf and
httpd.cnf. As domino.cnf is system generated, you should not modify the file. The
domino.cnf contains Web service parameters from any Domino server service
that is delivered through the Web. The httpd.cnf contains parameters related to
general Web usage and other services outside the Domino server. You should not
put Web configurations for notes applications in httpd.cnf.
The procedure for configuring the httpd.cnf is the same as configuring the
Domino Go Webserver. Please see 2.1.4.1, “Configuring Domino Go Webserver”
on page 37.
2.1.8.3 WebSphere Plug-In for Domino R5 Server on Windows NT
The WebSphere Application Server can deliver its services through the Domino
Web Server by using a plug-in. The plug-in is go46.dll which is the same plug-in
62
WebSphere Application Servers: Standard and Advanced Editions
that is used for Domino Go WebServer. The Web service component of Domino
R5 is derived from the Domino Go WebServer.
You should install the plug-in only after you have set up the Domino Web Server.
The WebSphere installation program inserts the following lines into the Domino
Web server configuration file, httpd.cnf:
ServerInit D:\WebSphere\AppServer\plugins\nt\go46.dll:init_exit
D:\WebSphere\AppServer\properties\bootstrap.properties
ServerTerm D:\WebSphere\AppServer\plugins\nt\go46.dll:term_exit
Pass /IBMWebAS/samples/* D:\WebSphere\AppServer\samples\*
Pass /IBMWebAS/* D:\WebSphere\AppServer\web\*
The first line specifies the entry point for WebSphere services when the
WebServer starts. The third line specifies a function, term_exit, for terminating
the service. The fourth and fifth lines construct directory aliases for default
WebSphere directories.
2.1.8.4 Starting the Web Server Operation
To control Web Server operation, you can use the Domino server console, which
can be invoked from Start > Program > Lotus Applications > Lotus Domino
Server or by calling nservice.exe from a Windows console. The console allows
you to enter some commands after the > prompt:
04/22/99 11:36:52 AM Removing the version 0 free time data. Recreating it as
version 3.
04/22/99 11:36:52 AM Can't find existing Schedule database busytime.nsf,
creating a new one
04/22/99 11:36:53 AM SchedMgr: Validating Schedule Database
04/22/99 11:36:53 AM SchedMgr: Done validating Schedule Database
04/22/99 11:36:57 AM Stats agent started
04/22/99 11:36:57 AM Stats: Creating Mail-In Database record for stats
destination 'wsnt00 Stats/Itso'
04/22/99 11:36:57 AM Stats: Creating Stats Mail-In Database.
04/22/99 11:37:07 AM Creating Domino Web Administrator database...
04/22/99 11:37:08 AM DECS: Creating DECS Administrator database ...
04/22/99 11:37:12 AM Stats agent shutdown
04/22/99 11:37:13 AM Maps Extractor started
04/22/99 11:37:15 AM Setting up default monitors in Statistics & Events
database.
04/22/99 11:37:18 AM SMTP Server: Started
04/22/99 11:37:18 AM Maps Extractor: Building Maps profile
04/22/99 11:37:18 AM Maps Extractor: Maps profile built OK
04/22/99 11:37:18 AM DECS: DECS Administrator database created
04/22/99 11:37:21 AM DECS Server started
04/22/99 11:37:23 AM Domino Web Administrator database created
04/22/99 11:37:28 AM Database Server started
04/22/99 11:37:35 AM HTTP Web Server started
>
2.2 WebSphere Installation on Windows NT
To ensure a smooth installation process, before you install the WebSphere in your
machine, perform the following:
Installation of WebSphere and Associated Products
63
• Choose an edition of WebSphere Application Server that matches your
requirements. See 1.1.1, “WebSphere Application Server” on page 2 for a
comparison of the features of the different WebSphere editions.
• Make sure that all required hardware and software requirements are set up
and running in your machine. This includes a working JDK/JRE, Web browser,
Web server, and database system.
• You should set up TCP/IP properties such as Host Name, Domain Name, IP,
gateway and DNS addresses. Ensure that your Internet/intranet environment
works.
• Set up a local Administrator user ID to run Windows NT services. We
recommend you restrict access to the machine. You should follow your
company’s system security procedures.
• To minimize the risk for corrupting shared files, shut down the Web server on
which you want to install the WebSphere. Stop any running Windows
applications.
The installation process consists of a sequence of dialog boxes. After each dialog
box, you can proceed to the next dialog box by clicking the Next> button. If you
miss some information in a screen, you can always go back by clicking the Back>
button.
• The first installation dialog box (Figure 39 on page 65) warns you to stop any
running Windows program and Web server in your machine.
• In the next dialog box (Figure 40 on page 65), you have to specify a directory
to install. This directory will be the WebSphere Application Server root
directory.
• The next dialog box (Figure 41 on page 66) asks you to select the application
server components. Select any component that you need.
• The following dialog box (Figure 42 on page 66) lists the JDK or JRE installed
in your system. The installation program obtains this information from the
Windows NT registry. Choose a JDK/JRE system from the list. Choosing a
JRE only will prevent developers from working on the system. If you want an
alternative JDK/JRE, specify its directory.
• Choose an application server plug-in in the next dialog box (Figure 43 on page
67). The installation program will detect any installed Web server from the
registry. By default, selections for Apache and IBM HTTP servers are enabled.
If you have installed other Web server products, the dialog box will enable
selections on the corresponding product. If your Web server has a later
version than those listed in the dialog box, choose the latest plug-in version
available.
• Specify a folder to put the WebSphere programs. After that, click Next> to
start copying files.
• The installation program will take some time to install on your system.
• After it finishes, the installation program may ask you for the location of the
Web server configuration file (Figure 44 on page 67). For Domino Go
Webserver or Lotus Domino, the file is httpd.cnf; for Netscape Server the file is
obj.conf. IIS stores the configuration in the registry. For Apache or IBM HTTP
Server the file is httpd.conf.
64
WebSphere Application Servers: Standard and Advanced Editions
• In the last window you can read the readme.txt file or click Finish to complete
the installation.
• Reboot your computer, and WebSphere should be ready after the system is
up.
Figure 39. WebSphere Application Server on Windows NT Installation Welcome
Figure 40. WebSphere Installation on Windows NT Target Directory
Installation of WebSphere and Associated Products
65
Figure 41. WebSphere Installation on Windows NT - Choose Application Server Components
Figure 42. Select JDK or JRE
66
WebSphere Application Servers: Standard and Advanced Editions
Figure 43. Select Application Server Plug-In
Figure 44. WebSphere Installation on Windows NT - Specifying Web Server Configuration File
2.3 Infrastructure Installation for AIX V4.3.2
The following products were installed on AIX V4.3.2:
• JDK
• HTTP Server
• Domino Go WebServer
• Netscape SuiteSpot
• DB2 UDB
• Domino R5
2.3.1 JDK 1.1.6 Installation and Setup Procedure
This section will show you how to install a JDK on an AIX machine. You can
obtain the JDK for AIX from the WebSphere installation CD or by downloading it
Installation of WebSphere and Associated Products
67
from http://www.ibm.com/java/jdk. On the AIX platform, the JDK is available in tar
format. You need to uncompress it into a temporary directory before starting the
installation.
To perform the installation, you need to be a user that has root privileges. In an
AIX terminal window, enter the following command:
smitty installp
This will bring up the AIX System Management Interface Tool window and put you
at the Install and Update Software menu as shown in Figure 45 on page 68:
Install and Update Software
Move cursor to desired item and press Enter.
Install and Update from LATEST Available Software
Update Installed Software to Latest Level (Update All)
Install and Update Software by Package Name (includes devices and printers)
Install Software Bundle (Easy Install)
Update Software by Fix (APAR)
Install and Update from ALL Available Software
F1=Help
F2=Refresh
F3=Cancel
F9=Shell
F10=Exit
Enter=Do
F8=Image
Figure 45. JDK Installation on AIX - Install and Update Software Menu on smitty
Choose Install and Update from LATEST Available Software to invoke the
installation process. After that, enter the device or directory where the JDK
installation package is located, as shown in Figure 46 on page 69.
68
WebSphere Application Servers: Standard and Advanced Editions
Install and Update from LATEST Available Software
Type or select a value for the entry field.
Press Enter AFTER making all desired changes.
* INPUT device / directory for software
[/99swa109/JDK]
F1=Help
F2=Refresh
F3=Cancel
F4=List
F5=Reset
F6=Command
F7=Edit
F8=Image
F9=Shell
F10=Exit
Enter=Do
+
Figure 46. JDK Installation on AIX -Specifying Installation Source Directory
smitty will then let you choose which software components to install, as shown in
Figure 47 on page 69. Choose _all_latest and click Enter to start the installation.
Install and Update from LATEST Available Software
Type or select values in entry fields.
Press Enter AFTER making all desired changes.
* INPUT device / directory for software
/99swa109/JDK
* SOFTWARE to install
[_all_latest]
+
PREVIEW only? (install operation will NOT occur)
no
+
COMMIT software updates?
yes
+
SAVE replaced files?
no
+
AUTOMATICALLY install requisite software?
yes
+
EXTEND file systems if space needed?
yes
+
OVERWRITE same or newer versions?
no
+
VERIFY install and check file sizes?
no
+
Include corresponding LANGUAGE filesets?
yes
+
DETAILED output?
no
+
Process multiple volumes?
yes
+
F1=Help
F2=Refresh
F3=Cancel
F4=List
F5=Reset
F6=Command
F7=Edit
F8=Image
F9=Shell
F10=Exit
Enter=Do
Figure 47. JDK Installation on AIX - Confirmation before Starting the Installation
After it finishes, it will provide you with an installation summary at the bottom of
the command status screen, as shown in Figure 48 on page 70. You should verify
each component’s installation status.
Installation of WebSphere and Associated Products
69
COMMAND STATUS
Command: OK
stdout: yes
stderr: no
Before command completion, additional instructions may appear below.
[MORE...144]
Installation Summary
-------------------Name
Level
Part
Event
Result
--------------------------------------------------------------------------Java.rte.Dt
1.1.6.0
USR
APPLY
SUCCESS
Java.rte.Dt
1.1.6.0
ROOT
APPLY
SUCCESS
Java.adt.src
1.1.6.0
USR
APPLY
SUCCESS
Java.adt.includes
1.1.6.0
USR
APPLY
SUCCESS
Java.adt.docs
1.1.6.0
USR
APPLY
SUCCESS
Java.adt.src
1.1.6.1
USR
APPLY
SUCCESS
Java.adt.src
1.1.6.1
USR
COMMIT
SUCCESS
[BOTTOM]
F1=Help
F2=Refresh
F3=Cancel
F6=Command
F8=Image
F9=Shell
F10=Exit
/=Find
n=Find Next
Figure 48. JDK Installation on AIX -Installation Summary
Setting Environment Variable
After installation, the JDK will know the path to its own class libraries. To enable
the JDK to find other class libraries, you should set the system CLASSPATH
environment variable. You should also set the JAVA_HOME environment variable
to point to the base directory for the JDK, which is /usr/jdk_base by default.
You can set this variable in your current AIX session by using the export
command or put these commands into your login profile.
export CLASSPATH=$CLASSPATH:.:path1:path2:any path to class library
export JAVA_HOME=/usr/jdk_base
2.3.2 IBM HTTP Server V1.3.3 for AIX
For the AIX platform, you can obtain the IBM HTTP Server from the WebSphere
CD or obtain it in tar format from:
http://www.software.ibm.com/webservers/httpservers/download.html.
2.3.2.1 Installing IBM HTTPServer
To install the HTTP Server using the WebSphere installation CD, you should
select the IBM HTTP Server, the IBM HTTP Server plug-in as a component and a
sub-component to install. The WebSphere installation program will silently install
the HTTP Server and automatically modify the HTTP Server configuration file.
If you install the HTTP Server from a downloaded package, you should install the
HTTP Server first before installing WebSphere. The WebSphere installation
70
WebSphere Application Servers: Standard and Advanced Editions
program will insert plug-in information into the HTTP Server configuration file. To
install the HTTP Server separately, you should log on as a root user, and perform
the following steps:
• Uncompress the downloaded tar file using:
tar -xvf <tar-filename>
• Change directory to the directory that contains uncompressed results. If the
installation package table of contents (the .toc file) does not exist, create it
with the following command while still in the install directory:
inutoc .
• Call the AIX smitty utility for package installation:
smitty installp
• Specify the source directory of installation package, and click Enter to start
the installation. At the end of the installation process, you can verify the
installation status from the installation summary.
2.3.2.2 Configuring IBM HTTP Server
After the HTTP Server is installed, the basic tasks for configuring a Web Server
are:
• Specify your domain name and Web server port.
• Specify a directory alias.
• Specify your access control.
You can set up the Web server by editing the HTTP Server configuration file,
httpd.conf, which is located in /usr/lpp/HTTPServer/etc directory. The process for
modifying this file is the same as the HTTP Server setup in Windows NT platform.
Section 2.1.3.1, “Configuring IBM HTTP Server” on page 34 explains some basic
directives to control Web server behavior. You can refer back to this section for
configuring a Web server.
2.3.2.3 Controlling Web Server Operation
The HTTP Server provides a utility program, called apachectl, to control basic
Web server operations. The program is located in the /usr/lpp/HTTPServer/sbin
directory. The syntax for this utility is apachectl <command>. The <command>
argument can be: start, stop, restart, status, or configtest. As an example, the
following command starts the Web server:
apachectl start
To stop the Web server:
apachectl stop
2.3.2.4 WebSphere Plug-In for HTTPServer on AIX
Basically, the HTTP Server is an Apache Web server, which is built upon several
base modules. Each module provides a specific service. The WebSphere
Application Server delivers its service to the HTTP Server using a module (or
plug-in), named ibm_app_server_module. This module is implemented as an
object file, mod_ibm_app_server.so. When the HTTP Server starts, it loads and
starts the module. To enable the HTTP Server to recognize the module,
WebSphere inserts the following lines into the httpd.conf file:
Installation of WebSphere and Associated Products
71
LoadModule ibm_app_server_module
/usr/WebSphere/AppServer/plugins/aix/mod_ibm_app_server.so
WebSphere also inserts several directives, as listed below, to be passed into
ibm_app_server_module as initialization parameters:
NcfAppServerConfig BootFile
/usr/WebSphere/AppServer/properties/bootstrap.properties
NcfAppServerConfig LogFile /usr/WebSphere/AppServer/logs/apache.log
NcfAppServerConfig LogLevel TRACE|INFORM|ERROR
2.3.3 Domino Go Webserver
The Domino Go Webserver is a Web server product from Lotus. It is also known
as the IBM Internet Connection Server. The product is available on many
platforms, including Windows NT, AIX, Solaris, HP/UX, OS/2 and OS/390. Lotus
has integrated the Web server into its Lotus Domino R5 server family. It is the
Web Services component in the Domino R5 Application Server product. On the
AIX platform, you can obtain the Domino Go Webserver as a separate installation
package from IBM.
2.3.3.1 Configuring Domino Go Webserver
Domino Go Webserver provides Web-based configuration and administration
forms. You can access these online forms by accessing
http://<your.domain.name>/admin-bin/cfgin/initial, as shown in Figure 19 on
page 38. These forms are easy to use with a complete description as well as
examples for each parameter. As an alternative, you may configure the Web
server by using its configuration file which is httpd.cnf.
The procedure for configuring the Web server on AIX is the same as on the
Windows NT platform. Refer to 2.1.4.1, “Configuring Domino Go Webserver” on
page 37, for a list of basic configuration directives and the steps for setting up the
Web server.
2.3.3.2 WebSphere Plug-In for Domino Go Webserver on AIX
WebSphere can run on top of Domino Go Webserver by using a plug-in. For
Domino Go Webserver 4.x or later on AIX platform, the plug-in file is
libdomino.so.
During installation, the WebSphere installation program adds several entries into
the httpd.cnf file:
ServerInit /usr/WebSphere/AppServer/plugins/aix/libdomino.so:init_exit
/usr/WebSphere/AppServer/properties/bootstrap.properties
ServerTerm /usr/WebSphere/AppServer/plugins/aix/libdomino.so:term_exit
Pass /IBMWebAS/samples/*
/usr/WebSphere/AppServer/samples/*
Pass /IBMWebAS/*
/usr/WebSphere/AppServer/web/*
The first and second entries map server initialization and termination functions
into a corresponding API entry. The other entries are Websphere default mapping
rules.
2.3.4 Netscape SuiteSpot V3.X for AIX
The Netscape SuiteSpot for AIX is a family of server products that includes Web
server, directory server, proxy server, media server, and several other server
72
WebSphere Application Servers: Standard and Advanced Editions
types. The Web server product in the SuiteSpot family is the Netscape Enterprise
Server. In this section, we limit our discussion to the Enterprise Server.
SuiteSpot provides an Administration Server to configure any server in the family.
The Netscape SuiteSpot for AIX Administration Server is a Web service tool used
for configuring SuiteSpot servers. The Administration Server for AIX has the
same functions, look and feel as the Administration Server for Windows NT. The
process for setting up and configuring the Web server is the same as those
explained for the Windows NT platform, except for UNIX directory naming
conventions. See 2.1.5, “Netscape SuiteSpot V3.x for Windows NT” on page 41.
2.3.4.1 WebSphere Netscape Enterprise for AIX Plug-Ins
The WebSphere Application Server provides application services through a
Netscape Enterprise plug-in. The plug-in is loaded when the WebServer starts.
The Netscape Enterprise configuration file, obj.conf, specifies the name and
location of plug-ins. WebSphere’s installation program modifies this configuration
file. Since the configuration file is only available after you set up an Enterprise
Web server, you should install WebSphere after setting up the Web server. In the
WebSphere installation process, the installation program will ask you to select the
appropriate Web server plug-in and ask you for the location of the configuration
file.
In Netscape Enterprise for AIX, the configuration file is:
<SuiteSpotRoot>/https-<ServerIdentifier>/config/obj.conf
and the plug-in module is libnsXX.so, where XX is the Enterprise version number.
The WebSphere installation program will automatically insert the following lines
inside the obj.conf file:
Init fn="load-modules" funcs="init_exit,service_exit,term_exit"
shlib="/usr/WebSphere/AppServer/plugins/aix/libns35.so"
Init fn="init_exit"
bootstrap.properties="/usr/WebSphere/AppServer/properties/bootstrap.properties
"
NameTrans from="/IBMWebAS/samples" fn="pfx2dir"
dir="/usr/WebSphere/AppServer/samples"
NameTrans from="/IBMWebAS" fn="pfx2dir" dir="/usr/WebSphere/AppServer/web"
The first line indicates that in the Web server initialization, the Web server should
load the WebSphere plug-in module, libns35.so. The second line tells the Web
server to invoke init_exit for starting the module using specified bootstrap
properties. The third and fourth lines specify directory aliases for WebSphere
default document directories.
After the WebSphere installation, you should apply the changes in obj.conf into
the Web server. You can do this by clicking the Apply button on any Server
Manager form for the corresponding Web server.
Installation of WebSphere and Associated Products
73
2.3.5 DB2 Universal Database (UDB) for AIX
DB2 UDB products for AIX provide the same functions as DB2 UDB for Windows
NT platform. See 2.1.7, “DB2 Universal Database (UDB) for Windows NT” on
page 52 for a brief introduction of DB2 products and components.
DB2 UDB comes with full Java support. It provides JDBC and SQLJ drivers for a
smooth integration with the WebSphere application server. Section 6.2, “Using
DB2 UDB for WebSphere Applications” on page 349 describes techniques for
accessing the DB2 database.
DB2 UDB for AIX product packaging is the same as DB2 UDB on Windows NT. If
you install DB2 UDB and WebSphere on the same machine, you do not need to
install DB2 CAE. If DB2 UDB and WebSphere are on different machines, you
need to install DB2 CAE or SDK on the WebSphere machine and configure a
remote interface to the DB2 UDB server.
2.3.5.1 Setting Up DB2 in the WebSphere Environment
In the WebSphere environment, you should install the DB2 Client and DB2 Java
support components. Both components are available in DB2 UDB, CAE and SDK
products. Make sure that you select Java support in the DB2 setup program.
Setting Up Java Environments
To use DB2 in the WebSphere environment, you should add the DB2 Java class
paths and native implementation library path into the system environment and
WebSphere Java engine setup. The Java path information in the system
environment is required for the DB2 Client component or for developing
applications.
Add the following entries into the system CLASSPATH:
CLASSPATH=$CLASSPATH:${INSTHOME}/sqllib/java/db2java.zip
CLASSPATH=$CLASSPATH:${INSTHOME}/sqllib/java/runtime.zip
CLASSPATH=$CLASSPATH:${INSTHOME}/sqllib/java/sqlj.zip
export CLASSPATH
LD_LIBRARY_PATH=$(LD_LIBRARY_PATH):${INSTHOME}/sqllib/lib
export LD_LIBRARY_PATH
where INSTHOME is the DB2 instance home directory.
To add the path information into the WebSphere Java engine setup, follow these
steps:
• Log on to the WebSphere Administration tool as an administrator.
• On the left frame, select Setup > Java Engine. This will bring up the Java
Engine setup dialog box as shown in Figure 30 on page 55.
• On the Paths tab, append the following entries to the Application Server
Classpath:
D:\SQLLIB\java\db2.zip;D:\SQLLIB\java\sqlj.zip;D:\SQLLIB\java\runtime.zip
• Append the following entry to the User Libpath:
D:\SQLLIB\bin
• Click Save and log off from the Administration tool.
74
WebSphere Application Servers: Standard and Advanced Editions
• Stop the Web server and kill all WebSphere processes. You can get the
WebServer process identifier by using:
ps -ef | grep WebSphere
• Restart the Web server to activate the new settings.
Figure 49. Setting Up DB2 Java Path in WebSphere Administration Tool
2.3.5.2 Configuring Remote Interface
A remote interface is required if the application server and the database server
are not in the same machine. The remote interface links the DB2 Client
component to a remote database. Configuring a remote interface involves setting
up server communication profiles and defining a remote database connection in
the client machine.
Setting Up Server Communication Profile
DB2 UDB for AIX includes DB2 Communication Support components to enable
clients, either a local client component or a remote one, to communicate with the
DB2 Server. This communication component can support multiple communication
protocols concurrently. The protocol can be any combination of TCP/IP, APPC or
IPXSPX. You should have a System Administrative Authority (SYSADM) to set up
this service.
To identify which protocol to use, the system uses the DB2COMM environment
variable. To set DB2COMM enter the following command:
db2setup DB2COMM=TCP/IP
db2stop
db2start
After restarting, DB2 will have a new DB2COMM value.
Installation of WebSphere and Associated Products
75
The remote client interface requires two communication support services: one for
the connection service, and the other for the interrupt connection services. The
service parameters (name and addresses) are set according to the underlying
protocol service and address notation.
For TCP/IP communication services, there are two TCP/IP services that should
be set in the TCP/IP service configuration file: /etc/services file. Their port
numbering has the following restriction: if the port number for the connection
service is n, then the port number for interrupt connection service is n+1.
For example, to create conserv TCP/IP service on port 10000, put the following
lines into /etc/services file:
conserv 10000/tcp # DB2 interrupt connection service port
conservi 10001/tcp # DB2 interrupt connection service port
After these services are created, you need to make DB2 recognize these
services. You can do it by updating the database manager configuration with the
new connection service name. The system will automatically identify the interrupt
connection service by its port number:
db2 update database manager configuration using svcename <servicename>
db2stop
db2start
After restarting the database system, you can verify configuration values by
entering the following command:
db2 get database manager configuration
It will show the database manager configuration and it should contain the
following line:
...
TCP/IP Service name (SVCENAME) = <servicename>
...
Setting Up Remote Database Connection at DB2 Client
Setting DB2 client components is done by specifying a host address, indicating
service names involved and cataloging the TCP/IP node and database.
To specify the host address, create an entry in /etc/hosts to enable the system to
resolve host name into IP address. For example, insert the following line into
/etc/hosts:
9.24.104.68 hostnt00 #host address for serverhost
To specify the service offered by the server, the system must resolve the service
name into a port number. This is done by creating a new entry in the /etc/services
file:
conservice 10000/tcp # DB2 connection service port
To describe the remote node, you should catalog the node by issuing the catalog
command to DB2. For example, to catalog node nodent00 on remote host
hostnt00 using service name conservice with the TCP/IP protocol, enter the
following commands:
76
WebSphere Application Servers: Standard and Advanced Editions
catalog tcpip node nodent00 remote hostnt00 server conservice
terminate
Before a client can connect to a remote database, the client should catalog the
database. For example, to catalog the database sample at node nodent00, and
identify it locally as sample1, enter the following command:
catalog database sample as sample1 at node nodent00
terminate
2.3.6 Lotus Domino R5 Server for AIX
A brief introduction to Lotus Domino R5 is presented in 2.1.8, “Lotus Domino R5
Server for Windows NT” on page 57. Since we are going to work only with the
Web server installation for WebSphere, we only described setting up a Domino
Web server.
2.3.6.1 Setting Up a Domino Web Server on AIX
Creating a Web server on the Domino platform involved creating a Domino server
and specifying that an HTTP service is to be included in the Server. The server
setup application, setupweb.nsf, is a Web-based tool. To invoke the tool, perform
the following steps:
• Log in as a Notes user that owns the Domino data directory and Domino
server process. That user ID was set up during the Domino installation.
• Change the directory to the Domino data directory, for example,
/usr/lotus/notesdata.
• Start the HTTP engine and ask it to load the Domino Server Setup service by
giving httpsetup as the argument:
/usr/lotus/bin/http httpsetup
This will start the Domino Server Setup server, which is a Web-based
application located on port 8081.
• Open a Web browser and go to your domain site on port 8081. For example, if
the domain name is rs600031e.itso.ral.ibm.com, enter the following line into
Web browser location entry field:
http://rs600031e.itso.ral.ibm.com:8081
This will invoke Domino Server Setup in your Web browser as shown in Figure
50 on page 78.
At that point, the application has the same look and feel as the Domino Server
Setup on Windows NT. Follow the steps in 2.1.8.1, “Setting Up a Domino Web
Server on Windows NT” on page 58.
Installation of WebSphere and Associated Products
77
Figure 50. Domino Server Setup in AIX Platform is a Web Application
2.3.6.2 Domino Web Server Configuration Files
As an independent service component, the Domino Web Server has its own
configuration files: httpd.cnf and domino.cnf. When the Web server is started, it
generates domino.cnf from setup.nsf and other Domino databases. It then reads
domino.cnf and httpd.cnf. As domino.cnf is system generated, you should not
manually modify the file. The domino.cnf file contains Web service parameters
from any Domino server service that is delivered through the Web. The httpd.cnf
configures parameters related to general Web usage and other services outside
the Domino server. You should not put Web configuration for notes applications in
httpd.cnf.
The procedure for configuring the httpd.cnf is the same as configuring in Domino
Go Webserver. See 2.1.4.1, “Configuring Domino Go Webserver” on page 37.
2.3.6.3 WebSphere Plug-In for Domino R5 Server on AIX
The WebSphere Application Server can use the Domino Web Server to deliver its
services by using a plug-in. The plug-in is implemented as an object file,
libdomino.so. In the WebSphere installation, the installation program inserts the
following lines into httpd.cnf:
ServerInit /usr/WebSphere/AppServer/plugins/aix/libdomino.so:init_exit
/usr/WebSphere/AppServer/properties/bootstrap.properties
ServerTerm /usr/WebSphere/AppServer/plugins/aix/libdomino.so:term_exit
Pass /IBMWebAS/samples/*
/usr/WebSphere/AppServer/samples/*
Pass /IBMWebAS/*
/usr/WebSphere/AppServer/web/*
78
WebSphere Application Servers: Standard and Advanced Editions
When the Web server starts, it reads the httpd.cnf configuration file. The
ServerInit directive instructs the Web Server to load the plug-in. The Web Server
also reads additional Pass directives to create directory aliases for the default
WebSphere directory.
2.3.6.4 Controlling Web Server Operation
To control Web server operation, log in as a Notes user, and call the server from
an AIX terminal window:
$ server
Lotus Domino (r) Server, Release 5.0 (Intl), 30 March 1999
Copyright (c) 1985-1999, Lotus Development Corporation, All Rights Reserved
04/22/99 07:10:21
04/22/99 07:10:21
itso.ral.ibm.com
04/22/99 07:10:25
04/22/99 07:10:30
04/22/99 07:10:36
04/22/99 07:10:37
04/22/99 07:10:37
04/22/99 07:10:41
Domino Directory.
04/22/99 07:10:41
04/22/99 07:10:46
04/22/99 07:10:51
04/22/99 07:10:51
04/22/99 07:10:51
04/22/99 07:10:56
04/22/99 07:11:01
04/22/99 07:11:08
04/22/99 07:11:11
04/22/99 07:11:16
04/22/99 07:11:20
>
PM Mail Router started for domain ITSO
PM Router: Internet SMTP host rs600031e in domain
PM
PM
PM
PM
PM
PM
Database Replicator started
Index update process started
Agent Manager started
JVM: Java Virtual Machine initialized.
AMgr: Executive '1' started
rs600031e/Itso/us is the Administration Server of the
PM
PM
PM
PM
PM
PM
PM
PM
PM
PM
PM
Administration Process started
Calendar Connector started
Schedule Manager started
SchedMgr: Validating Schedule Database
SchedMgr: Done validating Schedule Database
Event Dispatcher started
Stats agent started
HTTP Web Server started
DECS Server started
Maps Extractor started
Database Server started
2.4 WebSphere Installation on AIX
To ensure a smooth installation process, before you install the WebSphere in your
AIX machine, do the following:
• Choose an edition of WebSphere Application Server that matches your
requirements. You can refer to 1.1.1, “WebSphere Application Server” on page
2 to compare features of WebSphere editions.
• Make sure that all hardware and software requirements are set up and running
on your machine. This includes working versions of JDK/JRE, Web browser,
WebServer, and database systems.
• Ensure that you have configured your TCP/IP environment correctly. Verify
your machine’s Host Name, Domain Name, IP, routing and DNS addresses.
Make sure that your Internet/intranet access from/to your machine is working
properly.
• You should have an AIX user ID for running the Web Server. WebSphere will
use the same user ID for executing its process. To install WebSphere
Application Server, you can either log in as a root or a user ID that can run the
Web Server.
Installation of WebSphere and Associated Products
79
The installation process consists of a sequence of dialog boxes. After each dialog
box, you can proceed to the next dialog box by clicking the Next> button. If you
miss some information in a screen, you can always go back by clicking the Back>
button.
• After the Welcome dialog box (Figure 51 on page 80), go to the next dialog
box.
• Specify a directory to install the WebSphere (Figure 52 on page 81). This
directory will be the WebSphere Application Server root directory.
• The next dialog box (Figure 53 on page 81) asks you to select the application
server components that you want to install. To select the Web Server on which
WebSphere will run, select Application Server form the list on the left and
select the appropriate Web server plug-ins on the right. If your Web server has
a later version than those listed in the dialog box, choose the latest plug-in
version available.
• The Installation program will ask you for the location of your Web server
configuration file (Figure 44 on page 67). For Domino Go Webserver or Lotus
Domino the file is httpd.cnf; for Netscape Server the file is obj.conf; for Apache
or IBM HTTP Server the file is httpd.conf.
• The installation program will take some time to install files into your system.
• After it finishes, in the last dialog box, you can choose to read the readme.txt
file or click Finish to complete the installation.
At that point, the Websphere Application server is ready. Go to the next section
for a first look at the WebSphere Application server.
Figure 51. WebSphere Application Server Installation on AIX - The Welcome Page
80
WebSphere Application Servers: Standard and Advanced Editions
Figure 52. WebSphere Installation on AIX - Specifying WebSphere Root Directory
Figure 53. WebSphere Installation on AIX - Selecting Components to Install
Installation of WebSphere and Associated Products
81
Figure 54. WebSphere Installation - Specifying Web Server Configuration File
Figure 55. WebSphere Installation on AIX - The Final Dialog Box
2.5 Using WebSphere for the First Time
After installing all of the infrastructure and WebSphere, it is time to take your first
tour of WebSphere.
You should try to verify that your installation worked. Open a Web browser and go
to the location: http://<hostname>/servlet/SimpleServlet. If the system is working,
it should shows a simple message " This is output from SimpleServlet". More
complex samples can be found in http://<hostname>/IBMWebAS/samples/. For the
time being, try to look at the WebSphere Administration tool.
The WebSphere Application Server Administration tool is a Web application for
configuring and monitoring the Application Server. To call this application, use
82
WebSphere Application Servers: Standard and Advanced Editions
your browser and go to http://<hostname>:9527. This will bring up the WebSphere
Administration tool login page (Figure 56 on page 83):
Figure 56. WebSphere Administration Tool Login Page
By default, the first time the user ID is admin and the password is also admin.
Enter the Administration tool by using that user ID and password. The
Administration tool (Figure 57 on page 84) consists of two frames. The left frame
is for navigation. The right frame is for configuration forms.
Installation of WebSphere and Associated Products
83
Figure 57. WebSphere Administration Tool
You can now configure WebSphere for the first time. You can set up the
WebSphere Java environment, which is an important configuration in
WebSphere. We also set up the Java environment in later chapters.
• On the left frame, click Setup to list Setup menus, then select Java Engine to
invoke the Java Engine configuration form (Figure 58 on page 85).
• On the Path tab, there are two important parameters: Application Server Class
Path and User Libpath.
• Append any additional Java library that your applications need into Application
Server Class Path. For example, add D:\SQLLIB\java\db2java.zip to the end of
Application Server Class Path.
• Append related native implementation library paths into User Libpath. For
example, use D:\SQLLIB\bin to inform the WebSphere the location of
db2jdbc.dll which is the native API for DB2 JDBC driver.
• After that, click Save and Log Off from the Administration tool.
84
WebSphere Application Servers: Standard and Advanced Editions
Figure 58. Setting Up Java Engine Configuration in WebSphere Administration Tool
Now explore several WebSphere directories that may be important when you are
deploying applications:
• <ASROOT>/classes is the root directory for your application classes.
• <ASROOT>/servlets is the root directory for servlets. You should put servlets
under this directory.
• <ASROOT>/lib contains WebSphere Java libraries. If you are not using
VisualAge for Java, you might need these libraries for developing Java
programs on WebSphere.
• <ASROOT>/plugins contains several plug-in modules such as plug-ins for
Web servers.
• <ASROOT>/web contains WebSphere’s own Web documents, help pages and
utility class libraries. It is not intended for storing your Web documents.
There are several property files under <ASROOT>/properties directory. In fact all
parameters configured using the WebSphere Administration tool are stored in
these property files. Some important property files are:
• <ASROOT>/properties/bootstrap.properties contains basic WebSphere
parameters.
• <ASROOT>/properties/ejs/ejs.properties contains EJB configurations.
• <ASROOT>/properties/server/servlet/servletservice/servlets.properties
contains servlet setup.
At this point, you are ready to use WebSphere Application Server.
Installation of WebSphere and Associated Products
85
2.6 Setting Up a Development System
WebSphere allows you to run servlets and Enterprise Java Bean (EJB)
applications, as well as general Web applications. In this environment, Java is the
underlying programming language. There are many Java development tools
available on the market. To develop applications in WebSphere, the tool should
support servlets, JSPs, and EJB application developments. If your application
requires enterprise access to various platforms and distributed components
technology, the tool should also have various connectors and CORBA support.
In general, we can divide Web application development into two main fields:
presentation and content generation. In developing presentation components,
you work with HTML, page layout, graphics, servlets, Java beans and multimedia.
In content generation, you deal mainly with data and transactions.
IBM comes with two solutions: a complete Java development tool, VisualAge for
Java for working with data processing and transaction logics, and WebSphere
Studio for working with presentation components.
VisualAge (VA) for Java enables you to create Web-enabled enterprise
applications with proven support for building Java components. It is available on
many platforms: OS/2, Windows NT, AIX, and OS/390. VA for Java is the best
choice for building applications that require strong integration with other IBM
products. For more information about VA for Java, you can visit
http://www.software.ibm.com/ad/vajava.
VA for Java 2.0 is now available. It includes:
• Visual servlet builder
• Tools for creating, testing and deploying EJB
• WebSphere Test Environment
• Enterprise Access Builder for various connectors
The WebSphere Studio provides tools to develop presentation components. The
WebSphere Studio 3.0 includes:
• Visual page designer that supports dynamic HTML and Java Server Pages
(JSP). You can visually design page layouts using HTML and JSP.
• Site construction management. You can import existing site contents, update
links automatically, archive a site into a single file and publish the site
information.
• Enhanced team development features that provide a common view of work
across the entire team and source control.
In this section, we describe how to set up a development environment for building
applications on top of WebSphere Application Server. We don’t discuss Java
programming techniques, and how to use the tools. For more information on that,
there are several IBM redbooks on VisualAge for Java programming. In particular,
you can read Programming with VisualAge for Java Version 2, SG24-5264 for an
introduction on VA for Java; or Using VisualAge for Java Enterprise Version 2 to
Develop CORBA and EJB Applications, SG24-5276 for developing EJB
applications. You can obtain these books online at http://www.redbooks.ibm.com.
86
WebSphere Application Servers: Standard and Advanced Editions
2.6.1 Setting Up VisualAge for Java
There are three editions of VA for Java 2.0: Entry Edition, Professional Edition
and Enterprise Edition. To develop applications in the WebSphere environment,
we recommend you use the Enterprise Edition of VA for Java 2.0. In addition, you
need to install the Enterprise Update for VisualAge for Java that you can obtain
from http://www.developer.ibm.com/java.
2.6.1.1 Adding Features into VA for Java
To develop applications in the WebSphere environment, you should add the
following VA for Java features into your work space:
• IBM EJB Development Environment 1.1
• IBM Servlet Builder 2.1
• IBM Servlet Builder Examples 2.1
• IBM Servlet IDE Utility Class Libraries 2.0.3
• IBM IDL Development Environment 2.0
• IBM IDL Development Environment Examples 2.0
• IBM WebSphere Test Environment 1.1
• IBM Common Connector Framework 2.0
• IBM Enterprise Access Builder 2.0
• IBM Enterprise CICS Access Builder Library 1.0
• IBM Java Record Library 2.0
• CICS Connector 3.0.1
• Encina Connector 2.1.1
To add these features to your work space, perform the following steps:
• In the Workbench, select File > Quick Start or press F2 to invoke the Quick
Start dialog box (Figure 59 on page 88).
• Select Features in the left pane and Add Features in the right pane.
• This will bring up a dialog box containing a list of additional features (Figure 60
on page 88). Select the features that you want to add and click OK .
Installation of WebSphere and Associated Products
87
Figure 59. Quick Start Dialog Box
Figure 60. Adding Features into VA for Java WorkBench
After installing the features, there will be a new tab sheet for EJB in the
Workbench (Figure 61 on page 89). In that sheet, you can create, test and deploy
EJB applications. For instructions on using this feature, see Using VisualAge for
Java Enterprise Version 2 to Develop CORBA and EJB Applications, SG24-5276.
88
WebSphere Application Servers: Standard and Advanced Editions
Figure 61. VA for Java Workbench
2.6.2 Setting Up and Using Command Line Session
As an alternative (though not recommended), some developers may occasionally
use a command line compiler and tools. It may be useful for:
• Integrating with third-party products such as using the SQLJ precompiler
(which is invoked from the command line).
• Debugging EJBs, which are developed using tools other than VA for Java, to
run on WebSphere EJS.
2.6.2.1 Setting Session CLASSPATH Variables
For compiling and running applications from the command line, you should set
the session CLASSPATH variables. For the Windows NT platform, create a batch
file with the following contents:
set
set
set
set
set
REM
REM
REM
set
REM
REM
REM
set
set
...
WASL=D:\WebSphere\AppServer\lib
DEPL=D:\WebSphere\AppServer\deployedEJBs
CLASSPATH=%CLASSPATH%;%WASL%\ibmwebas.jar;%WASL%\ejs.jar
CLASSPATH=%CLASSPATH%\%WASL%\jst.jar;%WASL%\jsdk.jar;%WASL%\xml4j.jar
CLASSPATH=%CLASSPATH%;%WASL%\databeans.jar
Put other Java libraries here ... e.g. for databases
CLASSPATH=%CLASSPATH%;D:\sqllib\java\db2java.zip
Put Your deployed EJB JAR files below ...
CLASSPATH=%CLASSPATH%;%DEPL%\HelloServer.jar
CLASSPATH=%CLASSPATH%;%DEPL%\<your_deployed_ejb_jar>
Installation of WebSphere and Associated Products
89
For the AIX platform, create a batch file with the following contents:
export WASL=/usr/WebSphere/AppServer/lib
export DEPL=/usr/WebSphere/AppServer/deployedEJBs
export CLASSPATH=$CLASSPATH:$WASL/ibmwebas.jar:$WASL/ejs.jar
export CLASSPATH=$CLASSPATH:$WASL/jst.jar:$WASL/jsdk.jar:$WASL/xml4j.jar
export CLASSPATH=$CLASSPATH:$WASL/databeans.jar
#
# Put other additional Java libraries here ... e.g for databases
#
set CLASSPATH=$CLASSPATH;/home/db2inst1/sqllib/db2java.zip
#
# Put Your deployed EJB JAR files below ...
#
export CLASSPATH=$CLASSPATH;$DEPL/HelloServer.jar
export CLASSPATH=$CLASSPATH;$DEPL/<your_deployed_ejb_jar>
...
Starting Enterprise Java Service (EJS) Manually
The EJS is WebSphere EJB Server. You can start EJS manually from the
command line. Before that, make sure that WebSphere is not running. To start the
EJS, perform the following steps:
• Change the directory to the WebSphere root directory.
• Set session CLASSPATH variables as listed above.
• Start the EJS Location Service Daemon:
java com.ibm.lsd.LocationServiceDaemon -ORBListenerPort <lsd_port>
where <lsd_port> is the Location Service Daemon listening port. For example:
java com.ibm.lsd.LocationServiceDaemon -ORBListenerPort 9029
• Start the EJS Persistent Name Server:
java com.ibm.CosNaming.PersistentNameServer -ORBBootstrapPort
<bootstarp_port> -ORBPersIORHostName <lsd_host_name> -ORBPersIORPort
<lsd_port> -InitialRoot <name_server_dir>
where <bootstrap_port> is the port on which to start the name service server;
<lsd_host_name> is Location Service Daemon server host name;
<name_server_dir> is a directory to contain Name Server data. For example:
java com.ibm.CosNaming.PersistentNameServer -ORBBootstrapPort 9019
-ORBPersIORHostName wsnt00.itso.ral.ibm.com -ORBPersIORPort 9029
-InitialRoot d:\EJSNameSpace
• Start the EJS Server
java -nojit com.ibm.ejs.server.EJServer -ORBPersIORPort <lsd_port>
-ORBBootstrapPort <bootstrap_port> -file <ejs_properties_file>
where <ejs_properties_file> is the fully qualified file name for WebSphere
EJS configuration file ejs.properties. For example:
java -nojit com.ibm.ejs.server.EJServer -ORBPersIORPort 9029
-ORBBootstrapPort 9019 -file
d:\WebSphere\AppServer\properties\ejs\ejs.properties
90
WebSphere Application Servers: Standard and Advanced Editions
Chapter 3. Content Presentation
The Web technologies that are available to present information to the client are
evolving at a rapid pace. First, there was HTML, which displayed only static
content. Shortly after that came Common Gateway Interface (CGI), a simple
protocol that can be used to communicate between Web forms and your
applications. It enabled dynamic content, with some programming languages
such as C and Perl. But CGI had trouble with its performance and scalability
because it started and ended processes for each request. This adversely affected
performance.
To solve this problem, other technologies were attempted. One of them used the
Web server’s APIs. That enabled the programs to run quicker, but it took a lot of
effort to develop the applications and they were unique to each vendor’s Web
server.
Another technology was Fast CGI. It is a high-performance extension of CGI,
using long-lived processes that are API-independent. But it was also hard to
develop because it required specific coding or configuration on each httpd server
or in each developer’s environment.
The servlet is a recent Java-based technology and it runs on the servlet engine. It
provides high performance and has many of the same advantages as Java. It has
portability and robustness, and provides security at run time. The servlet is
becoming more commonly used on Web applications. You can find more
information about servlets at:
http://java.sun.com/products/servlet/index.html
In addition to discussing servlets in this chapter, we explain and provide
examples of JSP coding and XML. This chapter shows how to use these new
technologies on WebSphere.
3.1 How to Deploy and Configure a Servlet
This section shows you the steps required to deploy servlets and configure
servlets in WebSphere Application Server V2.02. Most of these procedures
assume that you are logged on to the WebSphere Application Server
Administration interface using your administrator user ID and password. This can
be achieved by going to the Web address http://<hostname>:9527/ and typing
your user ID and password in the fields provided.
© Copyright IBM Corp. 1999
91
Figure 62. IBM WebSphere Application Server Administration Log In
Most of the time, the servlet is invoked from a link in HTML files (also JSP and
SHTML files). We show how to deploy servlets, including related HTML files in
this section.
To deploy a servlet on your application server perform the following steps:
1. Copy the class files to the application server.
2. Copy the related HTML, JSP, and SHTML files to the application server.
3. Use the Application Server Manager to configure initialization parameters and
set other options. This last step is optional.
3.1.1 Placing Class Files on the Application Server
By default, the application server looks for servlet class files in the servlet root
directory, <ASRoot>\servlets. The second step required to deploy the servlets
requires you to perform the following tasks:
• Put a copy of your compiled servlet class files in the servlet root directory.
• If the servlets are in a package, mirror the package structure as subdirectories
under the servlet\ or reloadable servlet directory. For example, if the servlets
SendMessage.class and GetMessage.class are in a package named
com.ibm.servlet.servlets.personalization.util, copy the servlets into the
92
WebSphere Application Servers: Standard and Advanced Editions
directory <ASRoot>\servlets\com\ibm\servlet\servlets\personalization\util as
shown in Figure 63:
Figure 63. The Servlets in a Package
• If your servlets import non-servlet classes that you developed, it is
recommended that you copy those classes to applicationserver_root\servlets.
• Standard out logging (Stdout) for all servlets goes to
<ASRoot>\ljvm_stdout.logs or to the Java console window, depending on the
settings in the bootstrap.properties file. See 8.2, “The Application Server
Debug Console” on page 418 for instructions on enabling Java standard out
logging.
For example, if you call the StdTest servlet shown in Figure 64 on page 94,
outputs for System.out.println are written to jvm_stdout.log and System.err.println
is written to the jvm_stderr.log.
Content Presentation
93
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class StdTest extends HttpServlet {
public void doGet (HttpServletRequest req, HttpServletResponse res) throws ServletException,
IOException
{
PrintWriterout;
res.setContentType("text/html");
out = res.getWriter();
out.println("<html>");
out.println("<head><title>StdTest</title></head>");
out.println("<body>");
out.println("<h1>StdTest</h1>");
out.println("See jvm_stuout.log & jvm_stderr.log<BR>");
out.println("</body></html>");
System.out.println("This is standard output.");
System.err.println("This is standard err.");
}
}
Figure 64. StdTest.java
null
Error finding default business: bean method raised unchecked exception;
nested exception is:
:
:
read properties file: can't find resource for IBMConnMgrTestStrings_en_US
This is standard output.
Figure 65. jvm_stdout.log
:
:
at com.ibm.servlet.engine.api.ServerEntry.service(Compiled Code)
at com.ibm.servlet.engine.nativeEntry.NativeServerEntry.service(Compiled Code)
at com.ibm.servlet.engine.outofproc.OutOfProcThread.run(Compiled Code)
This is standard err.
Figure 66. jvm_stderr.log
3.1.2 Placing HTML, JSP, and SHMTL Files on the Application Server
The next step in the process is to copy the HTML, JSP, and SHMTL files for the
servlet to the Web server's HTML document root directory, <DocRoot>. This
directory is determined by your specific server configuration (the settings for path,
alias, and virtual hosting rules).
You should code your servlets to use the method that returns the location of the
servlet's HTML file. For example:
ServletRequest.getRealPath("/my.html")
where "/my.html" is the name of the servlet's HTML file.
94
WebSphere Application Servers: Standard and Advanced Editions
The Web server document root directory is accessible from your Web browser by
opening the URL:
http://<hostname>//
You can copy HTML files into subdirectories relative to the document root
directory in:
<DocRoot>/morefiles
To open the HTML file from a browser, specify the relative directory in the URL.
For example, if you added the morefiles subdirectory under the document root
directory and placed an HTML file there (as shown in Figure 67), open the
following URL to view the file (Figure 68):
http://<hostname>//morefiles/myhtml.html
Figure 67. C:\Program Files\IBM HTTP Server\morefiles\myhtml.html
Figure 68. my.html Called by http://<hostname>/morefiles/myhtml.html
Content Presentation
95
3.1.3 Configuring a Servlet
The fourth step is to configure the servlets. If you want to load a servlet from a
JAR or SER file on a remote system (3.1.3.8, “Loading Remote Servlet” on page
103) or set servlet initialization parameters (see 5.3.1.3, “Creating Multiple Site
Queues in a Server” on page 288), use the Application Server Manager to
configure the servlet. You can also use it to implement the XML servlet
configuration.
Note: If your application server is running on Netscape Enterprise or Netscape
FastTrack Server under Sun Solaris and you specify a JAR file for the remote
load, be sure that the JAR file was created with the no compression flag (-0) set.
If compression was specified when the JAR file was created, the browser will
return an error 500 when you try to invoke the servlet.
3.1.3.1 Configuring Servlets
To see a servlet's settings, choose the servlet from the Servlet Names list on the
left side of the Configuration page. The servlet details display on the right side of
the page. You can add servlets to the list and modify information for servlets that
are in the list.
Servlet Details
Figure 69. Configuring Servlets
You can:
• Add servlets.
• Delete servlets.
• Modify servlets.
• Load servlets.
• Unload servlets.
96
WebSphere Application Servers: Standard and Advanced Editions
3.1.3.2 Adding Servlets
1. Click the Servlets -> Configuration page as shown in Figure 70 on page 97.
2. Click the Add button to display the Add a New Servlet dialog box as shown in
Figure 71 on page 98.
Figure 70. Add Button to Display the Add a New Servlet Dialog Box
3. In the Servlet Name field, enter the unique name of the servlet to add.
Content Presentation
97
Figure 71. Add a New Servlet
4. In the Servlet Class field, enter the name of the Java class for the servlet. This
name consists of the package name without the .class extension. For
example, sun.server.http.FileServlet is a valid class name for
sun.server.http.FileServlet.class.
5. Specify whether the servlet is a JavaBean. If it is, specify the full path to the
JAR file containing the bean. You can see this example in 3.1.3.3, “Adding
Bean Servlet” on page 99.
6. Optionally, use the Test button to confirm that the Application Server can find
your servlet. If you get a message that your servlet code can’t be found, check
the data you have entered.
7. Click the Save button.
8. You should see your servlet name appear in the Servlet Names field as shown
in Figure 72 on page 98.
Figure 72. Added Servlet
98
WebSphere Application Servers: Standard and Advanced Editions
3.1.3.3 Adding Bean Servlet
There is an interesting sample of Bean servlet in <ASRoot>/servletbean. We
show how to add a Bean servlet by adding this servlet:
1. Copy SampleBean.jar to <ASRoot>/servlets from <ASRoot>/servletbean.
2. Click the Add button on the Servlet Configuration page. The following dialog
box appears:
Figure 73. Add a New Servlet
3. Check Yes for the Bean Servlet option and specify the absolute path of the
SampleBean.jar file. In this case, it is
C:\WebSphere\AppServer\servlets\SampleBean.jar.
4. Click the Test button. If the Application Server can’t find the .jar file or
specified class in the .jar file, the following error message will appear:
Figure 74. "Test" Failed
If the Application Server finds the class, then the following message appears:
Figure 75. "Test" Succeeded
5. Click the Add button on the dialog box (Figure 73 on page 99). You can see
the SampleBean on Servlet Configuration page (Figure 76 on page 100).
Content Presentation
99
6. In the Servlet Properties field, the properties for the SampleBean are shown. When the
Bean is added it is introspected.
Figure 76. SampleBean Servlet Added on Configuration Page
7. When you invoke this servlet from the URL http://<hostname>//servlet/SampleBean you
should see the following window:
Figure 77. The Result of SampleBean Servlet
3.1.3.4 Modifying Servlets
In order to modify an existing servlet perform the following steps:
1. Click the Servlet Configuration page as shown in Figure 69 on page 96.
100
WebSphere Application Servers: Standard and Advanced Editions
2. From the Servlet Names column, select the servlet to modify.
3. Change the servlet settings.
The following window shows how to change property values for a Servlet
Bean. For Servlet Beans the buttons in this field are disabled. Since Beans
have their property definitions in their class files, it is logical that the field is
disabled. You can modify the value of the property by double-clicking the value
field as shown in Figure 78 on page 101:
Double-click here
Figure 78. How to Change Servlet Properties
4. Click the Save button.
5. Open http://<hostname>//servlet/SampleBean on your browser. The following
window appears:
Content Presentation
101
Figure 79. The Properties Can Be Changed from Servlet Configuration Page
After this modification you can see that SampleBean.ser was created in
<ASRoot>/servletbeans. This ".ser" file is an instance of the SampleBean.class
created with the Serialize technology of Java.
Figure 80. SampleBean.ser Was Created in <ASRoot>/servletbeans
The modifications to the Beans are reset after the Application Server goes down.
Modifying Load Options
You can set the servlet to load automatically at application server startup by
checking the Load at Startup option shown in Figure 81 on page 103.
The following items are reasons to load a servlet at startup time:
• The servlet takes time when loading because of its heavy init procedure and
you don’t want to affect the response time for users.
• The servlet needs an initial parameter to be explicitly specified.
• You shouldn’t load too many servlets at once. It takes a lot of resources and
causes overall performance to decline.
102
WebSphere Application Servers: Standard and Advanced Editions
Figure 81. Servlet Load Options
The Load Servlet Remotely option refers to the ability of the Web server to load
the servlet from a remote location. The servlet must be in a JAR file for remote
loading.
3.1.3.5 Deleting Servlets
To delete a servlet perform the following steps:
1. Click the Servlet Configuration page (shown in Figure 69 on page 96).
2. From the Servlet Names column, select the servlet to delete.
3. Click the Remove button.
4. Confirm the deletion by clicking Yes.
3.1.3.6 Loading Servlets
To load a servlet:
1. Click the Servlet Configuration page (shown in Figure 69 on page 96).
2. From the Servlet Names column, select the servlet to load.
3. Click the Load button.
3.1.3.7 Unloading Servlets
To unload a servlet:
1. Click the Servlet Configuration page.
2. From the Servlet Names column, select the servlet to unload.
3. Click the Unload button.
Note: Do not unload the invoker servlet. This is the servlet, called in every servlet
request, to "invoke" a servlet. If you unload this servlet, the next servlet call takes
time to invoke the invoker servlet and called servlet.
3.1.3.8 Loading Remote Servlet
You can copy the servlet class (JAR) file to a remote server and get the file when
it is needed. To set up the remote loading of a servlet:
1. Create a JAR file from the servlet class file.
Content Presentation
103
T>jar -cvf HelloWorldFromRs60004.jar HelloWorldFromRs60004.class
adding: HelloWorldFromRs60004.class (in=889) (out=521) (deflated 41%)
2. Copy HelloWorldFromRs60004.jar to the HTTP document directory on the
remote system (not in the servlet root directory). The remote server where you
placed the .jar file doesn’t have to be a WebSphere server.
3. The .jar file’s permissions must be set up as read for everyone.
rs60004:/usr/lpp/HTTPServer/share/htdocs > ls -la HelloWorldFromRs60004.jar
-rw-r--r-- 1 root
system
975 May 27 10:32 HelloWorldFromRs60004.jar
rs60004:/usr/lpp/HTTPServer/share/htdocs >
4. Add a new class.
Figure 82. Add a New Servlet
5. On the Servlet Load Options check the Yes option for the Load Servlet
Remotely field. In addition, specify the URL of the JAR file. In this example, it
is http://rs60004.itso.ral.ibm.com/HelloWorldFromRs60004.jar.
104
WebSphere Application Servers: Standard and Advanced Editions
Figure 83. Specify the Class File URL and Click the Save Button
6. Click the Save button and go to:
http://localhost/servlet/HelloWorldFromRs60004
7. The following window will appear:
Content Presentation
105
Figure 84. Remotely Load Servlet
3.1.3.9 Configuring Alternate Servlet Directories
You can put the servlet in other directories besides the <ASRoot>/servlets
directory. If you do that, you need to do some more customization.
To load servlets from an alternate servlet directory, you need to configure a
reloadable servlet directory. It is on the Paths tab of the Java Engine page (see
Figure 85 on page 107). You get there by clicking Setup -> Java Engine. The
servlet root directory is reloadable by default.
Specify the reloadable servlet classpath and click the Save button.
C:\WebSphere\AppServer\servlets2 is specified as the alternate directory in
Figure 85:
106
WebSphere Application Servers: Standard and Advanced Editions
Figure 85. Reloadable Servlet Classpath
After setting it you can invoke the servlet placed in the specified directory the
same way as you would invoke the servlet placed in the <ASRoot>/servlet
directory. For example, if you copy the HelloWorldServlet2.class to the
C:\WebSphere\AppServer\servlets2 directory, the HelloWorldServlet2 servlet can
be invoked by
http://<hostname>/servlet/HelloServlet2
See Figure 87.
Content Presentation
107
Figure 86. HelloWorldServlet2.class in C:\WebSphere\AppServer\servlets2 Directory
Figure 87. HelloWorldServlet2 Was Invoked from the Alternate Folder
3.1.3.10 How to Configure a Servlet Series (Chaining)
You can create a sequence of servlets in which each one appends additional
output to the results of the previous servlet. This is also known as chaining.
The following steps show how to create servlet chains by invoking
HelloWorldServlet and snoop from the following Web site:
http://<hostname>//servlet/ChainServlet
1. Open the Alias Page by clicking Servlets -> Aliases from the Application
Server Manager.
108
WebSphere Application Servers: Standard and Advanced Editions
Figure 88. Aliases Page
2. Click the Add button. A new row will be added in the table.
Table 7. The Values to Configure Servlet Series
Alias
/servlet/ChainServlet
Servlet Invoked
HelloWorldServlet,snoop (with no space)
3. Update the fields with the correct values (see Figure 89):
Figure 89. Edit Row Values and Click Save
4. Click the Save button (see Figure 89).
Content Presentation
109
5. Open http://<hostname>//servlet/ChainServlet with your browser. The
following window appears:
Figure 90. Series Servlets (HelloWorldServlets,snoop)
3.1.3.11 Servlet Filtering
Servlet filtering takes the output of a servlet and uses it as the input of another
servlet. This is useful for translation or substitution. For example, you can use this
to translate XML to HTML. You can add specific values to your servlet.
Servlet filtering is disabled by default because it uses a lot of resources and
causes performance reduction. To enable filtering, do the following:
1. Modify httpd.properties in <ASRoot>/properties/server/servlet/httpdservice.
Change enable.filters property from false to true.
110
WebSphere Application Servers: Standard and Advanced Editions
#
# Common properties for HTTP and HTTPS services
#
service.vendor=Sun Microsystems
service.version=1.0
# Default HTTP processing pipeline definition:
pipeline.state.class=com.sun.server.http.HttpProcessingState
pipeline.stages=resolver, runner, logger, reporter
pipeline.stage.resolver.class=com.sun.server.http.stages.Resolver
pipeline.stage.runner.class=com.sun.server.http.stages.Runner
pipeline.stage.logger.class=com.sun.server.http.stages.Logger
pipeline.stage.reporter.class=com.sun.server.http.stages.Reporter
# Enable/disable service features
enable.acls=true
enable.browseDirs=false
enable.filters=true
enable.proxy=false
enable.urlLoading=false
enable.virtualHosts=true
:
Figure 91. Part of httpd.properties (<ASRoot>/properties/server/servlet/httpdservice)
2. Modify httpd.properties in <ASRoot>/properties/servlet/servletservice. Edit
the pipeline.stages property, that is uncomment the statement for filtering
support and comment out the statement that indicates no filtering support.
#
# Properties for HTTP
#
service.vendor=IBM
service.version=1.1
# Default HTTP processing pipeline definition:
pipeline.state.class=com.sun.server.http.HttpProcessingState
No
Filtering
Filtering
#Stages for servlet processing (no filtering support)
#pipeline.stages=resolver, runner, reporter
#Stages for servlet processing (with filtering support)
pipeline.stages=resolver, filter, runner, reporter
pipeline.stage.resolver.class=com.ibm.servlet.personalization.sessiontrack
ing.IBMResolver
pipeline.stage.runner.class=com.sun.server.http.stages.Runner
pipeline.stage.reporter.class=com.sun.server.http.stages.Reporter
pipeline.stage.filter.class=com.sun.server.http.stages.FilterManager
pipeline.stage.debug.class=com.sun.server.http.stages.Debug
:
Figure 92. A Piece of httpd.properties (<ASRoot>/properties/servlet/servletservice)
Content Presentation
111
Click the Servlets -> Filtering page from the Application Server Manager. This
brings up the following window. Click the Add button and specify the servlet name
and MIME type used to filter (Figure 93 on page 112):
Figure 93. Filtering Setting Page
3. Click Save. This change is saved to
<ASRoot>/properties/servlet/servletservice/mimeservlet.properties file
(Figure 94 on page 112):
# This file maps mime-types to the servlets which process them
# This is used by the filter manager to set up chains of servlets
# where the output of one servlet gets piped to the input of
# another servlet based on the mime-type that the servlet specifies
# with setContentType("mime-type")
#
# The default servlet for all mime-types is file. Do not set this
# explicitly.
#
# Entries in this file should be of the form
# mime-type/servletname
# ie.
# foo/bar=fooServlet
# where fooServlet is defined in servlets.properties
java-internal/parsed-html=pageCompile
toSimpleFilterServlet/filter-html=SimpleFilterServlet
Figure 94. mimeservlet.properties
112
WebSphere Application Servers: Standard and Advanced Editions
4. mimeservlet.properties is also in <ASRoot>/properties/servlet/httpservice/. If
you cannot find the MIME type in this file, modify this file and the file shown in
Figure 94 on page 112. In that case, the Application Server probably needs to
be restarted.
5. Two files are used as filtering samples in this part.
• SimpleFilterServlet.java is the servlet-specified filtering setting. This
servlet opens an input stream using HttpServletRequest.getInputStream().
See Figure 95 on page 114. Capitalize the characters from the input
stream, and write to the output stream.
• FilteredServlet.java is the servlet output HTML code with MIME type
specified in the configuration.
Content Presentation
113
import
import
import
import
java.io.*;
java.util.Enumeration;
javax.servlet.http.*;
javax.servlet.*;
public class SimpleFilterServlet extends HttpServlet {
public void service(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException
{
try {
//append a header to the response
res.setHeader("filtered-by", "SimpleFilterServlet");
//set the desired content-type of the filtered data
// res.setContentType("text/plain");
res.setContentType("text/html");
//Transfer the header.
String headersString = "";
Enumeration e = req.getHeaderNames();
while (e.hasMoreElements()) {
String header = (String)e.nextElement();
String value = req.getHeader(header);
headersString += header + ": " + value + "\n";
if (!header.equals("Content-Type")) {
res.setHeader(header, value);
}
}
//Warning: getWriter() will flush the stream and thus write the
headers
//
so we must put this below the set header methods.
PrintWriter out = res.getWriter();
//WAS 2.0 and 2.01 had a bug that caused getReader() to throw a
NullPointerException
//WAS 2.02 has fixed this problem
BufferedReader in = new BufferedReader(new
InputStreamReader(req.getInputStream()));
//Xfer and capitalize all of the data from the previous servlet
String line = in.readLine();
while(line != null){
out.println(line.toUpperCase());
line = in.readLine();
}
out.flush();
out.close();
}
catch (Throwable th) {
th.printStackTrace();
}
}
}// Thanks to Spike
Figure 95. SimpleFilterServlet.java
114
WebSphere Application Servers: Standard and Advanced Editions
import javax.servlet.*;
import javax.servlet.http.*;
import java.io.*;
public class FilteredServlet extends HttpServlet {
public void service(HttpServletRequest req, HttpServletResponse res)
throws IOException {
res.setContentType("toSimpleFilterServlet/filter-html");
PrintWriter pw = res.getWriter();
pw.println("<head>");
pw.println("<title>FilteredServlet </title>");
pw.println("<body>");
pw.println("<h2>This is the output of FilteredServlet</h2>");
pw.println("---------------------------------<br>");
pw.println("1234567890<br>");
pw.println("abcdefghigklmnopqrstuvwxyz<br>");
pw.println("---------------------------------<br>");
pw.println("</body>");
pw.flush();
}
}
Figure 96. FillteredServlet.java
6. Create SimpleFilterServlet.java and FilteredServlet.java and compile them.
C:\WebSphere\AppServer\Servlets>javac SimpleFilterServlet.java
C:\WebSphere\AppServer\Servlets>javac FilteredServlet.java
C:\WebSphere\AppServer\Servlets>
7. Copy the class files into <ASRoot>/servlets.
8. Open http://<hostname>/servlets/FilterdServlet.
9. If your browser begins downloading(), the MIME setting doesn’t work properly.
Try restarting the Application Server to enable these settings.
Figure 97. Download the File
10.The following window is the result of filtering. All the character output from
FilteredServlet was capitalized (see Figure 98 on page 116).
Content Presentation
115
Figure 98. The FilteredServlet Was Filtered and Capitalized by Simple FilterdServlet
3.1.4 Monitoring Servlets
You can see the Loaded Servlets with the Application Server Manager. You don’t
need any configuration information, as mentioned in 3.1.3, “Configuring a Servlet”
on page 96.
From the initial screen, select Server Execution Analysis -> Monitors ->
Loaded Servlets which leads you to the following window:
Figure 99. Loaded Servlet Monitor
116
WebSphere Application Servers: Standard and Advanced Editions
Table 8. Loaded Servlets Monitor Values
Field
Comment
View
Which servlets to view: servlets you started (user), internal (system)
servlets, active servlets, or all of the servlets known to the service.
Name
The servlet name or alias. If a servlet has multiple aliases, more than
one row in the table might provide statistics for that servlet. Use the
Class Name and Path columns to determine if multiple rows apply to
the same servlet.
Requests
The number of requests for the servlet, as received by IBM
WebSphere AS since the time the servlet was loaded.
Avg Run Time
The cumulative total number of seconds for all requests to the servlet
since it was loaded. The average time a servlet spent in service
method such as service(), doGet(), or doPOST(). A new average time
is calculated each time the Loaded Servlets page is updated. The time
is displayed in hh:mm:ss.ms format.
State
The state of the servlet during the current update interval. The possible
states are:
idle - The servlet is available and is not active.
init() - The servlet is initializing.
service() - The servlet is performing its services.
destroy() - The servlet is stopping.
If the servlet is in any state other than idle for many update intervals,
suspect a problem with the servlet.
Auto Start
Whether the servlet is configured to load automatically when this
service starts (indicated by a check mark) or load when requested
(indicated by a blank).
Auto Reload
Whether the servlet is automatically reloaded whenever the service
detects a change in the servlet file (indicated by a check mark). The
service automatically reloads servlets that are in the monitored
directories for servlets and servlet beans. The default monitored paths
are <ASRoot>\servlets and <ASRoot>\servletbeans, where
<ASRoot> is the directory where Application Server is installed.
Internal (system) servlets are not in the monitored paths.
Remote
Whether the servlet was loaded from a remote system (indicated by a
check mark) or the local system (indicated by a blank). Remote
servlets are loaded in a security sandbox.
Loaded Time
The date and time the servlet was most recently loaded.
Class Name
The servlet class name.
Path
The directory path for the servlet .class file. If the class file is in a JAR
file, the path for the JAR file is listed.
Content Presentation
117
Figure 100. User View Option Checked
Figure 101. Internal View Option Checked
118
WebSphere Application Servers: Standard and Advanced Editions
Figure 102. Active View Option Checked
There is an Active View option, but it does not seem to work properly. The state of
the monitor is the same as that of the All View option that was checked. This will
be fixed in V3.0.
Content Presentation
119
3.2 Java Server Pages
Java Server Pages (JSP) is a relatively new technology developed by Sun
Microsystems. It looks like HTML files, but in JSP you can embed the results from
servlets and Beans. You can also write Java code in JSP. That enables you to
separate the HTML coding from the business logic in your Web applications.
WebSphere Application Server implemented JSP before the official
announcement and support from Sun Microsystems. When we were writing this
part, Sun Microsystems announced JSP V1.0. WebSphere V2.02 used V0.91 of
JSP.
For more information, please refer to the following:
• JavaServer Pages (JSP)
http://[hostname]/IBMWebAS/doc/whatis/icjsp.html
• JavaServer Pages (JSP) reference
http://[hostname]/IBMWebAS/doc/whatis/icjspref.html
• JavaServer Pages from Sun Microsystems (in the WebSphere documentation)
http://java.sun.com/products/jsp/
3.2.1 JSP Architecture
In a JSP environment, most requests are sent to JSP files. Figure 103 on page
121 is a diagram showing the JSP processing flow.
The following list numbers correspond to the numbers in Figure 103 on page 121:
1. The HTTP client sends a request to httpd.
2. JSP sends a request to the servlet instance.
In case there are no servlet instances of the JSP file in JVM:
• The JSP processor(pageCompile) dynamically compiles the JSP file into a
Java file and class file (in case files do not exist).
• The JSP processor generates the servlet instance from the compiled class
file.
3. Servlet execute process - send answers back to JSP, or to the client (3’).
4. HTTP client receives the JSP embedded result from the servlet, or the result
from the servlet.
120
WebSphere Application Servers: Standard and Advanced Editions
Figure 103. JSP Processing Flow
The JSP processor (pageCompile) puts the .java and the .class files in the
servlets\pagecompile\_(JSP_URL) directory, if the JSP file is called by
http://<hostname>/IBMWebAS\samples\XtremeTravel\bookit.jsp. The .java and .class
files are put in
<ASRoot>\servlets\pagecompile\_IBMWebAS\_samples\_XtremTravel\
Content Presentation
121
Figure 104. Processed JSP File
The .java and the .class file have the same file name. The processor uses a
naming convention that includes adding underscore characters and a suffix to the
JSP file name. For example, if the JSP file name is bookit.jsp, the generated files
are _bookit_xjsp.java and _bookit_xjsp.class as shown in Figure 104 on page
122.
3.2.1.1 JSP Access Models
There are two ways to access JSP files:
1. Access Model 1: Request to JSP, Response from JSP (Figure 105 on page
122).
In this model, Web clients send and receive the requests and responses via a
JSP file. A JSP creates servlets and Beans to communicate to back-end
systems, if needed.
Figure 105. JSP Access Model 1
122
WebSphere Application Servers: Standard and Advanced Editions
2. Access Model 2: Request to Servlet, Response via JSP (Figure 106 on page
123)
In this model, Web clients send requests to the servlet. The servlet
communicates to back-end systems, puts the result into a Java object (usually
a Bean), and passes the object to a JSP file. The servlet uses the
com.sun.server.http.HttpServiceResponse callPage() method at that time.
Figure 106. JSP Access Model 2
This approach enables you to separate content generation (business logic) from
the presentation of the content (HTML formatting). This separation enables
servlets to generate content and store the content (for example, in a Bean) in the
request context. The servlet that generated the context generates a response by
passing the request context to a JSP file that contains the HTML formatting.
3.2.2 JSP File Contents
JSP files have the extension .jsp. A JSP file contains combinations of:
• HTML tags
JSP supports all valid HTML tags. Refer to your favorite HTML reference for a
description of those tags.
• NCSA tags
The Application Server supports the following NCSA tags through JSP:
•
•
•
•
•
•
config
echo var=variable
exec
filesize
include
lastmodified
Content Presentation
123
• Commands for formatting size and date outputs
• <SERVLET> tags
See 3.2.3, “<SERVLET> Tags” on page 124.
• JSP Syntax
See the 3.2.4, “JSP Syntax” on page 127.
3.2.3 <SERVLET> Tags
<SERVLET> tags are used to invoke the servlet from JSP. It is useful to embed
partial HTML from the servlet to your Web page. The syntax of these tags is:
<SERVLET NAME="servlet_name" CODE="servlet_class_name"
CODEBASE="URL_for_remote_loading" initparm1="initparm_value">
<PARAM NAME="param_name" VALUE="param_value">
</SERVLET>
Table 9. Summary Information of <SERVLET> Tag Attributes
Attributes
Comment
NAME
The servlet class name without .class extension. This can be
configured also using the Application Server. See 5.3.1.3, “Creating
Multiple Site Queues in a Server” on page 288. You can omit this
attribute if CODE attribute is specified. In that case, an instance of the
servlet with NAME=CODE is created.
CODE
The servlet class file name. This is optional. See below for tips.
CODEBASE
The URL of the JAR file placed on the remote machine.
parameter
The name and value of initialization parameters.
<PARAM>
tag
The name and value of the parameters that are passed through a
Request object of the servlet service() method.
Note: The CODE attribute is optional, but when you load a servlet from a remote
system, it is not optional. If you drop this attribute, you see a familiar error
message (Figure 107 on page 125). If you configure the remote loading of the
servlets option on the Servlet Configuration page (in the Application Server
Manager), you can load the servlet by specifying the NAME attribute of the
<SERVLET> tag. To configure the remote loading of servlets, see 3.1.3.8,
“Loading Remote Servlet” on page 103.
124
WebSphere Application Servers: Standard and Advanced Editions
Figure 107. 500 Internal Server Error
This is sample code to show <SERVLET> tags loading a servlet file from the
remote system.
<html>
<head>
<title>Remote Servlet</title>
</head>
<body>
<H1>Remote Servlet</H1>
<HR>
<SERVLET NAME="Greeing"
CODE="GutenMorgen.class"
CODEBASE="http://rs60004.itso.ral.ibm.com/GutenMorgen.jar">
</SERVLET>
</body>
</html>
Figure 108. Remote.jsp
1. Copy RepeatTest1.jsp to your HTTP document root. In the default setting of
IBM HTTP Server1.3.3 on Windows NT, it is located at \Program Files\IBM
HTTP Server\htdocs.
2. Create a JAR file from the servlet class file.
>jar -cvf GutenMorgen.jar GutenMorgen.class
adding: GutenMorgen.class (in=845) (out=501) (deflated 40%)
Content Presentation
125
3. Copy GutenMorgen.jar to the HTTP document directory on the remote system
(not the servlet root directory). The remote server where you place the .jar file
doesn’t have to be a WebSphere server.
4. The permissions for the JAR file must be set to read for everyone.
rs60004:/usr/lpp/HTTPServer/share/htdocs > chmod a+r *.jar
rs60004:/usr/lpp/HTTPServer/share/htdocs > ls -la G*.jar
-rw-r--r-- 1 root
system
927 Jun 2 18:00 GutenMorgen.jar
5. Open URL http://<hostname>/Remote.jsp The following window will appear:
Figure 109. The Result of Remote.jsp
6. Click Servlet Execution Analysis -> Monitors -> Loaded Servlets and go to
the Loaded Servlets Monitor page from the Application Server Manager. You
can see that the Greeting instance is created from the GutenMorgen.class
(Figure 110 on page 126).
Figure 110. The Greeting Instance Was Created
The sample <SERVLET> tags are also in 5.3.1.2, “Showing Bulletin” on page
287 and 5.3.2.1, “Sample Model of Message Exchanging” on page 296.
126
WebSphere Application Servers: Standard and Advanced Editions
You can find detailed explanations about <SERVLET> tags at:
http://<hostname>//IBMWebAS/doc/howto/itinvsv.html#invshtml
3.2.4 JSP Syntax
JSP syntax consists of the following format:
• <%@ and %> Tags (JSP Directives)
• <SCRIPT> and </SCRIPT> Tags
• <% and %> Tags (Inline Java Code, Scriptlets)
• <%= and %> Tags (Java Expressions for Variable Data)
• <BEAN> Tag (Accessing JavaBeans)
• <INSERT> Tag (For Embedding Variables in an HTML Page)
• <REPEAT> Tags (For Repeating a Block of HTML tagging)
You can get detailed information about JSP syntax from
http://<hostname>/IBMWebAS/doc/whatis/icjspref.html.
The references in the WebSphere documentation are located at:
http://www.javasoft.com/products/jsp/index.html
You can also get JSP information from:
http://www.javasoft.com/products/jsp/JSP-1_0-public-draft-1.pdf
3.2.4.1 <%@ and %> Tags (JSP Directives)
In Figure 111 on page 128, you can find the expressions enclosed within <%@
and %>. This syntax is called JSP directives. JSP directives are used to specify:
• The scripting language being used
• The interfaces a servlet implements
• The classes a servlet extends
• The packages a servlet imports
The general syntax of the JSP directives is:
<%@ directive_name ="value" %>
In JSP directives, the following six directives are valid as directive names:
language, method, import, content_type, implements, extends
With JSP directives, you define basic settings (for example, language or method)
for the code generated from JSPs:
• Language
The language directive defines the scripting language used in this file. At this
time, only Java is valid and it is set as the default.
• Method
This is the method of servlet code generated from a JSP file. The default
method is service.
Content Presentation
127
• Import
You can import Java language packages just like writing a servlet. This
directive can be specified multiple times within a JSP file to import different
packages.
• Content_type
This is the MIME type of the generated response. The default value is
text/html.
• Implements
This is a comma-separated list of Java language interfaces that the generated
servlet implements. You can use this directive more than once within a JSP file
to implement different interfaces.
• Extends
This is the name of the Java language class that the servlet extends. The
class must be a valid class and does not have to be a servlet class. The scope
of this directive spans the entire JSP file. When used more than once, only the
first occurrence of the directive is significant.
The following code segment provides an example of JSP directives. You
usually use JSP directives in the beginning part of your code.
<html><head>
<title>JSP Sample for JSP Directive </title></head>
<body text="#000000" bgcolor="#FFCCCC" link="#0000EE" vlink="#551A8B"
alink="#FF0000">
<! JSP Directives >
<%@ language = "java" %>
<%@ method = "doGet" %>
<%@ import = "java.util.*"%>
<%@ import = "java.sql.*"%
<%@ implements ="javax.servlet.http.HttpSessionContext" %>
<%@ content_type = "text/html" %>
<%@ extends ="javax.servlet.http.HttpServlet" %>
Figure 111. JSP Directives
3.2.4.2 <SCRIPT> and </SCRIPT> Tags
Use the <SCRIPT> and </SCRIPT> tags to declare class-wide variables and
class-wide methods for the servlet class. The general syntax is:
<script runat=server>
// code for class-wide variables and methods
</script>
The attribute runat=server is required and indicates that the tag is for server-side
processing. You shouldn’t edit this expression.
128
WebSphere Application Servers: Standard and Advanced Editions
<! JSP Class-wide variables and methods>
<script runat = server>
private static int counter = 0;
private String parmVal = "None";
private String arrangeCreatedTime ( GregorianCalendar gc1) {
GregorianCalendar gcal = gc1;
StringBuffer arrangedTime = new StringBuffer();
arrangedTime.append("<B>" + (1+gcal.get(Calendar.MONTH)));
arrangedTime.append("/" + gcal.get(Calendar.DATE));
arrangedTime.append("/ " + gcal.get(Calendar.YEAR));
arrangedTime.append("<BR>"+gcal.get(Calendar.HOUR_OF_DAY));
arrangedTime.append(":" +gcal.get(Calendar.MINUTE));
arrangedTime.append("</B>:" +gcal.get(Calendar.SECOND));
return arrangedTime.toString();
}
</script>
Figure 112. <SCRIPT> Tag
3.2.4.3 <% and %> Tags (Inline Java Code, Scriptlets)
You can embed any valid Java language code inline within a JSP file between the
<% and %> tags. An advantage of embedding Java coding for servlets inline in
JSP files is that the servlet does not have to be compiled in advance, and placed
on the server. This makes it easier to quickly test servlet coding. You can use
these variables:
• request, responses, out, in
These are pre-defined for you. They are closely related to the classes well
known to Servlet developers. The classes are HttpServletRequest,
HttpServletResponse in javax.servlet.http package, PrintWriter and
BufferedReader in java.io package.
• The variables that you defined in <SCRIPT> tag (see 3.2.4.2, “<SCRIPT> and
</SCRIPT> Tags” on page 128).
In this code, you get a parameter value of parm1 (this is the string that you
input in the text field) from the HTTP request and set HTTP headers to disable
caches as shown in Figure 127 on page 143.
3.2.4.4 <%= and %> Tags (Java Expressions for Variable Data)
The tags, <%= and %>, are used to embed the value of variable data to the JSP.
Primitive types, such as int and float, are automatically converted to a string
representation.
This is an example:
• <%= (++counter)%>
This increments the counter variable and displays the value.
• <%= arrangeCreatedTime(new GregorianCalendar())%>
This executes the arrangeCreatedTime() method and displays the value. You
can define this method in the <SCRIPT> tag.
As you can see, you can execute simple calculations and methods in this tag.
Content Presentation
129
3.2.4.5 <BEAN> Tag (Accessing JavaBeans)
This tag is used to access JavaBeans. When you want to access Beans, you must
declare the Bean to be used. With this tag, you can get the value from the Bean.
The <BEAN> tag syntax is:
• name
<bean name="Bean_name" varname="local_Bean_name"
type ="class_or_interface_name" introspect="yes|no"
beanName="ser_filename" create="yes|no"
scope="request|session|userprofile" >
<param property_name="value">
</bean>
Name is used to look up the Bean in the appropriate scope (specified by the
scope attribute). The value is case-sensitive. For example, when using the Bean
from PopulateBeanServlet.java to DisplayData.jsp, this value must be the same
name as that stored in the setAttribute() method as shown in the following
window:
Figure 113. These Two Data Bean Names Should Be the Same Value
• varname
This attribute is optional. When you use the Bean elsewhere in JSP, you refer
to the Bean with this value.
• type
The name of the Bean class name.
• introspect
When the value is yes, the JSP processor examines all requested properties
and calls the set property methods (passed in the BeanInfo) that match the
requested properties. The default value of this attribute is yes.
• beanName
The serialized object file name (.ser file), or the name of the Bean .class file,
the Bean package name.
• create
When the value is yes, the JSP processor creates an instance of the Bean if
the processor does not find the Bean within the specified scope. The default
130
WebSphere Application Servers: Standard and Advanced Editions
value is yes. In DisplayData.jsp (Figure 113 on page 130), if you change this
value to no, the result is the same, because the processor finds the Bean
within the scope.
• scope
This is the lifetime of the Bean. This attribute is optional. There are three valid
values:
• request
This is the default value. The Bean is set as a context in the request by a
servlet that invokes the JSP file using the APIs described in the JSP API.
That is, the life time of the bean is one HTTP session.
If the Bean is not part of the request context, the Bean is created and
stored in the request context, unless the create attribute is set to no.
• session
If the Bean is present in the current session, the bean is reused. If the
Bean is not present, it is created and stored as part of the session (if the
create attribute is set to yes).
• userprofile
The user profile is retrieved from the servlet request object, put to the
specified type and introspected. If a type is not specified, the default type is
com.ibm.servlet.personalization.userprofile.UserProfile. The create
attribute is ignored.
• param
A list of property and value pairs. The properties are automatically set in
the bean using introspection. The properties are set once when the Bean is
instantiated.
3.2.4.6 <INSERT> Tag
The <INSERT> tag is used to embed the values of the Java variable into JSP.
The general syntax is:
<insert requestparm=pvalue requestattr=avalue bean=name
property=property_name(optional_index).subproperty_name(optional_index)
default=value_when_null>
</insert>
Where:
• requestparm
The parameter that is accessed in the request object. This attribute is
case-sensitive and can’t be used with the Bean and property attributes.
• requestattr
The attribute that is accessed in the request object. The attribute is set with
the setAttribute method. This attribute is case-sensitive and can’t be used
with the Bean and property attributes.
Content Presentation
131
• bean
The name of the JavaBean declared by a <BEAN> tag within the JSP file.
For more information on the <BEAN> tag, see 3.2.4.5, “<BEAN> Tag
(Accessing JavaBeans)” on page 130. The value for this attribute is
case-sensitive.
When the Bean attribute is specified, but the property attribute is not
specified, the entire Bean is used in the substitution.
For example, if the property is not specified, the String of the Bean value is
displayed as the substitution.
Figure 114. The Bean Is Used in the Substitution, If the Property Is Not Specified
• property
The property of the bean to access for substitution. The value of the
attribute is case-sensitive and is the locale-independent name of the
property. This attribute can’t be used with the requestparm and requestattr
attributes. For example, the code snippet in Figure 115 on page 133
displays the value of prop3 for the DataBean.
132
WebSphere Application Servers: Standard and Advanced Editions
<bean name="dataBeanName" type="DataBean" introspect="no" create="yes"
scope="request">
</bean>
<body>
:
:
<p>The value of Bean property 3 is
<insert bean=dataBeanName property=prop3 default="No property value" >
</insert></p>
Figure 115. Example of <INSERT> Tag
The value of Bean property 3 is Value3
Figure 116. The Result of Figure 115
• default
An optional string to display when the value of the bean property is null.
The default value of this parameter is an empty string.
3.2.4.7 <REPEAT> Tags (For Repeating a Block of HTML Tagging)
Use <REPEAT> tags to repeat a block of HTML tags that contains the <INSERT>
tag and the HTML tags for formatting the content.
The syntax of the <REPEAT> tags is:
<repeat index=name start=starting_index end=ending_index>
</repeat>
where:
• index
An optional name used to identify the index for this repeat block. The value is
case-sensitive.
• start
An optional starting index value for this repeat block. The default is 0.
• end
An optional ending index value for this repeat block. The maximum value is
2,147,483,647. If the value for the end attribute is less than the value of the
start attribute, the end attribute is ignored.
<REPEAT> tags are useful to access the indexed properties of JavaBeans.
RepeatTestBean.java (Figure 117 on page 135) is an example of properties that
are indexed. RepeatTest1.jsp accesses the RepeatTestBean with <REPEAT>
tags. RepeatTest1.jsp is one file, but it is cut into pieces here because it is too
Content Presentation
133
large to be shown at once and because we want to make it clear what each
segment of HTML code does.
To use this sample:
1. Create RepeatTestBean.java and RepeatTest1.jsp.
2. Copy RepeatTest1.jsp to your HTTP document root. In the default setting of
IBM HTTP Server1.3.3 on Windows NT, it is located at \Program Files\IBM
HTTP Server\htdocs.
3. Copy RepeatTestBean.java into <ASRoot>/servlets. Compile
RepeatTestBean.java and create a class file.
C:\WEBSPH~1\APPSER~1\servlets>javac RepeatTestBean.java
C:\WEBSPH~1\APPSER~1\servlets>
4. You can get the result by opening the URL http://<hostname>/
RepeatTest1.jsp.
134
WebSphere Application Servers: Standard and Advanced Editions
import java.io.*;
public class RepeatTestBean implements Serializable{
String[] city = new String[5];
String[] address = new String[5];
String[] telephone = new String[5];
public static void main(String[] args){
RepeatTestBean b=new RepeatTestBean();
for(int i=0; i<5; i++){
b.setCity(i,"cityName"+i);
b.setAddress(i,"AddressValue"+i);
b.setTelephone(i,"telephoneNumber"+i);
}
for(int i=0; i<3; i++){
System.out.println("city: "+b.getCity(i));
System.out.println("add : "+b.getAddress(i));
System.out.println("tel : "+b.getTelephone(i));
}
}
public String toString() {
return "This is RepeatTestBean.";
}
//---------- city ---------------//
public void setCity(int index,String city) {
this.city[index] = city;
}
public void setCity(String[] city) {
this.city = city;
}
public String[] getCity() {
return city;
}
public String getCity(int index) {
return getCity()[index];
}
Figure 117. RepeatTestBean.java (1/2)
Content Presentation
135
//---------- address ---------------//
public void setAddress(int index,String address) {
this.address[index] = address;
}
public void setAddress(String[] address) {
this.address = address;
}
public String[] getAddress() {
return address;
}
public String getAddress(int index) {
return getAddress()[index];
}
//---------- telephone ---------------//
public void setTelephone(int index,String telephone) {
this.telephone[index] = telephone;
}
public void setTelephone(String[] telephone) {
this.telephone = telephone;
}
public String[] getTelephone() {
return telephone;
}
public String getTelephone(int index) {
return getTelephone()[index];
}
}
Figure 118. RepeatTestBean.java (2/2)
136
WebSphere Application Servers: Standard and Advanced Editions
<html>
<head>
<title>RepeatTest1.jsp</title>
</head>
<H1>Test of Repeat Tags</H1>
<!-- Get the Bean using the BEAN tag
-->
<bean name="serviceLocationsQuery" type="RepeatTestBean" introspect="no"
create="yes" scope="request">
</bean>
<body>
<!---- scriptlet -- >
<%
for(int i=0; i<5; i++){
serviceLocationsQuery.setCity(i,"cityName"+i);
serviceLocationsQuery.setAddress(i,"AddressValue"+i);
serviceLocationsQuery.setTelephone(i,"telephoneNumber"+i);
}
%>
<HR>
<H2> Repeat Tags Example1</H2>
<table border=2>
<tr><td><B>city</B></td><td><B>Address</B></td><td><B>Telephone</B></td></
tr>
<repeat>
<tr><td><insert bean=serviceLocationsQuery property=city></insert></td>
<td><insert bean=serviceLocationsQuery property=address></insert></td>
<td><insert bean=serviceLocationsQuery
property=telephone></insert></td></tr>
</repeat>
</table>
Figure 119. RepeatTest1.jsp (1/3)
RepeatTest1.jsp accesses the RepeatTestBean three different ways using the
<REPEAT> tags. In the beginning of this file, enclosed with bold <% and %> in
Figure 119 on page 137, it sets the values to the properties of the
RepeatTestBean.
Figure 120 on page 138 shows implicit indexing with the default start and default
end index. The bean with the smallest number of indexed properties restricts the
number of times the loop will repeat.
The result of this part is shown in Figure 120 on page 138. All elements of the
properties are restored with this tag.
Content Presentation
137
Figure 120. The Result of RepeatTest1.jsp (2/3)
Figure 121 shows the starting index and the ending indexes:
<HR>
<H2> Repeat Tags Example2</H2>
<table border=2>
<tr><td><B>city</B></td><td><B>Address</B></td><td><B>Telephone</B></td></tr>
<repeat index=myIndex1 start=2 end=2147483647>
<tr><td><insert bean=serviceLocationsQuery
property=city(myIndex1)></insert></td>
<td><insert bean=serviceLocationsQuery
property=address(myIndex1)></insert></td>
<td><insert bean=serviceLocationsQuery
property=telephone(myIndex1)></insert></td></tr>
</repeat>
</table>
*
Figure 121. RepeatTest1.jsp (3/3)
The result of this part is shown in Figure 122 on page 139. The start attribute for
the <REPEAT> tags and the values for the properties begin at XXX2.
138
WebSphere Application Servers: Standard and Advanced Editions
Figure 122. The Result of RepeatTest1.jsp
Figure 123 shows explicit indexing and ending indexing with an implicit starting
index. Although the index attribute is specified, the indexed property city can still
be implicitly indexed because the value (i) is not required.
<HR>
<H2> Repeat Tags Example3</H2>
<table border=2>
<tr><td><B>city</B></td><td><B>Address</B></td><td><B>Telephone</B></td></
tr>
<repeat index=myIndex2 end=2>
<tr><td><insert bean=serviceLocationsQuery property=city></insert></td>
<td><insert bean=serviceLocationsQuery
property=address(myIndex2)></insert></td>
<td><insert bean=serviceLocationsQuery
property=telephone(myIndex2)></insert></td></tr>
</repeat>
</table>
</body></html>
Figure 123. RepeatTest1.jsp
Figure 124 on page 140 shows you the result. The display of the value of the
properties stopped at XXX2 because of the end property <REPEAT> tags.
Previous examples displayed all of the elements.
Content Presentation
139
Figure 124. The Result of RepeatTest1.jsp
3.2.5 JSP APIs
Two interfaces are provided to pass the request context to a JSP file. The
interfaces that support JSP are:
1. com.sun.server.http.HttpServiceRequest
This class implements the javax.servlet.http.HttpServletRequest interface and
a setAttribute() method to set attributes defined by name.
2. com.sun.server.http.HttpServiceResponse
This class implements the javax.servlet.http.HttpServletResponse interface
and adds a callPage() method enabling servlets to call JSP files and optionally
pass a context.
3.2.5.1 callPage() method
Use the callPage() method to serve a JSP from within a servlet. The served page
(a JSP file) is returned as the response to the browser. The calling servlet can
also pass some context via the request object. You should code the header of the
served page to include a directive to tell the browser not to cache the file.
The syntax of the callPage() method is:
public void callPage(String fileName,
HttpServletRequest req) throws ServletException, IOException)
Where:
• fileName
Is the name of the URL that identifies the file that will be used to generate the
output and present the content. If the file name begins with slash ( / ), the file
location is assumed to be relative to the document root. If the file name
doesn’t begin with a slash, the location is assumed to be relative to the URL
with which the current request was invoked.
The callPage() method doesn’t support calling pages with the file extension
.html. If you need to invoke HTML pages using the callPage() method, you
must first rename the HTML files to have the file extension .jsp.
140
WebSphere Application Servers: Standard and Advanced Editions
• req
Is the HttpServletRequest object of the servlet that invoked this method. Most
often, the content is passed as a Bean in the context of the request object.
To use the callPage() method, you must pass the response object to a special
Sun object:
com.sun.server.http.HttpServiceResponse.
See Figure 137 on page 149 for an example.
3.2.5.2 setAttribute() method
Use the setAttribute() method to store an attribute in the request context. The
syntax is:
public void setAttribute(String key, Object o)
Where:
• key
Is the name of the attribute to be stored.
• o
Is the context object stored with the key.
To use the setAttribute() method, you must pass the request object to a special
Sun object:
com.sun.server.http.HttpServiceRequest.
See Figure 137 on page 149 for an example of the syntax.
3.2.6 JSP Sample1
We show a very simple JSP sample first. This is a sample of the access model 1,
shown in 3.2.1.1, “JSP Access Models” on page 122.
3.2.6.1 Sample1 Processing Flow
We show you two files, Sample1.html (Figure 126 on page 142) and Sample1.jsp.
Parameters are sent to Sample1.jsp (Figure 127 on page 143), which processes
the parameter and sends the response to the browser as shown in Figure 125 on
page 142:
Content Presentation
141
Figure 125. JSP Sample1 Processing Flow
<html><head>
<title>JSP Sample 1</title>
</head>
<body text="#000000" bgcolor="#CCFFFF" link="#0000EE" vlink="#551A8B"
alink="#FF0000">
<center><font color="#000099"><font size=+2>Input
Page</font></font></center>
<form action = "http://localhost/Sample1.jsp" method = "GET">
<p><br>
<center><table COLS=2 WIDTH="76%" >
<tr>
<td>Input String:</td>
<td><input type = "text" name = "parm1"></td>
</tr><tr><td>Click on "Submit!" Button:</td>
<td><input type = "submit" VALUE = "Submit!"></td>
</tr></table></center>
</form></body></html>
Figure 126. Sample1.html
142
WebSphere Application Servers: Standard and Advanced Editions
<html><head>
<title>JSP Sample1</title></head>
<body text="#000000" bgcolor="#FFCCCC" link="#0000EE" vlink="#551A8B"
alink="#FF0000">
<! JSP Directive >
<%@ language = "java" %>
<%@ method = "doGet" %>
<%@ import = "java.util.*"%>
<%@ content_type = "TEXT/HTML" %>
<! JSP Class-wide variables and methods>
<script runat = server>
private static int counter = 0;
private String parmVal = "None";
private String arrangeCreatedTime ( GregorianCalendar gc1) {
GregorianCalendar gcal = gc1;
StringBuffer arrangedTime = new StringBuffer();
arrangedTime.append("<B>" + (1+gcal.get(Calendar.MONTH)));
arrangedTime.append("/" + gcal.get(Calendar.DATE));
arrangedTime.append("/ " + gcal.get(Calendar.YEAR));
arrangedTime.append("<BR>"+gcal.get(Calendar.HOUR_OF_DAY));
arrangedTime.append(":" +gcal.get(Calendar.MINUTE));
arrangedTime.append("</B>:" +gcal.get(Calendar.SECOND));
return arrangedTime.toString();
}
</script>
<! Scriptlet : disabling caches>
<%
parmVal = request.getParameterValues("parm1")[0];
response.setHeader("Pragma", "No-cache");
response.setHeader("Cache-Control", "no-cache");
response.setDateHeader("Expires", 0);
%>
<center>
<H1><font color="#000099">JSP Sample 1</font></H1>
</center>
<form action = "http://localhost/wakako/Sample1.html" method = "GET">
<p><br>
<center><table COLS=2 WIDTH="81%" >
<tr><td>Access Count:</td><td>
<%= (++counter)%>
</td></tr>
<tr><td>Access Time:</td><td>
<%= arrangeCreatedTime(new GregorianCalendar())%></td></tr>
<tr><td>Value:</td><td><%= parmVal%>
</td></tr>
<tr><td></td><td><input type = "submit" value = "Back"></td></tr>
</table></center>
</form>
</body></html>
Figure 127. Sample1.jsp
Content Presentation
143
To use this sample:
1. Create Sample1.html and Sample1.jsp.
2. Copy Sample1.html and Sample1.jsp to <DocRoot>.
3. Open http://<hostname>/Sample1.html in your browser. You’ll see a page
similar to Figure 128:
Figure 128. http:<hostname>/Sample1.html
4. Update the Input String in the text file and click the Submit! button in the
following window:
Figure 129. Input String to the Text Field
5. You should receive the result shown in Figure 130 on page 145 from
Sample1.jsp.
144
WebSphere Application Servers: Standard and Advanced Editions
Figure 130. The Result from Sample1.jsp
6. Click the Back button on the page. That brings you back to the Input Page.
When you repeat steps 3-6, you get the result faster, since once the servlet
instance is created from the JSP, it remains on the JVM unless you unload this
instance. Therefore, you get a quicker response, and an incremented Access
Count.
This shows you that JSPs give you the same performance advantage as
servlets.
3.2.7 JSP Sample 2
Many JSPs are used in the WebSphere samples, for example, WebBank and
Xtreme Travel. You can also find HitCount.jsp in <AppServerRoot>/servlet. In this
part, we used the sample JSP DisplayData.jsp. This is a simple example of the
second assess model for JSPs (Figure 106 on page 123).
3.2.7.1 Sample2 Processing Flow
This is the process flow for Sample2 shown in Figure 131 on page 146.
Content Presentation
145
Figure 131. Sample2 Processing Flow
1. A request from Populate.html is sent to PopulateBeanServlet.
2. PopulateBeanServlet creates an instance of the DataBean (named dataBean).
3. PopulateBeanServlet sets the parameters to the dataBean.
4. PopulateBeanServlet sets the Bean instance (dataBean) as an attribute in the
current request object.
5. PopulateBeanServlet calls DisplayData.jsp with callPage() method.
6. The client receives the DisplayData.jsp with embedded values of dataBean
properties in it.
3.2.7.2 Preparing to Work with the JSP Samples
This sample needs four files:
1. HTML form - We called this Populate.html. It calls PopulateBeanServlet.
2. PopulateBeanServet.java - This is the servlet that instantiates DataBeans,
sets bean values and calls the JSP file (DisplayData.jsp).
3. DataBeans.java - JavaBeans
4. DisplayData.jsp - This gets property values from DataBeans and sends the
responses to the user.
With Populate.html, PopulateBeanServlet.java and DisplayData.jsp, you can see
sample files at http://<hostname>/IBMWebAS/doc/whatis/icjsp.html#jspsamp.
Click each of the references (Figure 132 on page 147) to see the sample code.
146
WebSphere Application Servers: Standard and Advanced Editions
Figure 132. http://<hostname>/IBMWebAS/doc/whatis/icjsp.html#jspsamp
Copy and paste from the sample code window, and create these files
(Populate.html, PopulateBeanServlet.java, DisplayData.jsp). See Figure 133:
Figure 133. Copy and Paste from the Sample Code Window
Content Presentation
147
<!-- This JSP file gets a Bean passed in a request object
and displays the Bean properties -->
<html>
<head>
<title>Bean Data Display</title>
</head>
<!-- Get the Bean using the BEAN tag
-->
<bean name="dataBean" type="DataBean" introspect="no" create="no"
scope="request">
</bean>
<body>
<!-- There are three ways to access Bean properties -->
<!-Using a JSP scriptlet -->
<% out.println("The value of Bean property 1 is " + dataBeans.getProp1());
%>
<!-Using a JSP expression -->
<p>The value of Bean property 2 is
<%= dataBean.getProp2() %> </p>
<-Using the INSERT tag
-->
<p>The value of Bean property 3 is
<insert bean=dataBean property=prop3 default="No property value" >
</insert></p>
</body>
</html>
Figure 134. DisplayData.jsp
Note: In DisplayData.jsp, there is a spelling error. The error is the bold character
in Figure 134 on page 148. You must correct this to be "dataBean", not
"dataBean s". If you forget this, you will get an error message from the server
(Figure 135) in the next step:
Figure 135. Error Getting Compiled Page
This shows us that something is wrong with the DisplayData.jsp file (Figure 134).
Change "dataBeans" to "dataBean", then save the document in
<AppServerRoot>/servlets.
148
WebSphere Application Servers: Standard and Advanced Editions
import
import
import
import
import
java.io.*;
java.beans.Beans;
javax.servlet.*;
javax.servlet.http.*;
DataBean;
/******************************************************************
* PopulateBeanServlet - This servlet creates an instance of a Bean
* (DataBean), sets several of its parameters, sets the Bean instance
* as an attribute in the request object, and invokes a JSP file to
* format and display the Bean data.
*******************************************************************/
public class PopulateBeanServlet extends HttpServlet
{
public void service(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException
{
DataBean dataBean; // Create an instance of DataBean
try{
dataBean = (DataBean) Beans.instantiate(this.getClass().getClassLoader(),
"DataBean");
}catch (Exception ex) {
throw new ServletException("Can't create BEAN of class DataBean: "
+ ex.getMessage());
}
Figure 136. PopulateBeanServlet.java(1/2)
// Set some Bean properties (content generation)
dataBean.setProp1("Value1");
dataBean.setProp2("Value2");
dataBean.setProp3("Value3");
// To send the Bean to a JSP file for content formatting and display
// 1) Set the Bean as an attribute in the current request object
((com.sun.server.http.HttpServiceRequest)
req).setAttribute("dataBean", dataBean);
// 2) Use callPage to invoke the JSP file and pass the current request
object
((com.sun.server.http.HttpServiceResponse)
res).callPage("/DisplayData.jsp", req);
}
} /* end of class PopulateBeanServlet */
Figure 137. PopulateBeanServlet.java (2/2)
Copy Populate.html, DisplayData.jsp to your HTTP document root (Figure 138 on
page 150). In this case, we used the IBM HTTP Server V1.3.3 on Windows NT. It
was located at \Program Files\IBM HTTP Server\htdocs.
Content Presentation
149
Figure 138. Copy Populate.html, DisplayData.jsp to Your HTTP Document Root
If you look at PopulateBeanServlet.java, you may have the following question:
"Where did the DataBean come from?". If you compile this file, you receive the
following error message:
C:\WEBSPH~1\APPSER~1\servlets>javac PopulateBeanServlet.java
PopulateBeanServlet.java:7: Class DataBean not found in import.
import DataBean;
^
1 error
We couldn’t find this package in the WebSphere directories, so we created our
own example of DataBean.java (Figure 140 on page 151) for this sample. This
was placed in <AppServerRoot>/servlets as PopulateBeanServlet.java.
Note: In PopulateBeanServlet.java , "service" method must be written in
lowercase. We found "Service" method was written in this document, so we
corrected it.
Now compile DataBean.java and PopulateBeanServlet.java with the following
commands:
C:\WEBSPH~1\APPSER~1\servlets>javac DataBean.java
C:\WEBSPH~1\APPSER~1\servlets>javac PopulateBeanServlet.java
Figure 139. Compile DataBean.java, PopulateBeanServlet.java
150
WebSphere Application Servers: Standard and Advanced Editions
import javax.servlet.http.*;
import java.io.PrintWriter;
import java.io.IOException;
public class DataBean extends HttpServlet {
String Prop1 = "DefaultVauleOfProp1";
String Prop2 = "DefaultVauleOfProp2";
String Prop3 = "DefaultVauleOfProp3";
public void service(HttpServletRequest req, HttpServletResponse res)
throws IOException
{
PrintWriter writer = res.getWriter();
writer.println("<BR><B>This is output form DataBean</B><P>");
}
public void setProp1(String Prop1) {
this.Prop1 = Prop1;
}
public String getProp1() {
return Prop1;
}
public void setProp2(String Prop2) {
this.Prop2 = Prop2;
}
public String getProp2() {
return Prop2;
}
public void setProp3(String Prop3) {
this.Prop3 = Prop3;
}
public String getProp3() {
return Prop3;
}
}
Figure 140. DataBean.java
3.2.7.3 How to Use This Sample
Open page http://<hostname>/Populare.html in your browser. You can see this
page in Figure 141:
Figure 141. http://<hostname>/Populate.html
Content Presentation
151
<HTML>
<head><title>Run PopulateBeanServlet</title></head>
<BODY>
<H1>Run PopulateBeanServlet</H1>
<P>Do you want to run the PopulateBeanServlet?
<FORM action="/servlet/PopulateBeanServlet" method="GET">
<INPUT type="SUBMIT" value="Yes">
<INPUT type="SUBMIT" value="No">
</FORM>
</BODY>
</HTML>
Figure 142. Populate.html
Click the Yes or No button to call PopulateBeanServlet.
You should receive the result shown in Figure 143:
Figure 143. Result of JSP Sample
You receive this result whether you click Yes or No. The developer might have
forgotten to code this part, or left it to the reader as an exercise to complete.
3.2.8 Tools for Creating JSP Files
You can use various tools to make JSP. Please refer to 2.6, “Setting Up a
Development System” on page 86.
3.3 Using the WebSphere XML Tools
eXtensible Markup Language (XML) provides a way of formatting data with tags
so that it is platform and application independent. It is derived from SGML but
XML attempts to alleviate some of HTML’s shortcomings by promoting the
separation of presentation and content and building in extensibility. There is a
good introduction to XML in the WebSphere documentation at
http://<ASRoot>:9527/doc/whatis/icxml4j.html. There is also more information at
http://www.ibm.com/xml and http://www.alphaworks.ibm.com.
152
WebSphere Application Servers: Standard and Advanced Editions
XML allows the application designer to describe data in a way that represents the
structure and internal semantics of that data. It is then possible to take the XML
and transform it so that it can be viewed by a client, either as HTML or directly, as
formatted XML, through the use of a style sheet. WebSphere provides XML
document structure services to facilitate the creation and manipulation of XML
documents and allow the development of XML-based applications. XML
documents can be static or created dynamically through the use of servlets, JSPs
or EJBs accessing various back-end data sources such as databases. See 3.3.6,
“Example: Using XSL and XML to Format DB2 Data” on page 166 for an example
of a servlet that creates dynamic XML from a database.
In this section we look at the document structure services provided with
WebSphere and then at how to extend these services to produce formatted XML
data from a database. To generate and process the XML, we use the standard
XML document structure services and also additional tools from the IBM
alphaWorks Web site at:
http://www.alphaworks.ibm.com/
In addition, there is a discussion group available at alphaWorks for LotusXSL and
XML4J.
3.3.1 Environment
This section describes the environment that we used to produce the information
in this chapter.
3.3.1.1 Hardware and Software Environment
The following table lists the hardware and software environment used in this
section:
Table 10. XML Hardware and Software Environment
Item
Version
Machine
Netfinity 3000 PII 350MHz, 128 MB RAM
Operating System
Windows NT V4.0 with service pack 4
Application Server
WebSphere Application Server 2.02
Advanced
Database
DB2 UDB V5.2 Workgroup Edition installed
from the WebSphere 2.0 Advanced CD
3.3.1.2 External Tools Used
Table 11 is a list of the tools that we used in addition to the tools installed with
WebSphere. To get to the individual Web page for each tool do the following:
• Go to http://www.alphaworks.ibm.com.
• Select Technologies.
• Scroll to the bottom of the yellow list on the left of the page and select XML.
Content Presentation
153
• Select the technology in the yellow list.
Table 11. alphaWorks Technologies Used
Tool
Version
Version shipped with
WebSphere V2.02
Description
Lotus XSL
0.16.5
0.16.2
XML style sheet processor
for transforming XML to
other formats such as
HTML.
XML Parser
for Java
2.06
1.1.14
Update to WebSphere tool
used to parse XML files for
processing by Java
programs.
Note: XML4J V2.x is much faster than V1.x.
3.3.2 Setting Up the Environment
To work with the XML Document Services you need to set up the environment
correctly. This involves adding the IBM XML for Java parser JAR files to the
application server classpath. To do this follow these steps:
1. Open the WebSphere administration application by loading http://<your
server name>:9527/ and log in with your administration user ID and password.
2. Expand the Setup category and select Java Engine.
3. In the Application Server classpath field add the following directory to the end
of the classpath (classpath entries are separated by semicolons on Windows
and colons on AIX):
<server root>\lib\xml4j.jar;
Note: On Windows, any directory path must include directories in the 8.3 file
naming format. You can see these name by typing dir /x instead of dir to get
a directory listing. Typically, directories with names longer than eight
characters will have a tilde (~) character included followed by a number. For
example the directory path above may be:
d:\WEBSPH~1\APPSER~1\lib\xml4j.jar;
on Windows.
4. Stop and restart your Web server to make the changes active.
Note: While working with the XML document structure services on Windows NT
(using XML4J on Win32 Symantec JIT 1.1.6), we had problems with some
versions of the XML parser that had the JIT compiler turned on. See 3.3.6.10,
“Description of Errors Encountered during Development” on page 181 for a full
description of the symptoms and their resolution.
3.3.3 Processing XML
To make use of XML information it is necessary to transform it from a text format
into a data structure in memory that a program can use. This process of reading
the source and making sense of it is called parsing. To parse XML, a parser that
can understand XML semantics is required. WebSphere provides a version of the
IBM XML for Java parser (also known as XML4J) as part of XML document
structure services. It should be noted that there are later versions of the parser
154
WebSphere Application Servers: Standard and Advanced Editions
available on the alphaWorks Web site. See 3.3.7, “Installing Later Versions of the
XML Tools” on page 185 for instructions on how to configure WebSphere to use
the upgraded parser. In addition, XML4J and LotusXSL components of XML
Document Structure Services are following an open source development model.
The object is shipped and supported in WebSphere but new releases will be
made available via the alphaWorks Web site.
The component XML4J provides two different methods for processing XML:
1. Event-driven parsing using the Simple API for XML or SAX parsing
Code should be portable between XML processors. They are only interested in
processing pieces of the overall document (or if you have a very large
document). If you are using 2.x-level classes it provides the fastest
processing) and is easier to use than DOM tree parsing.
2. Event-driven parsing using event handlers
Event handlers are easier to use than SAX. This is because you can indicate
specific elements or attributes that you care about.
3. DOM Tree Parsing
This is the most portable of the methods for processing XML. Microsoft
implements this in Internet Explorer V5. It lets you process the entire
document tree in memory to manipulate the document structure. It is slower to
parse than the other methods and it uses more resources.
In event-driven parsing the application using the parser registers with the parser a
set of events in which it is interested. As the parser processes the XML it
recognizes data within the XML that makes up logical units called tokens. As
each token is recognized the parser checks to see if any applications have
registered their interest in the particular token encountered and signals
appropriate events to those applications.
In tree parsing the parser constructs a tree data structure in memory
corresponding to the logical structure of the input XML. Each logical unit or token
is placed at a node of the tree and tokens logically contained within other tokens
are placed as children of the containing token. The data structure is then made
available to the application to process as needed.
For example the XML source fragment shown in Figure 144 might produce the
logical tree structure shown in Figure 145 (the actual structure would be
significantly more complex than this. See 3.3.3.3, “Parsing Using the DOM Tree
Parser” on page 160 for further details).
<person>
<name>
<first>John</first>
<last>smith</last>
</name>
<age>34</age>
</person>
Figure 144. Sample XML Fragment
Content Presentation
155
person
name
first:: John
age: 34
last: Smith
Figure 145. Abstract Representation of the DOM Structure
One advantage of event parsing over tree parsing is that the whole XML
document structure does not have to be kept in memory at once, allowing very
large documents to be processed. Another advantage is that applications need
only register themselves for events in which they are interested. Applications
using trees generated using a tree parser must deal with every element in the
tree structure, whether or not it is significant to them. The advantage of tree
parsers over event parsers is that modifications to the tree structure are relatively
easy to make allowing transformations to be made. This is useful when the data
must be manipulated to produce a different output form such as in XSL
processing (see 3.3.5, “XML Style Sheets and LotusXSL” on page 164).
The choice of which processing method to use is driven by the needs of your
application.
3.3.3.1 SAX Event-Driven Parsing
In SAX parsing, the parser produces a simple set of events for the application at
the document level. The application must register a handler for these events with
the parser. Typically, the handler will need to implement the interface
org.xml.sax.DocumentHandler. This is the basic interface for SAX parsing.
Handlers wishing to register for SAX document events must implement each of
the methods shown in Table 12, although the method implementations need not
do anything. See file:///<server
root>/web/doc/apidocs/org.xml.sax.DocumentHandler.html#_top_ for more
details.
Table 12. Methods in the org.xml.sax.DocumentHandler Interface
Method
characters(char[], int, int)
156
WebSphere Application Servers: Standard and Advanced Editions
Purpose
Receive notification of character data.
Method
Purpose
endDocument()
Receive notification of the end of a
document.
endElement(String)
Receive notification of the end of an
element.
ignorableWhitespace(char[], int, int)
Receive notification of ignorable white space
in element content.
processingInstruction(String, String)
Receive notification of a processing
instruction.
setDocumentLocator(Locator)
Receive an object for locating the origin of
SAX document events.
startDocument()
Receive notification of the beginning of a
document.
startElement(String, AttributeList)
Receive notification of the beginning of an
element.
To implement SAX event-driven parsing, the application must do the following
(more details can be found in the WebSphere documentation at
<ASRoot>\web\doc\howto\itxml4j.html#evtparse):
1. Put the following two lines with the import statements at the top of the java
source file to include the java classes:
import org.xml.sax.*;
import com.ibm.xml.parser.SAXDriver;
2. Implement the org.xml.sax.DocumentHandler interface:
public class parseXMLUsingSAX extends HttpServlet implements DocumentHandler
3. Create the parser:
Class parserClass = Class.forName("com.ibm.xml.parser.SAXDriver");
Parser parser = (Parser) parserClass.newInstance();
4. Register the class with the parser as a document event listener:
parser.setDocumentHandler(this);
5. Run the parser:
parser.parse(new InputSource(bais));
Where bais is a java.io.ByteArrayInputStream. You could use any sort of
java.io.InputStream here.
The parser will now look at the input stream and call the event methods that were
defined in the class.
Example source code used by the Xtreme XML sample to perform SAX parsing
can be found at <ASRoot>\samples\XtremeXML\parseXMLUsingSAX.java.
For more information on the SAX standard visit the official Web site
http://www.microstar.com/sax.html or the site of one of the creators of SAX,
http://www.megginson.com/SAX/.
Content Presentation
157
3.3.3.2 Parsing Using Element Handlers
The second type of parsing that XML document structure services supports is
using element handlers. The parser that this method uses is the same as the
DOM tree parser (see 3.3.3.3, “Parsing Using the DOM Tree Parser” on page
160), but this method of parsing uses events. Thus, this method of parsing is a
hybrid between true event-driven parsing, such as that provided by the SAX
parser, and DOM tree parsing. Parsing using element handlers involves
registering handlers for different elements within the document as the parser
creates the DOM tree. These handlers are called whenever the parser
encounters an element of the specified type. It is also possible to register a
general handler to receive events when any element is encountered.
Parsing using element handlers is most useful when you need to make changes
to the structure of a DOM tree as it is being constructed. Each element that needs
to be modified has a handler registered to it. When the parser encounters an
element of that type it passes the document element to the handler which allows
the handler to effect the transformation.
The disadvantage of this method is that it needs to construct the entire DOM tree
in memory in order to generate the events. The advantage is that handlers can be
registered selectively for only the document elements that you are interested in
which leads to increased code efficiency.
To process XML using element handlers you need to create an element handler
and then register it with the parser. To create an element handler do the following:
1. Add the following import lines to the top of your element handler code:
import com.ibm.xml.parser.*;
import org.w3c.dom.*;
2. Implement the com.ibm.xml.parser.ElementHandler interface (see
file:///<ASRoot>/web/doc/apidocs/com.ibm.xml.parser.ElementHandler.html#_
top_ for API details). For example:
public class itineraryHandler implements ElementHandler
3. Create an implementation of the handleElement method that has as a
parameter a com.ibm.xml.parser.TXElement object. This is the element that
the parser created and for which your handler has been registered. After
performing processing using the DOM APIs (see
file:///<ASRoot>/web/doc/apidocs/com.ibm.xml.parser.TXElement.html#_top_),
the method must return either a modified TXElement object or null if the
element is to be removed from the DOM tree.
An example element handler can be found in
<ASRoot>\samples\XtremeXML\itineraryHandler.java.
To create a Java application that can register and use the element handler with
the parser, perform the following steps:
1. Import the required packages by placing the following lines at the top of your
code:
import com.ibm.xml.parser.*;
import org.w3c.dom.*;
2. Import the package or class containing the element handler or handlers that
you wish to use. For example:
158
WebSphere Application Servers: Standard and Advanced Editions
import itineraryHandler;
3. Create a parser instance to work with, specifying a file to use for error
messages:
Parser parser = new Parser("xslparse.err");
4. Register the element handler or handlers created with the parser by calling the
parser.addElementHandler method. For example, to add a handler for the
outbound-airline element the following code could be used:
parser.addElementHandler(new itineraryHandler(), "outbound-airline");
If a general element handler is to be registered, that is, one that is called for all
elements rather than a specific element, then do not include the second string
parameter with the element name.
5. Call one of the readStream methods on the parser to read the XML input
stream and call the handlers. When the readStream method is called, the
DOM tree is built and the handlers that are registered for each element are
called in order of their registration, with the handlers for specific tags being
called before any general handlers. For example, to read and process the XML
stored in a java.io.ByteArrayInputStream variable (bais), you could code the
following:
doc = parser.readStream(bais);
An example of a program that uses a handler to perform transformations in the
DOM tree prior to processing can be found in
<ASRoot>\samples\XtremeXML\parseXMLUsingElementHandlers.java.
It is also possible to register a number of other handlers to work with different
sorts of events, other than element events. Table 13 shows the different methods
that can be called on a com.ibm.xml.parser.Parser object to register different
sorts of handlers with the parser. It also shows the circumstances under which
each element handler’s methods are called and the name of the interface that
must be implemented for each different sort of handler. Full details about the API
for these handlers can be found at
file:///<ASRoot>/web/doc/apidocs/com.ibm.xml.parser.Parser.html#_top_.
Table 13. Register Event Handlers for com.ibm.xml.parser.Parser Instances
Method to Register
addElementHandler
When Handler is
Called
Called when an
element tag is
recognized. If an
optional element
name is specified it
will be called for only
that element;
otherwise, the
handler will be called
for all elements.
Handler Interface Name
(in com.ibm.xml parser)
ElementHandler
Content Presentation
159
Method to Register
When Handler is
Called
Handler Interface Name
(in com.ibm.xml parser)
addNoRequiredAttributeHandler
Called when the
parser detects that
an attribute that is
marked as required
on the DTD has not
been included on an
element.
NoRequiredAttributeHandler
addPIHandler
Called when the
parser recognizes
an XML processing
instruction.
PIHandler
addPreRootHandler
Called after the
DTDs (if any) have
been parsed but
before any elements
in the XML
document have
been parsed.
PreRootHandler
setTagHandler
Called when an
element tag start
and tag end are
recognized.
TagHandler
setReferenceHandler
Called when a
general entity
reference is
recognized (prior to
parsing any entity
streams) and after
all entity streams for
a general reference
have been parsed.
ReferenceHandler
3.3.3.3 Parsing Using the DOM Tree Parser
DOM tree parsing is the most sophisticated, and hence the most complex,
method of parsing XML. Unlike event-driven parsing, such as SAX parsing and
parsing using element handlers, DOM tree parsing is performed after the parser
has done its work and constructed a data structure called a Document Object
Model tree or DOM tree. This tree is then navigated by various methods and can
also be manipulated.
The abstract specification for the DOM was created by the World Wide Web
Consortium (known as W3C) and is available online at
http://www.w3.org/TR/PR-DOM-Level-1/. W3C also specified Java language
bindings for the DOM in the package org.w3c.dom. These bindings can be found
in an appendix to the DOM specification at
http://www.w3.org/TR/PR-DOM-Level-1/java-language-binding.html. WebSphere
includes javadoc documentation for the org.w3c.dom package at
file:///<ASRoot>/web/doc/apidocs/Package-org.w3c.dom.html. WebSphere also
includes an IBM implementation of the DOM Java language bindings in the
package com.ibm.xml.parser, and the complete API details are available at
file:///<ASRoot>/web/doc/apidocs/Package-com.ibm.xml.parser.html.
160
WebSphere Application Servers: Standard and Advanced Editions
Working with DOM parsing involves two steps: first creating the DOM tree from
the input source, and secondly navigating the tree to process the XML. The
following steps are required to produce a DOM tree in an application:
1. Add lines to the code to import the W3C and IBM DOM packages such as the
following:
import com.ibm.xml.parser.*;
import org.w3c.dom.*;
2. Create an instance of the parser specifying the location of the error file:
Parser parser = new Parser("xslparse.err");
3. Use one of the readStream methods to parse the input XML and return a
reference to the root of the parsed XML tree. For example, the following line of
code reads input XML from a java.io.ByteArrayInputStream(bais) and stores it
in a com.ibm.xml.parser.TXDocument object doc:
doc = parser.readStream(bais);
Once you have a reference to the root of the document tree you can then begin to
process the elements within that tree. Table 14 on page 161 shows the types of
entities that you may encounter in processing a DOM tree along with a brief
description and a reference to the package in which they reside. For further
detail, the API documentation is installed with WebSphere at
file:///<ASRoot>/web/doc/apidocs/packages.html and the DOM documentation
can be found at http://www.w3.org/TR/PR-DOM-Level-1/.
Table 14. Data Item Types Found in a DOM Tree
Data Item
Description
Implementation Class
Implementation Package
Document
The whole document tree. The
Document object contains all
the other objects.
TXDocument
com.ibm.xml.parser
DocumentFragment
A part of a document.
Document fragments do not
exist in the tree; they are
created and used during
processing.
TXDocumentFragment
com.ibm.xml.parser
DocumentType
A data structure representing
the DTD for this XML
document. This may be null if
no DTD was specified.
DTD
com.ibm.xml.parser
EntityReference
A reference to the value of a
previously defined entity
object. Usually the parser
replaces the EntityReference
with the value of the referred
entity object.
EntityReference
org.w3c.dom
Node
Node is the parent interface for
all of the objects in the DOM
tree. Methods on the node
element are the primary
means of navigation about the
tree.
Node
org.w3c.dom
Content Presentation
161
Data Item
Description
Implementation Class
Implementation Package
Element
An element in a document.
Most of the objects in a
document will be Elements.
TXElement
com.ibm.xml.parser
Attribute
An attribute associated with an
Entity. Attributes will only be
children of the owning Entity
node.
TXAttribute
com.ibm.xml.parser
ProcessingInstruction
An instruction to an XML
processor.
TXPI
com.ibm.xml.parser
Comment
A comment placed in the XML.
TXComment
com.ibm.xml.parser
Text
Content inside the start and
end tags of an element that is
not itself an element definition.
TXText
com.ibm.xml.parser
CDATASection
Section of text in which data
with tags may be included
without interpretation by the
parser.
TXCDATASection
com.ibm.xml.parser
Entity
Entities are used to provide a
shorthand for something else
such as special characters or
binary data.
EntityDecl
com.ibm.xml.parser
Notation
Notations are a way of telling
external applications the
format of the data preceding
them. For more details see the
XML 1.0 spec, section 4.7.
TXNotation
com.ibm.xml.parser
In practice, most of the work that is done in processing DOM trees uses the Node,
Document and Element objects. The following are a few common techniques
used in navigating and processing a DOM tree:
• Use the hasChildren() method on the Node interface to determine if a Node
has children.
• Use the getFirstChild(), getLastChild(), getNextSibling(), getPreviousSibling()
and getParentNode() methods on the Node interface to navigate around the
tree.
• Use the appendChild(Node), insertBefore(Node,Node), removeChild(Node)
and replaceChild(Node) on the Node interface to manipulate the children of a
node.
• Use the getNodeType() method on the Node interface to determine a Node’s
type.
• Use the createXXXX methods on the Document interface to create new
objects for insertion into the DOM tree.
• Use the different getAttribute, setAttribute and removeAttribute methods on
the Element interface to manipulate Attributes.
• Use the searchXXXX and getNthElementXXXX methods on the Element
interface to find different descendants.
162
WebSphere Application Servers: Standard and Advanced Editions
The parseXML example found in <ASRoot>\samples\XtremeXML\parseXML.java
shows the use of a number of these techniques.
3.3.4 XML Catalogs
WebSphere includes a catalog of public XML DTDs for use by applications.
Catalogs are useful when you have valid XML or when you are using industry
standard DTDs, and you want to abstract the exact locations of the DTDs. Figure
147 on page 164 shows a short Java program that gives an example of how to
use the catalog feature to provide a DTD for a small XML sample
OTP_v_0-99.xml as shown in Figure 146 on page 163.
<?xml version="1.0" ?>
<!DOCTYPE OtpMessage PUBLIC "-//Open Trading Protocol//DTD Open Trading
Protocol//EN" "OTP_v_0-99.dtd" >
<OtpMessage>
<TransRefBlk ID="M1">
<TransId ID="M1.1" OtpTransId="A1" OtpTransType="A2"
TransTimeStamp="A3"/>
<MsgId ID="M1.2" xml:lang="us-en" SoftwareId="B2"/>
</TransRefBlk>
<PingReqBlk ID="M2"/>
</OtpMessage>
Figure 146. OTP_v_0-99.xml
Content Presentation
163
package com.ibm.pjk.xml;
import com.ibm.xml.parser.*;
import java.io.*;
/**
* This type was created in VisualAge.
*/
public class CatalogTester {
/**
* CatalogTester constructor comment.
*/
public CatalogTester() {
super();
}
/**
* This method was created in VisualAge.
* @param args java.lang.String[]
*/
public static void main(String args[]) {
TXDocument doc = null;
String fname = "d:\\data\\catalog\\xmlparse.err";
String catalogFilespec =
"d:\\WebSphere\\AppServer\\web\\xml\\grammar\\dtd\\dtd.cat";
String xmlSource = "d:\\data\\catalog\\OTP_v_0-99.xml";
Stderr se = new Stderr(xmlSource);
try {
FileReader rr = new FileReader(catalogFilespec);
se.loadCatalog(rr);
rr.close();
} catch (java.io.IOException e) {
e.printStackTrace();
}
Source src = null;
try {
src = se.getInputStream(fname, null,
Stderr.file2URL(fname).toString());
} catch (java.io.IOException e) {
e.printStackTrace();
}
Parser pc = new Parser(xmlSource, se, se);
doc = pc.readStream(src);
}
}
Figure 147. Sample Java Code to Use an XML Catalog
This XML sample uses a public DTD for the Open Trading Protocol. More details
on the OTP are available at http://www.otp.org/.
3.3.5 XML Style Sheets and LotusXSL
To present XML data on a client machine it has to be formatted graphically in
some way. HTML handles this problem by defining a fixed set of tags that define
content and formatting at the same time. XML, on the other hand, seeks to
separate the content of the data from how it is presented. The eXtensible Style
sheet Language (XSL) seeks to complete the picture by defining a set of
164
WebSphere Application Servers: Standard and Advanced Editions
formatting elements that can be added to XML documents to describe how they
should be presented to a client. More importantly, it is a mechanism for
transforming an XML document to add those formatting elements without
affecting the source XML.
The XSL standard, which at the time of writing had not been finalized, consists of
two parts:
• A language for transforming XML documents
This is a way for a style sheet to specify which elements in an XML document
are to be transformed and how they are to be transformed. The idea is that a
parsed XML source DOM tree is input to the XSL processor and the tree is
modified to produce an output DOM tree based on instructions placed in an
XSL style sheet. This mechanism, also called XSL transformations (XSLT),
was originally designed to allow the addition of formatting tags to an XML
document. It is also useful in a more general sense for specifying other
transformations to XML documents, such as formatting them into HTML. More
information on XSLT can be found at the W3C site at http://www.w3c.org. The
latest draft of the specification available at the time of writing was at
http://www.w3.org/TR/1999/WD-xslt-19990421.
• An XML vocabulary for specifying formatting semantics
For an XSL formatter to correctly present a graphical view of an XML
document to a client there must be a well-understood set of formatting
commands for the formatter to process in constructing the output. The XSL
formatting language defines a rich set of formatting tags using an XML DTD to
define the formatting language and a specification to define the meanings of
the tags that comprise the formatting language. These tags can then be
interpreted and processed by an XSL formatter. This language is described
further in the documentation at http://www.w3c.org. The latest draft of the
specification available at the time of writing may be found at
http://www.w3.org/TR/WD-xsl/.
Another good source of information on XSL is the online magazine XML.com
(http://www.xml.com) which has a number of XSL articles at
http://www.xml.com/xml/pub/Style. Articles here need to be read carefully as the
XSL specification may have been different when the article was written. The
documentation for the tool being used is always the final arbiter.
To understand XSL fully it is also useful to understand the semantics of XML
namespaces. One good article to look at would be "XML Namespaces by
Example" by Tim Bray at http://www.xml.com/xml/pub/1999/01/namespaces.html.
The W3C specification for namespaces can be found at
http://www.w3.org/TR/REC-xml_names/.
To facilitate XSL transformations, WebSphere XML Document Structure Services
includes a version of the LotusXSL tool which can be used to effect XSL
transformations using XSL style sheets. It can be found in the lib directory
(<ASRoot>/lib/lotusxsl.jar). At the time that WebSphere 2.02 was built the XSL
standard was still very immature, but it has undergone considerable change. It is
suggested that a newer version of LotusXSL from http://www.alphaworks.ibm.com
be installed to process XSL (see 3.3.7, “Installing Later Versions of the XML
Tools” on page 185 for information on how to do this). At the time of writing, the
latest version available was 0.17.1.
Content Presentation
165
3.3.6 Example: Using XSL and XML to Format DB2 Data
To illustrate the uses of XSL we created a sample servlet using LotusXSL to
process XML data generated from a DB2 query so that it could be output to a
browser as HTML. The following sections will show you the relevant features of
the servlet and explain the relevant features of XSL. References in the text will
point to more complete reference documentation.
3.3.6.1 Setting Up the Environment
To work with LotusXSL we installed a later version of the processor from the
alphaWorks Web site and a later version of XML4J. It is recommended that before
working with XSL you download and install the latest versions, since the XSL
standard is continually evolving. See 3.3.7, “Installing Later Versions of the XML
Tools” on page 185 for details on how to perform this task. We installed LotusXSL
Version 0.16.5 and XML4J Version 2.0.6. We also tried the code with LotusXSL
Version 0.17.0, which became available during the writing of this section (see
3.3.6.11, “Release 0.17.0 of LotusXSL” on page 184).
Already present on the machine were DB2 and WebSphere Application Server
2.02 Advanced Edition. The DB2 sample database had been created.
3.3.6.2 Creating a DTD
The first thing we did in our XML project was to create a Data Type Definition
(DTD) describing the data that we wanted to model. You only need a DTD if you
want to validate the XML data against a schema. Figure 148 on page 167 shows
the DTD in its finished form. The data we wanted to model was the employee
table from the DB2 sample database. Note the following points:
• Each row in the employee table represents a single employee, but we want to
model a number of employees. Hence the top level element of our document is
called "employees". We define the top level element thus:
<!ELEMENT employees (employee)+>
meaning that an "employees" consists of one or more "employee" elements as
denoted by the "+" sign.
• The employee element is declared as having name, phone, hiredate, title,
birthdate, salary, bonus and commission components and empnum, edlevel,
department and sex attributes. This division between attributes and child
elements is somewhat arbitrary, but the usual rule of thumb is that if the
element has an existence or structure of its own apart from its owning
element, then it should be an element; otherwise it should be an attribute. It
really doesn’t matter in the long run and a different division could have been
argued. The child components with structure, namely name, birthdate and
hiredate definitely need to be elements, since they have attributes of their
own.
• The element "name" is declared as empty because all of its data is contained
in its attributes, first, midinit and last, and so there is no need to specify the
content of this element. We will see later that this means that the "name"
element is its own start and end tag. The "name" element brings together the
first name, middle initial, and last name columns in the employee table into a
single element, giving the flexibility to treat the name as a whole while still
allowing access to its individual components.
166
WebSphere Application Servers: Standard and Advanced Editions
• The "hiredate" and "birthdate" elements, while being empty elements like the
"name" element, take the opposite approach in terms of combining columns,
in that they take single columns in the database and split them so that their
individual components, the day, month, and year, are accessible. We will see
later that this allows great flexibility in formatting the dates in XML (see
3.3.6.4, “Developing an XSL Style Sheet” on page 169 for examples of the
different ways that dates were formatted).
<?xml encoding="US-ASCII"?>
<!-- Revision: 1.0, xml4j2, xml4j2_0_6 -->
<!-- employee.dtd -->
<!ELEMENT employees (employee)+>
<!ELEMENT employee (name,
phone,
hiredate,
title,
birthdate,
salary,
bonus,
commission)>
<!ATTLIST employee empnum ID #REQUIRED
department CDATA #REQUIRED
edlevel CDATA #REQUIRED
sex CDATA #REQUIRED>
<!ELEMENT name EMPTY>
<!ATTLIST name first CDATA #REQUIRED
midinit CDATA #IMPLIED
last CDATA #REQUIRED>
<!ELEMENT firstname (#PCDATA)>
<!ELEMENT midinit (#PCDATA)>
<!ELEMENT lastname (#PCDATA)>
<!ELEMENT phone (#PCDATA)>
<!ELEMENT hiredate EMPTY>
<!ATTLIST hiredate year CDATA #REQUIRED
month (01|02|03|04|05|06|07|08|09|10|11|12) #REQUIRED
day
(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|2
5|26|27|28|29|30|31) #REQUIRED>
<!ELEMENT title (#PCDATA)>
<!ELEMENT birthdate EMPTY>
<!ATTLIST birthdate year CDATA #REQUIRED
month (01|02|03|04|05|06|07|08|09|10|11|12) #REQUIRED
day
(01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|2
5|26|27|28|29|30|31) #REQUIRED>
<!ELEMENT salary (#PCDATA)>
<!ELEMENT bonus (#PCDATA)>
<!ELEMENT commission (#PCDATA)>
Figure 148. The Data Type Definition for the Employee Table
• The day and month attributes for the hiredate and birthdate elements utilize
the "|" (OR) operator to define a list of possible values. This makes error
detection easier, since wrong values will be detected by the parser and error
messages generated. This was found to be very useful during development
when it was found that the Java GregorianCalendar class returned month
Content Presentation
167
values in the range 0 to 11 rather than 1 to 12, which caused the parser to
complain that "00" was not a valid month and caused some code rewriting to
perform the conversion.
The year attribute would have been much more difficult to treat in this manner,
and in this case it was left as (#PCDATA). The code that is shown later makes
sure that there are no Y2K issues with the data by filtering all values through
the Java GregorianCalendar class, but to be really safe the DTD could be
modified to reject invalid year values. This is left as an exercise for the reader.
• The other elements are declared as (#PCDATA), which means that they
contain character data in an unspecified format.
There is an excellent tutorial on the IBM XML developer site describing how to
write XML and create DTDs. See
http://www.software.ibm.com/developer/library/tutorial-prog/writing.html#dtds
for a more exhaustive treatment of the syntax.
3.3.6.3 Building the First XML Document
In building an XML application that produces dynamically generated XML, it is
always useful to have a sample of the finished product to which you can refer.
Figure 149 on page 169 shows the XML file that was hand generated using the
DB2 tools to look at the data in the database and convert it to XML based on the
DTD already developed. You may want to refer back to Figure 148 on page 167 to
check the generated data against the DTD.
Ignore for the moment the style sheet processing directive on line 2, but do note
the DOCTYPE declaration on line 4 that points back to the DTD and references
the top level element employees. At the moment this declaration points to a file on
the local file system, but when we generate this XML dynamically in 3.3.6.6, “The
Servlet Code” on page 175 we will replace this file reference with a URL
reference.
168
WebSphere Application Servers: Standard and Advanced Editions
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="\data\employee\employee.xsl" ?>
<!DOCTYPE employees SYSTEM "file:/d:/data/employee/employee.dtd">
<employees>
<employee empnum="E000010"
department="A00"
edlevel="18"
sex="F">
<name first="SHILI" midinit="I" last="HAAS"/>
<phone>3978</phone>
<hiredate year="1965" month="01" day="01"/>
<title>PRES</title>
<birthdate year="1933" month="08" day="24"/>
<salary>52750.00</salary>
<bonus>1000.00</bonus>
<commission>4220.00</commission>
</employee>
<employee empnum="E000020"
department="B01"
edlevel="18"
sex="F">
<name first="MICHAEL" midinit="L" last="THOMPSON"/>
<phone>3476</phone>
<hiredate year="1973" month="10" day="10"/>
<title>MANAGER</title>
<birthdate year="1948" month="02" day="02"/>
<salary>41250.00</salary>
<bonus>800.00</bonus>
<commission>3300.00</commission>
</employee>
<employee empnum="E000030"
department="C01"
edlevel="18"
sex="F">
<name first="SALLY" midinit="A" last="KWAN"/>
<phone>4738</phone>
<hiredate year="1975" month="04" day="05"/>
<title>MANAGER</title>
<birthdate year="1941" month="05" day="11"/>
<salary>38250.00</salary>
<bonus>800.00</bonus>
<commission>3060.00</commission>
</employee>
</employees>
Figure 149. The Hand-Generated XML File Used in Development
3.3.6.4 Developing an XSL Style Sheet
The next stage in the process is to develop an XSL style sheet to effect the
transformations required in the XML data. In this project we developed three style
sheets to demonstrate how the same data can be transformed in different ways
by using different style sheets.
Content Presentation
169
The method that we used to develop the style sheets was to look at examples,
particularly those shipped with the LotusXSL tool, and adapt them to our
purposes. The style sheets take the XML data and use pattern templates to
recognize tag structures within the XML. These templates then specify what data
is to replace the specified element or attribute.
For an introduction to the development of XSL style sheets, see the article by
Norman Walsh at http://www.xml.com/xml/pub/1999/01/walsh3.html (but note that
the XSL semantics have changed slightly since this article was published).
Figure 150 on page 171 shows the first of the style sheets that we developed:
phonelist.xsl. The following points are worth noting:
• The first step is to declare three namespaces. The first one serves to tell the
XSL processor where to find the definitions for the XSL transformation
language. We use the older http://www.w3.org/TR/WD-xsl definition of the XSL
namespace that is compatible with LotusXSL Version 0.16.5. If we were using
LotusXSL Version 0.17.0 this value would be
http://www.w3.org/XSL/Transform/1.0.
170
WebSphere Application Servers: Standard and Advanced Editions
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl"
xmlns="http://www.w3.org/TR/REC-html40" result-ns="">
<xsl:template match="/">
<HTML>
<HEAD>
<TITLE>XML Formatting Servlet</TITLE>
</HEAD>
<BODY>
<H1>XSL Processing Example</H1>
<xsl:apply-templates/>
</BODY>
</HTML>
</xsl:template>
<xsl:template match="employees">
<TABLE border="1" frame="border" rules="all" cellpadding="2">
<CAPTION class="listingCaptions">Phone List</CAPTION>
<COLGROUP>
<COL width="30" align="right"/>
<COL padding-left="15"/>
<COL padding-left="15"/>
<COL padding-left="15" align="center"/>
</COLGROUP>
<THEAD class="tableHead">
<TD>Name</TD>
<TD>Phone</TD>
<TD>Title</TD>
<TD>Department</TD>
</THEAD>
<xsl:for-each select="employee">
<!-- The '.' context is now the "employee" element -->
<xsl:sort select="name/@last"
order="ascending" data-type="text"/>
<xsl:sort select="name/@midinit" order="ascending" data-type="text"/>
<xsl:sort select="name/@first"
order="ascending" data-type="text"/>
<TR>
<TD class="cell">
<!-- process the text from the "name" element -->
<xsl:apply-templates select="name"/>
</TD>
<TD class="cell">
<!-- get the text from the "phone" element -->
<xsl:value-of select="phone"/>
</TD>
<TD class="cell">
<!-- get the text from the "title" element -->
<xsl:value-of select="title"/>
</TD>
<TD class="cell">
<!-- process the text from the "birthdate" element -->
<xsl:value-of select="@department"/>
</TD>
</TR>
</xsl:for-each>
</TABLE>
</xsl:template>
<xsl:template match="name">
<xsl:value-of select="@last"/>
<xsl:text>, </xsl:text>
<xsl:value-of select="@first"/>
<xsl:text> </xsl:text>
<xsl:value-of select="@midinit"/>
</xsl:template>
</xsl:stylesheet>
Figure 150. Phonelist.xsl
• On the next line we define the default namespace, the one that applies if we
specify no prefix on the tags, to be the HTML 4.0 namespace. This line also
declares the result namespace to take the default value that is the same as the
default namespace. See "XML Namespaces by Example" by Tim Bray at
http://www.xml.com/xml/pub/1999/01/namespaces.html for more information on
understanding XML namespaces.
Content Presentation
171
• Next we declare an xsl:template that matches "/". Just like in a file system, the
"/" matches the root element of any XML tree. In our case this is a convenient
place to specify some boilerplate HTML that will serve as a wrapper for all of
the other HTML that we will produce. Note also that within this template we
have an XSL directive:
<xsl:apply-templates/>
which is an instruction for the XSL processor to look at all of the descendants
of the current element, in this case the root element of the XML tree, and
match any templates that apply. If this instruction were left out, the XSL
processor would stop processing after producing the text for the root element
and not apply the other tags.
• The next step is to declare a template that matches the "employees" element,
which as you will remember is the top level element in our XML document.
Within the employees element we produce the outer definitions for the HTML
table that will hold our data. Within this table definition there is another XSL
processing instruction:
<xsl:for-each select="employee">
which requires the end tag:
</xsl:for-each>
further down in the code. This tells the XSL processor to look for each node in
the XML source tree that matches the pattern contained in the select attribute
and for each of them replace them with the text contained within the
xsl:for-each tag. See the June 1999 issue of Web Techniques Magazine at
http://www.webtechniques.com for Michael Floyd’s column "Beyond HTML" for a
good tutorial on how to write XSL patterns. In this case the pattern will match
employee element children of the current node that is the employees element.
• Within the xsl:for-each tag we have the code to generate an individual table
row. The first thing that we see is a group of xsl:sort directives:
<xsl:sort select="name/@last"
order="ascending" data-type="text"/>
<xsl:sort select="name/@midinit" order="ascending" data-type="text"/>
<xsl:sort select="name/@first"
order="ascending" data-type="text"/>
These have the effect of telling the XSL processor to sort the output of the
xsl:for-each tag by certain criteria before producing the output. The criteria are
specified by specifying a pattern that is evaluated for each node processed by
the xsl:for-each directive and then sorted according to the other criteria. In this
case we specify that the sorting is to be first by the "last" attribute of the
"name" element that is a child of the current employee element, and then
within that, by the "midinit" and "first" attributes. In each case the sorting is to
be ascending and based on the text collation order of the current language
and character set. The effect of these directives is to sort by last name, then
within that to sort by middle initial, and then within that to sort by first name.
The next part of the xsl:for-each tag is the HTML commands to generate the
cells in the table row for this employee element. You will notice a number of
XSL directives similar to the following:
<xsl:value-of select="phone"/>
These have the effect of taking any text that is included between the start and
end tags of the element specified and inserting it in the results. We could have
also specified a pattern resolving to an attribute here, in which case the
attribute value would have been inserted. This allows us to insert data from
172
WebSphere Application Servers: Standard and Advanced Editions
the XML into our output rather than just using the node structure to generate
output as we have been doing up until now.
The other XSL processing directive that is included in the cell definitions is the
directive to process the name tags:
<xsl:apply-templates select="name"/>
This is similar to the processing directive that we saw in the template for the
root element above, except this time we specify a pattern for the nodes that
the XML processor will look at in order to apply the templates. In our case we
only want to process the name element children of the current employee
element at this time so we use select="name".
• The last element in the XSL file is another template, this time one to match the
name element. In the template above we included an xsl:apply-templates
directive to match the name elements and this is where the information for
each name element will be produced. xsl:value-of directives are used to get
the attribute values of the name element (note the "@" signs denoting
attributes). The other new directive is the xsl:text directive, which is used to tell
the XSL processor to insert some text into the output stream. Up until now we
have been producing HTML tagged data that conforms to the default
namespace we declared at the beginning of the file:
xmlns="http://www.w3.org/TR/REC-html40"
If we want the XSL processor to produce text in the output that is not part of a
tag we need to use the xsl:text directive. The effect of these directives is to
cause the last name to be output followed by a comma and a space followed
by the first name followed by a space followed by the middle initial.
The birthday list style sheet, birthday.xsl (see Figure 151) is similar to the phone
list style sheet, but it implements a different view of the data, showing a list of
birthdays:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl"
xmlns="http://www.w3.org/TR/REC-html40" result-ns="">
<xsl:template match="/">
<HTML>
<HEAD>
<TITLE>XML Formatting Servlet</TITLE>
</HEAD>
<BODY>
<H1>XSL Processing Example</H1>
<xsl:apply-templates/>
</BODY>
</HTML>
</xsl:template>
<xsl:template match="employees">
<TABLE border="1" frame="border" rules="all" cellpadding="2">
<CAPTION class="listingCaptions">Birthday List</CAPTION>
<COLGROUP>
Figure 151. Birthday.xsl
The following differences are worth noting:
• In this style sheet we are sorting by the birth month and then the birth day
rather than by the name of the person.
• The template that we are using for the name is slightly different, showing the
first and last name separated by a space.
Content Presentation
173
• We have a new template for the birthdate producing the birth day followed by a
"/" followed by the birth month.
The seniority list style sheet, seniority.xsl (see Figure 152) is similar to the other
style sheets. It implements a view of the data, showing a list of employees with
the last hired shown first and the longest-serving employees shown last.
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl"
xmlns="http://www.w3.org/TR/REC-html40" result-ns="">
<xsl:template match="/">
<HTML>
<HEAD>
<TITLE>XML Formatting Servlet</TITLE>
</HEAD>
<BODY>
<H1>XSL Processing Example</H1>
<xsl:apply-templates/>
</BODY>
</HTML>
Figure 152. Seniority.xsl
The following differences are worth noting:
• The sort order in this style sheet is again different. Note that descending sort
order is used as well as numeric rather than text-based sorting.
• The hiredate template rearranges the order of the data fields so that the year
comes first, followed by the month followed by the day.
3.3.6.5 Building a Prototype and Fixing Problems
The next step in the development process was to hunt around for example code
from the various tools used and build a non-servlet prototype using VisualAge for
Java. This was useful, because it allowed the testing of the logic in an easily
debuggable environment away from any considerations introduced by
WebSphere. It also uncovered a number of errors in the logic as the program was
developed. The first stage was to use the hand generated XML to produce an
HTML file on the development machine and then to gradually introduce new
features till the code was extracting data from the database and producing HTML
to standard output. This process uncovered a number of things:
• XML is a complex and evolving field that necessitated much trial and error.
Hopefully this code will help to iron out some of the pitfalls, but the moment
that you try something a little different you will need to look for resources to
help you fix the problems. The following is a list of the resources that we used
during development and that you might find useful:
• The annotated XML spec at http://www.xml.com/axml/testaxml.htm. There’s
no substitute for the specification and this version makes things a little
easier to understand.
• The rest of the http://www.xml.com site.
• The IBM XML site, which at the time of writing was being moved to
http://www.ibm.com/developer/xml/.
174
WebSphere Application Servers: Standard and Advanced Editions
• The WebSphere newsgroup at
news:news.software.ibm.com/ibm.software.websphere.application-server.
• The alphaWorks LotusXSL and XML4J discussion groups at
http://www.alphaWorks.ibm.com.
• It always helps to run your stand-alone code outside of your development
environment before trying to run it as a servlet in WebSphere. The release of
LotusXSL or XML4J that we used didn’t like the JIT compiler on either of the
JDKs that we used for testing (IBM JDK 1.1.7 and Sun JDK 1.1.6). See
3.3.6.10, “Description of Errors Encountered during Development” on page
181 for a full description of the symptoms encountered. It was only after
running the code as a stand-alone program from the command line that we
were able to find this problem.
3.3.6.6 The Servlet Code
Now that we have all of the data pieces together, it is time to have a look at the
servlet code that ties everything together. Figure 153 shows the source code for
XSLServlet.java:
package com.ibm.pjk.xml;
import javax.servlet.*;
import javax.servlet.http.*;
import java.util.*;
import java.io.*;
import java.sql.*;
import com.ibm.xml.parsers.*;
import org.xml.sax.*;
import com.lotus.xsl.*;
import com.lotus.xsl.xml4j2dom.*;
/**
* This type was created in VisualAge.
Figure 153. XSLServlet.java
The following points about the code are worth noting:
• There are a number of output statements in the code that produce
informational output for debugging purposes. They have been left in to show
what the code is doing. If this code is modified to be used in a production
environment, then remove these statements. In particular the DB2 JDBC
driver log output is redirected to standard output and the XML generated from
the DB2 query is redirected to standard output.
• The DB2 driver is registered in the static block at the start of the code to
ensure that it is registered once when the class is first loaded.
• The constructor does nothing other than to call the superclass constructor.
• Among the variable declarations there are a number of machine specific
parameters:
//Machine specific parameters - change these for your environment
String userid = "peterk";
String password = "xxxxxxx";
String machineName = "wtr05073.itso.ral.ibm.com";
String dtdPath = "/employee.dtd";
Content Presentation
175
These parameters need to be changed for your environment if you want to run
this code. Note that the user ID and password were ones used during
development and bear no resemblance to real user IDs and passwords used
on production systems. The machineName value is the name of your Web
server. Change the dtdPath value to reflect the location of your DTD document
on your Web server.
• The code uses a style sheet parameter value passed to it by the HTTP request
to determine which style sheet to use. This parameter contains the complete
URL of the style sheet.
• The technique used to generate the XML and then to process it using
LotusXSL was to first write it to a byte array using a ByteArrayOutputStream.
This byte array could then be used as input to an InputStreamReader via a
ByteArrayInputStream to provide the reader argument for the LotusXSL
processor.
• The database is queried using JDBC calls. For more information on using
JDBC see 6.1, “JDBC” on page 332.
• Before adding the data for each employee the XML header information,
including the namespace declarations and the style sheet definition, are
written to the output stream. This is followed by the start tag for the document
type: <employees>.
• For each row of the database the information contained in the result set for the
query is extracted into a number of string variables for later processing.
• The hiredate and birthdate values returned from the database are in the form
of java.sql.Date values. To extract the year, month, and day values, each Date
value is inserted into a GregorianCalendar object using the setTime method
and then the individual values are extracted into an array using the
GregorianCalendar get method with the appropriate constant specifying which
value we want to get. The array values are then used later to construct the
XML.
• Next the XML is written to the output stream using the data values extracted
from the result set. This format follows closely that of the hand-created XML
shown in Figure 149 on page 169. Tabs are inserted in the output so that it is
formatted nicely for debugging purposes. Their omission would not change the
semantic content of the XML.
• After all of the employee date has been written, the end tag for the employees
element is written and the output stream is closed and flushed.
• The next step is to prepare the response header fields and to extract the print
writer from the response object so that it can be used to write the HTML. The
response object is set up to disable caching on the client so that the
dynamically generated data is regenerated each time the servlet is called
rather than being taken from a cache.
• After setting up a writer to read the XML from the byte array created earlier it is
time to do the XSL processing. The first step is to create an instance of the
XSL processor. This needs to be done each time a style sheet is processed;
you need a new instance for each operation. The argument to the constructor
is an instance of the XMLParser LiasonDefault class, which is used by
LotusXSL to provide an interface between the XSL processor and the XML4J
parser.
176
WebSphere Application Servers: Standard and Advanced Editions
• The final step is to call the process method with the reader for the XML as the
first argument and the writer from the response object, to which the HTML will
be written, as the second argument.
• The rest of the code is some error handling to print informative messages if
something should go wrong and a final clause that flushes and closes the
response object to make sure that all of the output is written.
3.3.6.7 Creating HTML to Run the Servlet
The final step in the process was to create some framework HTML to run the
servlet. Since this was only to test the servlet code, the HTML we wrote was very
basic. Figure 154 shows the HTML we used to test the servlet:
<HTML>
<HEAD>
<TITLE>WebSphere Samples</TITLE>
</HEAD>
<BODY>
<form Method="get" ACTION="/servlet/XSLServlet">
<font size=-1>StyleSheet URL</font>&nbsp;
<input type="text" name="stylesheet" size=30>
<br><br>
<input type="submit" value="Submit">
</form>
</BODY>
Figure 154. XSLTest.html
The HTML provides a text entry field in which to provide the URL for the style
sheet to use and a button to submit the data and call the servlet.
3.3.6.8 Putting It All Together
Once all of the pieces have been created it is time to put them all together. The
following tasks need to be performed:
1. Copy the DTD, XSL and HTML files on the Web server.
The following files need to be placed in a directory on the Web server
accessible via HTTP:
employee.dtd
phonelist.xsl
birthday.xsl
seniority.xsl
XSLTest.html
In our case, using the IBM HTTP server installed on Windows NT on drive D
meant putting them in the d:\Program Files\IBM HTTP Server\htdocs directory.
2. Compile the Java program and put it in the WebSphere Servlets directory.
The Java class file for the servlet needs to be compiled and placed in the
correct directory so that the WebSphere servlet engine can find it. In our case
we used the WebSphere default servlet directory which meant that the class
file had to be put in the <ASRoot>\servlets\com\ibm\pjk\xml directory
according to the package name we used: com.ibm.pjk.xml.
Content Presentation
177
3. Register the servlet to WebSphere.
The next step is to register the servlet to WebSphere so that it can be called
by a client. The procedure for adding servlets can be found in 3.1.3.2, “Adding
Servlets” on page 97. We added the servlet with an alias of XSLServlet.
4. Ensure that DB2 is running and the sample database has been created.
Because this sample uses the DB2 sample database, you need to ensure that
the DB2 database instance you will access is running and that the sample
database has been created. See your DB2 documentation for instructions on
how to create the sample database. For Windows NT you can type db2sampl in
a DB2 command window to create the sample database.
5. Run the servlet using the test HTML page.
Figure 155 on page 178, Figure 156 on page 179, and Figure 157 on page 180
show the HTML pages produced as a result of running the XSL servlet with
the phone list, birthday and seniority list style sheets respectively. To do this
we input the URLs of the style sheets on our Web server into the input field on
the test HTML page and clicked submit .
Figure 155. Results of Running the XSL Servlet with phonelist.xsl
178
WebSphere Application Servers: Standard and Advanced Editions
Note that the XML that we generate from the database is identical in every
case except for the line that specifies the style sheet. The style sheet
instructions as interpreted by the XSL processor do the rest.
Figure 156. Results of Running the XSL Servlet with birthday.xsl
Content Presentation
179
Figure 157. Results of Running the XSL Servlet with seniority.xsl
3.3.6.9 Possible Improvements and Changes
The following is a list of possible improvements or changes you might like to make
to the code when implementing it in your environment:
• The parameters that specify such things as the database user ID and
password are hard coded into the XSLServlet.java file. For more general use
these should be read from a .properties file somewhere.
• Now each time the servlet is called it must read information from the database
and regenerate the XML. It would be better if this XML could be cached
somehow and only regenerated if the database changed. The only change to
be made would be the style sheet reference.
• The HTML files generated by the XSL processor are extremely basic. They
could easily be modified to look much better through the use of images, color
and cascading style sheets (cascading HTML style sheets have nothing to do
with XSL style sheets).
• At the moment the HTML produced is for a complete HTML page. In a
production environment it may be desirable to have the servlet only produce
180
WebSphere Application Servers: Standard and Advanced Editions
the table portion of the HTML and have another part of the application, a JSP
page for instance, produce the rest of the page.
• The code could be easily adapted to read from other database tables or even
other database engines that support JDBC.
• The style sheets used only begin to scratch the surface of what can be
accomplished with XSL transformations. They could be modified to perform
more complex transformations on the XML to achieve more sophisticated
results.
3.3.6.10 Description of Errors Encountered during Development
During the development process we encountered a number of errors and
problems in completing the task. They ranged from the trivial to discovering a
potential bug in the tools themselves. There were two errors in particular that
proved difficult to track down from the information provided by various diagnostic
messages and logs. These two errors are described here in the hope that the
descriptions will save some time if you ever come across them.
1. Can’t find the class for servlet XSLServlet: null
When you are adding a servlet there is an option for WebSphere to try and test
the loading of the servlet class prior to completing the add. If, during this test,
you get a message box similar to the one shown in Figure 158, it usually
means that WebSphere cannot find a class associated with your servlet and
that you should check your classpath settings.
Figure 158. Servlet Test Error Box
In this case, however, the place where WebSphere usually puts the name of
the class it cannot find has the value null, which is most unhelpful. This null
value is WebSphere’s way of telling us that it cannot find the class itself, even
though it can find the file that the class is in. If it could not find the class file it
would give us another message.
The solution to this problem is to go back to your source code and make sure
that your servlet class is declared as public so that WebSphere can find it.
2. Running the XSLServlet causes the WebSphere Servlet Service to hang.
The symptom of this problem was that a servlet using the XML parser would
produce the error dialog shown in Figure 159 under Netscape Navigator (other
browsers would have similar messages).
Content Presentation
181
Figure 159. Netscape Error Dialog Box
Attempting to reload the servlet at this point would produce the error page
from WebSphere shown in Figure 160:
Figure 160. WebSphere Servlet Service Unavailable Page
Attempting to stop and restart WebSphere would produce the following
message in the <ASRoot>\logs\servlet\adminservice\error_log:
[May 17, 1999 3:45:05 PM EDT] Cannot start service adminservice: Port 9527
is already in use. Change the port or shut down the other network service
that is using it.
The Windows NT Task Manager would show four java.exe processes that
would give the error dialog box shown in Figure 161 when the End Process
button was used to attempt to terminate them:
Figure 161. Windows NT Process Termination Error
182
WebSphere Application Servers: Standard and Advanced Editions
The only way to get WebSphere restarted was to completely reboot the
machine.
The code would run correctly in the VisualAge for Java WebSphere test
environment.
The way that this problem was diagnosed was to create a non-servlet class to
run the XML processing code outside of VisualAge using the command line.
When this was tried the following messages were printed to standard output:
+++
+++
+++
+++
+++
+++
+++
+++
+++
+++
+++
...
EXCEPTION:
EXCEPTION:
EXCEPTION:
EXCEPTION:
EXCEPTION:
EXCEPTION:
EXCEPTION:
EXCEPTION:
EXCEPTION:
EXCEPTION:
EXCEPTION:
Unknown
Unknown
Unknown
Unknown
Unknown
Unknown
Unknown
Unknown
Unknown
Unknown
Unknown
(code=c0000005)
(code=c0000005)
(code=c0000005)
(code=c0000005)
(code=c0000005)
(code=c0000005)
(code=c0000005)
(code=c0000005)
(code=c0000005)
(code=c0000005)
(code=c0000005)
for
for
for
for
for
for
for
for
for
for
for
JITC
JITC
JITC
JITC
JITC
JITC
JITC
JITC
JITC
JITC
JITC
at
at
at
at
at
at
at
at
at
at
at
10054a1a
10054a1a
10054a1a
10054a1a
10054a1a
10054a1a
10054a1a
10054a1a
10054a1a
10054a1a
10054a1a
(id=1d0)
(id=1d0)
(id=1d0)
(id=1d0)
(id=1d0)
(id=1d0)
(id=1d0)
(id=1d0)
(id=1d0)
(id=1d0)
(id=1d0)
Figure 162. Messages Sent to Standard Output
This indicated a problem with the JIT compiler. The stand-alone program was
also run on another system and no error messages were printed to standard
output, but no HTML was produced.
When the JIT compiler was turned off using the -nojit flag on the command
line the stand-alone program worked properly.
The solution to this problem was to turn off the JIT compiler in WebSphere. To
do this, log on to the administration interface and click Setup -> Java Engine
and select the Directives tab (see Figure 163 on page 184). Add the directive
-nojit to the Java Compiler field (if you are using the IBM or Sun JVM, other
JVMs may have different commands).
Note: It is possible that a later version of the JIT compiler works better. We
were advised that a later level should work, but we did not have the time to
verify that during this project.
Content Presentation
183
Figure 163. The WebSphere Java Engine Directives Page
3.3.6.11 Release 0.17.0 of LotusXSL
We also tried running the code under Release 0.17.0 of LotusXSL with limited
success. This release of LotusXSL conforms to the April 21, 1999 version of the
XSLT specification which can be found at
http://www.w3.org/TR/1999/WD-xslt-19990421.html. The only change that we made
to the code was to add a different namespace URL to the XSL style sheets,
replacing http://www.w3.org/TR/WD-xsl with http://www.w3.org/XSL/Transform/1.0.
The results of running the birthday.xsl style sheet (see Figure 151 on page 173)
with the later release are shown in Figure 164.
We were unable to determine if the duplicated table header was the result of a
change in the XSL specification that necessitated a change in our XSL style
sheet or a bug in LotusXSL.
184
WebSphere Application Servers: Standard and Advanced Editions
Figure 164. Results of Running birthday.xsl with LotusXSL V0.17.0
3.3.7 Installing Later Versions of the XML Tools
So far most of this section has been confined to discussing the version of the
XML document Structure Services shipped with WebSphere 2.02. These services
are based on a version of the IBM XML for Java parser and on a version of the
LotusXSL style sheet processor. Newer versions of these technologies are
available from the IBM alphaWorks Web site at http://www.alphaworks.ibm.com
and these can be installed in place of the versions shipped with the product.
To install a newer version, download the new distribution file and unpack it
according to the download instructions, then perform the following steps:
1. Locate the JAR files containing the product APIs.
These files will probably be located in the top level directory to which you
unpacked the tools. For the IBM XML for Java parser this file will be called
xml4j.jar. For LotusXSL it will be called lotusxsl.jar.
2. Make backup copies of the original product files.
Content Presentation
185
The JAR files shipped with the original product are located in the directory
<ASRoot>\lib. Copy the files xml4j.jar and lotusxsl.jar to a safe location to
enable you to back out the changes if there are problems. You may need to
stop the WebSphere servlet engine in order to release the locks on the files so
that you can accomplish this. On Windows NT go to Start ->Settings-> Control
Panel , then double-click Services. When the services window opens, scroll
down and select the WebSphere Servlet Service and click Stop.
3. Copy the new files to the WebSphere lib directory.
Copy the xml4j.jar and lotusxsl.jar files that you located in step 1 to the
<ASRoot>\lib directory in place of the original files.
4. Stop and restart the Web server to pick up the changes.
An alternative to the above procedure would be to add the xml4j.jar and
lotusxsl.jar files to the application server classpath in place of the ones shipped
with the original product. The procedure to add files to the classpath is covered in
3.3.2, “Setting Up the Environment” on page 154.
WebSphere 2.02 ships with Version 1 of the IBM XML parser for Java. The latest
version available when this book was being written was 2.0.6. There have been
significant changes to the API between these two releases, so a careful study of
the documentation is required in order to understand if any change in applications
developed with the older APIs is desirable or necessary. In particular there has
been a new package added: com.ibm.xml.parsers (as opposed to
com.ibm.xml.parser), which includes a number of parser variants that conform
more closely to the W3C standard and have better performance. These parsers
do not have all of the functionality of the older APIs. The Version 1 APIs are still
present in the product and they are referred to as the TX Compatibility APIs in the
documentation.
If installing a newer version of LotusXSL it should be noted that there are
dependencies between LotusXSL and the IBM XML for Java parser. These
dependencies are detailed in the LotusXSL documentation.
The WebSphere XML samples were tested with the IBM XML for Java parser
Version 2.0.6 and the event-driven parsing samples. The SAX parser sample, and
the sample on parsing using event handlers, did not work for us. Please check the
documentation for any new version that is available to install.
186
WebSphere Application Servers: Standard and Advanced Editions
Chapter 4. Enterprise Java Services
Note: Enterprise Java Services are not included with WebSphere Application
Server 2.X Standard Edition. These features are included only in the Advanced
Edition.
Enterprise Java Services, or EJS, is the WebSphere component that allows the
deployment and management of Enterprise Java Beans in EJB containers. It is in
fact made up of a number of interrelated pieces including a naming service, EJB
containers and management services. In this chapter we will look at how to work
with EJS, including how to install and run the WebSphere EJS samples.
What we will not look at in this chapter is how to develop EJBs or EJB clients.
This is beyond the scope of this book. Where appropriate, references have been
made in this chapter to reference materials relating to EJB development. Readers
are encouraged to review the EJB overview presented in 1.3.5, “Enterprise Java
Beans” on page 6.
A more in-depth technical overview of EJB development can be found at
http://java.sun.com/products/ejb/developers-guide.pdf.
4.1 The EJS Java Processes
EJS runs three processes on your WebSphere system when enabled. The
Persistent Naming Service (PNS) and Location Service Daemon (LSD)
processes are used by EJS to provide naming services to EJB clients so that they
can locate EJBs deployed on the server. The EJS Server process is where the
EJB containers and management services run. Each of these processes runs in a
separate Java Virtual Machine on the server. This is in addition to the servlet
service process that also runs in its own virtual machine.
Figure 165 shows the results of running ps -ef | grep java on an AIX system to
display the Java processes running on the machine. The first process is the
servlet process followed by the LSD, PNS and EJS server processes and finally
the grep command itself.
# ps -ef | grep java
nobody 24510
1 1 May 14 pts/2 118:17 java
com/ibm/servlet/engine/outofproc/OutOfProcEngine -nativelogfile
/usr/WebSphere/AppServer/logs/oop_native.log -nativeloglevel 14 -linktype local -port 8081
-queuename ibmappserve -stublib /usr/WebSphere/AppServer/plugins/aix/libosestub.so -serverlib
/usr/WebSphere/AppServer/plugins/aix/libasouts.so
nobody 26060 24510 0 May 14 pts/2 0:43 java com/ibm/servlet/ejs/LSDInstance 9091
controller 9030 LSD localhost 9029
nobody 26332 24510 0 May 14 pts/2 0:44 java com/ibm/servlet/ejs/PNSInstance 9091
controller 9028 PNS localhost localhost 9029 /usr/WebSphere/AppServer//temp 9019
nobody 26596 24510 0 May 14 pts/2 51:52 java com/ibm/servlet/ejs/EJSInstance 9091
controller 9027 EJS localhost 9029 /usr/WebSphere/AppServer//properties/ejs/ejs.properties
9019 /usr/WebSphere/AppServer/ null
root 29370 21424 1 16:08:01 pts/1 0:00 grep java
Figure 165. Java Processes on an AIX System Showing the Three EJS Processes
© Copyright IBM Corp. 1999
187
On Windows NT it is more difficult to tell the four Java processes apart. Figure
166 on page 188 shows a screen from Windows NT task manager. The four
java.exe processes shown in the middle of the screen belong to WebSphere.
Java Processes
Figure 166. Windows NT Task Manager Showing the Four WebSphere Java Processes
4.2 Configuring Enterprise Java Services
This section shows the steps required to configure EJS and deploy EJBs in
WebSphere Application Server. Most of these procedures assume that you are
logged on to the WebSphere Application Server Administration Interface using
your administrator user ID and password. This can be achieved by opening the
Web address http://<your server name>:9527/ and typing your user ID and
password in the fields provided.
4.2.1 Setting Up the Environment
Most of the environment setup for EJS is covered in the sections on working with
containers and deploying EJBs, but there are a few other parameters that affect
how the EJS services will run.
Figure 167 shows the entry field area of the EJS global settings page that can be
reached by logging on to WebSphere Administration and then selecting
Enterprise Java Services -> Global Settings.
188
WebSphere Application Servers: Standard and Advanced Editions
Figure 167. The EJS Global Settings Page
Table 15 shows the fields and their possible values:
Table 15. Field Values for EJS Configuration
Field Name
Description
Enable EJS
This field allows EJS to be enabled or
disabled. EJS is enabled by default.
EJS Server Name
This is the JNDI name of the WebSphere
EJS server. By default this is set to server1.
Remote Access
This parameter relates to whether or not
remote clients have access to the EJS
server.
Enable EJS Tracing
This parameter governs whether or not the
tracing output produced by the EJS engine is
produced. This overrides any setting for
EJS_stderr and EJS_stdout on the Server
Execution Analysis -> Trace page. By default
this value is set to on.
Host Name
The name of the host providing the naming
service.
Boot Port
The port number for the EJS naming service.
By default this value is set to 9019.
Protocol
The protocol used by the naming service.
There is no indication as to whether anything
other than CORBA can be placed in this field
or what the effect would be.
4.2.2 Working with Containers
In order to deploy EJBs on a server a container is required. Containers are the
basic service provided by an EJB server. Each EJB exists in a container that
provides certain services and facilities to the EJB that are defined in the EJB
specification. This is known as the container contract. Each EJB container
provider is responsible for implementing container classes that provide the
services specified in the container contract to EJBs deployed in the containers.
Enterprise Java Services
189
Containers also provide the mechanisms by which clients interact with EJBs,
controlling and filtering access to the EJBs contained within.
WebSphere allows the creation of multiple containers on the server, each with a
separate database connection, database user ID, name and separate deployment
directories. Each container may also be configured for use by either session or
entity EJBs through the specification of the Java class file used to implement the
container.
Each EJB JAR file may be deployed in single or multiple containers depending on
what particular connections it requires.
It is a good idea to delete containers that have no EJBs deployed in them as this
can cause errors in the EJS naming service.
4.2.2.1 Creating a Container
Perform the following steps to create a new EJB container:
1. In the left-hand column of the administration interface expand the choices
under Enterprise Java Services by clicking the twistie (the small triangle) and
select Containers (see Figure 168 on page 190).
Figure 168. The EJS Container Page
2. Click Add and fill in the name of the new container in the Add a New Container
window (see Figure 169 on page 191):
190
WebSphere Application Servers: Standard and Advanced Editions
Figure 169. Adding a New EJB Container
3. Enter values in the fields on the container page for your new container (see
Figure 168 on page 190) according to the values in Table 16. If using
Netscape Navigator, do not resize the browser window before completing the
next step (to save your data), as this will cause any changes to be lost.
Table 16. Parameter Values for Container Fields
Parameter
Possible Value
Comments
Container
Name
Anything you choose
Name used to identify the
container to WebSphere.
Container
Class
com.ibm.ejs.container.
EJSEntityContainer or
com.ibm.ejs.container.EJSSession
Container
Name of the class implementing
the container function. Use
EJSEntityContainer for containers
to hold entity EJBs and
EJSSessionContainer for
containers to hold Session EJBs.
JDBC URL
Any JDBC URL. For DB2 this might
be something like
jdbc:db2:ejs_samp
JDBC driver URL for the database
used to store EJB information.
This value is only required for
containers with Entity EJBs with
Container Managed Persistence.
If the EJBs to be deployed need
different databases, create
multiple containers, each with the
URL of the desired database.
EJB JAR
Directory
Relative directory name
Directory relative to <server root>
where EJBs are to be deployed.
This value defaults to
DeployedEJBs.
ContainerUser
ID
Your database logon ID
Database logon ID for the
container to use when it accesses
the database. This value is only
required for containers with Entity
EJBs with Container Managed
Persistence.
Container
Password
Your database password
Database password for the
container to use when it accesses
the database.This value is only
required for containers with Entity
EJBs with Container Managed
Persistence.
Enterprise Java Services
191
4. Click Save to save your changes.
5. Stop and restart the EJS processes to activate the changes.
On Windows NT click Start -> Settings -> Control Panel -> Services and
find the WebSphere Servlet Service. Stop this service by selecting it and
clicking Stop. That will stop the EJS processes. Next stop and restart your
Web server to restart EJS.
On AIX you will need to stop the Web server and then kill all of the WebSphere
processes before restarting the Web server (see Figure 165 on page 187).
4.2.2.2 Removing a Container
In order to remove a container, perform the following steps:
1. In the left-hand column of the administration interface expand the choices
under Enterprise Java Services by clicking the twistie (the small triangle) and
select Containers (See Figure 168 on page 190).
2. Under Container Names select the name of the container you wish to remove
and click Remove.
3. A dialog box asks you to confirm the delete. Click Yes to delete the container.
4. Stop and restart the EJS processes to activate the changes.
On Windows NT click Start -> Settings -> Control Panel -> Services and
find the WebSphere Servlet Service. Stop this service by selecting it and
clicking Stop. This will stop the EJS processes. Next stop and restart your
Web server to restart EJS.
On AIX you will need to stop the Web server and then kill all of the WebSphere
processes before restarting the Web server (see Figure 165 on page 187).
4.2.2.3 Setting Container Parameters
If you need to change the parameters for an existing container, perform the
following steps:
1. In the left-hand column of the administration interface expand the choices
under Enterprise Java Services by clicking the twistie (the small triangle) and
select Containers (See Figure 168 on page 190).
2. Under Container Names select the name of the container you wish to modify.
3. Edit the container fields according to Table 16 on page 191 and click Save. If
you are using Netscape Navigator, do not resize the browser window until after
saving your changes or they will be lost.
4. Stop and restart the EJS processes to activate the changes.
On Windows NT click Start -> Settings -> Control Panel -> Services and find
the WebSphere Servlet Service. Stop this service by selecting it and clicking
Stop. This will stop the EJS processes. Next stop and restart your Web server
to restart EJS.
On AIX you will need to stop the Web server and then kill all of the WebSphere
processes before restarting the Web server (see Figure 165 on page 187).
4.2.3 Deploying an EJB
4.2.3.1 Deploying an EJB in a Container
In order to deploy an EJB in a container perform the following steps:
192
WebSphere Application Servers: Standard and Advanced Editions
1. Copy the EJB JAR file containing the EJB or EJBs into the <Server
Root>\deployable EJBs directory. See 4.2.3.3, “WebSphere Generated
Classes” on page 196 for an explanation of the files required in an EJB JAR
file.
2. In the WebSphere administration interface select Enterprise Java Services
and then EJB JAR Files (see Figure 170 on page 193).
Figure 170. The EJB JAR Files Page
3. Select the JAR file for the EJB or EJBs that you want to deploy from the list
and click Deploy.
4. In the container selection dialog box (see Figure 171) select the name of the
container into which you wish to deploy. Make sure that you select a container
type that is consistent with the EJBs contained within the JAR file. Deploy JAR
files containing session EJBs into a session container, JAR files with entity
EJBs into an entity container, and JAR files with both types of EJBs into both
types of container.
Enterprise Java Services
193
Figure 171. The Container Selection Dialog Box
5. If your JAR file already contains all of the stub and skeleton classes and the
deployment descriptor you will see the Redeployment Selection dialog box (as
shown in Figure 172). Choose either Regenerate to regenerate all of the stub
and skeleton classes or Redeploy Existing to deploy the stub and skeleton
classes already present in your JAR file. For more information on what classes
are generated see 4.2.3.3, “WebSphere Generated Classes” on page 196.
Figure 172. The Redeployment Selection Dialog Box
6. If all is successful you should see the dialog box shown in Figure 173 and the
list of containers into which the bean has been deployed on the EJB JAR files
page which should get updated to show your container (see Figure 174 on
page 195).
Figure 173. The Successful Deployment Dialog Box
194
WebSphere Application Servers: Standard and Advanced Editions
Figure 174. The EJB Deployment Container List
7. Stop and restart the EJS processes to activate the changes.
On Windows NT click Start -> Settings -> Control Panel -> Services and
find the WebSphere Servlet Service. Stop this service by selecting it and click
Stop. That will stop the EJS processes. Next stop and restart your Web server
to restart EJS.
On AIX you will need to stop the Web server and then kill all of the WebSphere
processes before restarting the Web server (see Figure 165 on page 187).
4.2.3.2 Removing an EJB from a Container
To remove or undeploy an EJB from a container, perform the following steps:
1. In the WebSphere administration interface select Enterprise Java Services
and then EJB JAR Files (see Figure 170 on page 193).
2. Select the name of the JAR file you wish to remove and click Undeploy.
3. When the container selection dialog box comes up select the container you
wish to remove the JAR file from and click Undeploy.
Figure 175. The Container Selection Dialog
4. If all goes well, you should see the successful completion dialog box shown in
Figure 176 and the list of containers into which the JAR file is deployed (see
Figure 174 on page 195), which should have been updated to show the
change.
Enterprise Java Services
195
Figure 176. The Successful Undeployment Dialog Box
5. Stop and restart the EJS processes to activate the changes.
On Windows NT click Start -> Settings -> Control Panel -> Services and
find the WebSphere Servlet Service. Stop this service by selecting it and
clicking Stop. This will stop the EJS processes. Next stop and restart your
Web server to restart EJS.
On AIX you will need to stop the Web server and then kill all of the WebSphere
processes before restarting the Web server (see Figure 165 on page 187).
Note: The undeployment process removes the EJB from the container, but it does
not delete the deployed EJBs JAR filename. For example, even after undeploying
test.jar, you will still see the test.jar file in the \deployed EJBs directory.
4.2.3.3 WebSphere Generated Classes
When an EJB is in its deployed state in WebSphere, it needs a number of helper
classes to allow client to server communication and to provide infrastructure for
deployment. Some development tools can create some or all of these classes
automatically and others do not. The EJB specification defines which classes
must be in an EJB JAR file as follows:
•
•
•
•
•
•
The class files for the bean or beans
The class files for the home interfaces
The class files for the remote interfaces
The deployment descriptor for each EJB
A manifest file describing the JAR file contents
Any classes or resources referenced or needed by the EJB classes
Figure 177 shows an example of the contents for a simple EJB JAR file.
Development tools that support EJBs will, at a minimum, support the generation
and packaging of these classes. See your development tools’ documentation for
information on how to perform these tasks.
Figure 177. The HelloWorld EJB JAR File Before Deployment
When an EJB JAR file without all of the extra classes required by WebSphere is
deployed, the deployment tools will generate a number of Java classes to
196
WebSphere Application Servers: Standard and Advanced Editions
complete the deployment. Figure 178 shows the contents of the JAR file shown in
Figure 177 after a successful deployment.
Figure 178. The HelloWorld EJB JAR File after Deployment
Most of these classes are used by the server only, with no direct reference by
clients or modification by the server administrator. The only class that users need
to reference is the <bean name>HomeHelper class. That class is generated for
each EJB and has methods to assist clients in resolving references to names
provided by the CORBA naming service in WebSphere. See 4.3.1, “Finding EJBs”
on page 207 for more information.
The IBM VisualAge for Java EJB support, provided in the 2.0 release by the VAJ
Enterprise Update fix, provides several options for exporting EJB JAR files. If you
export an EJB JAR file, you only export the classes shown in Figure 177 on page
196. If, on the other hand, you export an EJS JAR file, all of the helper classes
required for deployment in WebSphere are generated automatically and placed in
the exported JAR file.
4.2.4 Working with Deployment Descriptors Using the Jet Tool
In order to specify how an EJB is deployed on a server, a special class called a
deployment descriptor is used. This class specifies, for example, security
constraints and transactional attributes. A deployment descriptor is an instance of
the class javax.ejb.deployment.DeploymentDescriptor. A serialized version of this
class must be included in the EJB JAR file prior to the deployment of the EJB to
inform the server how to manage the EJB correctly. See the EJB specification at
ftp://ftp.javasoft.com/docs/ejb/ejb.10.pdf, section 18 for more information on
the deployment descriptor specification.
WebSphere provides a tool called Jet to assist in creating and editing deployment
descriptors. Jet allows you to modify the deployment characteristics of EJBs prior
to deployment and also to take JAR files containing EJBs and turn them into EJB
JAR files through the addition of a deployment descriptor.
Another feature of Jet is that it allows the creation of XML documents containing
the information required to create deployment descriptors for EJBs. Unfortunately
we were not able to use these XML files to recreate the deployment descriptors
due to bugs in the tool. The XML format used is different from the one used in the
latest version of the EJB 1.1 specification available at the time of writing.
Enterprise Java Services
197
The Jet tool is not good at handling JAR files with more than one EJB present,
which unfortunately includes most of the samples. If you need to work with a JAR
file with more than one EJB it is recommended that you unpack the JAR file and
either import the individual files into a development tool that can generate EJB
deployment descriptors, such as VisualAge for Java, or assemble the files into
separate JAR files for processing by Jet. This issue has been noted by the
WebSphere developers and improvement is expected in Version 3.0.
4.2.4.1 Software Requirements
The Jet tool requires that you have the Java Foundation Classes (otherwise
known as Swing) Version 1.0.3 available on your system. These classes are
required for the user interface for the Jet tool. VisualAge for Java, if you have it
installed, includes the swingall.jar file containing these classes in the <VAJava
home>\lib\hpj\directory. Alternatively, they can be downloaded from
http://java.sun.com/products/jfc/index.html.
Note: This is back-level from the latest release of these classes (1.11 at the time
of writing).
4.2.4.2 Configuration
For Windows NT you will need to edit the file <Server Root>\samples\ejs\jet.bat
and change the line:
set SWING_ROOT=.
to reflect the directory containing the swingall.jar file. For example:
set SWING_ROOT=D:\swing-1.0.3
For AIX there is no launch file provided, although it should not be difficult to edit
jet.bat into a shell script if desired.
4.2.4.3 Using the Jet Tool Interactively
To use the Jet tool interactively you need to complete the configuration steps
shown above. Once you have edited the batch file you can open a command
prompt, change the directory to the <Server Root>\samples\ejs directory and
type jet on the command line to run the tool. You should see the window shown
in Figure 179:
198
WebSphere Application Servers: Standard and Advanced Editions
Figure 179. The Jet Initial Start-Up Screen
Note: All of the figures in this section will use the Metal look and feel. If you prefer
you can use the options menu to set the look and feel to be either Windows or
Motif. The functions in each case are the same.
Loading a Bean and Setting Paths Interactively
In order to load a bean, either click the Browse button located near the Input field
on the front panel to locate a JAR file, or type the JAR file name and path into the
Input field and click Load.
The documentation states that it is possible to type a directory name in this field
and have the Jet tool load any EJB in that directory.
If there is more than one bean in the JAR file loaded, a dialog box may appear
asking you with which bean in the JAR file you wish to work. There appears to be
a problem with the Jet tool if there is more than one EJB in the same directory in
the JAR file. It also appears that the tool incorrectly identifies classes that are not
EJBs as being possible beans. It is recommended that EJB JAR files used with
Jet either have only a single bean or have each EJB in a separate package
directory.
Given the limitations of the Jet tool and the difficulties that VisualAge for Java has
importing multiple EJB JAR files, it is recommended that each EJB JAR file
contain only one EJB.
In the Output field, put the name of the JAR file that you want to build. This is the
EJB JAR file that WebSphere will deploy. After the information is entered, the
Build button should become active. This button causes Jet to create the EJB JAR
file specified in the Output field.
Enterprise Java Services
199
Finally, Jet will output an XML version of the deployment descriptor for later batch
processing. If this needs to be performed, enter the name of the XML file into the
XML Output field before clicking Build.
It should be possible to load an EJB from a JAR file using the -f command line
option and a prepared XML file, but we were unable to get this working due to null
pointer exceptions in the Jet tool.
Working with Session Beans
If the bean you have loaded is a session bean then the SessionBean tab
becomes active (see Figure 180). On this page it is possible to enter the
parameters that govern the deployment of a session bean.
Figure 180. The Jet SessionBean Page
The fields on this page correspond to the properties of the
javax.ejb.deployment.SessionDescriptor class, which inherits from the
javax.ejb.deployment.DeploymentDescriptor class (see the EJB specification at
ftp://ftp.javasoft.com/docs/ejb/ejb.10.pdf, section 18 for more information)
according to Table 17. Note that the Run-As Identity value has no effect, because
200
WebSphere Application Servers: Standard and Advanced Editions
security is not supported in WebSphere 2.02 (this is different from WebSphere’s
security).
Table 17. EJB SessionDescriptor Values
Field Name
Session Descriptor Property
Session Timeout Value (seconds)
sessionTimeout
State Management Attribute
stateManagementType
JNDI Home Name
beanHomeName
Transaction Attribute
Corresponds to the transactionAttribute
property of an instance of the
javax.ejb.deployment.ControlDescriptor
class, with no method specified, added to the
controlDescriptors property.
Isolation Level
Corresponds to the isolationLevel property
of an instance of the
javax.ejb.deployment.ControlDescriptor
class, with no method specified, added to the
controlDescriptors property.
Run-As Mode
Corresponds to the runAsMode property of
an instance of the
javax.ejb.deployment.ControlDescriptor
class, with no method specified, added to the
controlDescriptors property.
Run-As Identity
Corresponds to the runAsIdentity property of
an instance of the
javax.ejb.deployment.ControlDescriptor
class, with no method specified, added to the
controlDescriptors property. This value has
no effect in WebSphere 2.02.
Enterprise Bean Class
enterpriseBeanClassName
Remote Interface Class
remoteInterfaceClassName
Home Class
homeInterfaceClassName
Working with Entity Beans
If the bean you have loaded is an entity bean, then the EntityBean tab becomes
active (see Figure 181). On this page it is possible to enter the parameters that
govern the deployment of an entity bean.
Enterprise Java Services
201
Figure 181. The Jet EntityBean Page
The fields on this page correspond to the properties of the
javax.ejb.deployment.EntityDescriptor class, which inherits from the
javax.ejb.deployment.DeploymentDescriptor class (see the EJB specification at
ftp://ftp.javasoft.com/docs/ejb/ejb.10.pdf, Section 18 for more information)
according to Table 18. Note that the Run-As Identity value has no effect, because
EJB security is not supported in WebSphere 2.02 (this is different from
WebSphere’s security).
Table 18. EJB EntityDescriptor Values
Field Name
202
Session Descriptor Property
Select Container Managed Fields
containerManagedFields
Primary Key Class
primaryKeyClassName
JNDI Home Name
beanHomeName
Re-entrant?
reentrant
Transaction Attribute
Corresponds to the transactionAttribute
property of an instance of the
javax.ejb.deployment.ControlDescriptor
class, with no method specified, added to the
controlDescriptors property.
WebSphere Application Servers: Standard and Advanced Editions
Field Name
Session Descriptor Property
Isolation Level
Corresponds to the isolationLevel property
of an instance of the
javax.ejb.deployment.ControlDescriptor
class, with no method specified, added to the
controlDescriptors property.
Run-As Mode
Corresponds to the runAsMode property of
an instance of the
javax.ejb.deployment.ControlDescriptor
class, with no method specified, added to the
controlDescriptors property.
Run-As Identity
Corresponds to the runAsIdentity property of
an instance of the
javax.ejb.deployment.ControlDescriptor
class, with no method specified, added to the
controlDescriptors property. This value has
no effect in WebSphere 2.02.
Enterprise Bean Class
enterpriseBeanClassName
Remote Interface Class
remoteInterfaceClassName
Home Class
homeInterfaceClassName
Setting Method Properties
When you select the Methods tab, the method properties page is displayed (see
Figure 182).
Note: While Jet allows you to enter these values, they are not supported by
WebSphere 2.02. The values for each method will be taken from the default
values set on the EntityBean and SessionBean pages.
Enterprise Java Services
203
Figure 182. The Jet Method Properties Page
This page allows you to specify the deployment properties of the methods
available in the EJB. Each row on the page corresponds to a method in the EJB
and each column corresponds to a property value for an instance of the
javax.ejb.deployment.ControlDescriptor class with the appropriate method
specified on the constructor (see section 18 of the EJB specification at
ftp://ftp.javasoft.com/docs/ejb/ejb.10.pdf for the specification of the
ControlDescriptor class). This instance is added to the DeploymentDescriptor
controlDescriptors property. The column headings correspond to the properties of
the javax.ejb.deployment.ControlDescriptor class according to Table 19:
Table 19. EJB ControlDescriptorValues
Column Label
Control Descriptor Property
Transaction Attribute
transactionAttribute
Isolation Level
isolationLevel
Run-As Mode
runAsMode
Identity
runAsIdentity
Setting Environment Values
Selecting the Environment tab brings up the environment values page (see Figure
183).
204
WebSphere Application Servers: Standard and Advanced Editions
Figure 183. The Jet Environment Values Page
This page allows you to specify environment values that correspond to
java.util.Properties objects that are used as the value for the
environmentProperties property of the
javax.ejb.deployment.DeploymentDescriptor class (see section 18 of the EJB
spec at ftp://ftp.javasoft.com/docs/ejb/ejb.10.pdf for the specification of the
DeploymentDescriptor class). Each property is specified by a key/value pair
separated by an = sign. Comments are prefixed with a :. The Insert From button
brings up a file selection dialog box that allows you to select a text file to load into
the field.
Setting Dependencies
Selecting the Dependencies tab brings up the dependencies page (see Figure
184).
Enterprise Java Services
205
Figure 184. The Jet Dependencies Page
This page allows you to specify files in the JAR file on which the EJB depends.
This information is included in the JAR file manifest file, along with a notation as
to whether the file is included within the JAR file or is external to the JAR file.
Comments are prefixed with a :. The Insert From button brings up a file selection
dialog box that allows you to select a text file to load into the field.
Looking at Messages
When you select the Message Log tab, the messages page is displayed (see
Figure 185).
206
WebSphere Application Servers: Standard and Advanced Editions
Figure 185. The Jet Messages Page
This page displays informational messages about the use of the Jet tool.
4.2.4.4 Using the Jet Tool in Batch Mode
It is possible to use XML files specifying deployment descriptor information to
process EJB JAR files in batch mode. This is accomplished through the use of the
-x command line option for Jet. Unfortunately we were not able to get this
working, even with the WebSphere samples, due to null pointer errors when
starting the tool.
4.3 Coding WebSphere EJB Clients
There are several considerations that must be taken into account when coding for
clients to be able to access EJBs deployed on a WebSphere server as opposed
to coding EJB clients in general.
4.3.1 Finding EJBs
In order for a client to be able to interact with an EJB, it must first be able to locate
its home interface so that it can call either the create or find methods (see 1.7.4.2,
“Steps in Using an EJB” on page 21). This is accomplished by means of a JNDI
interface to a CORBA naming service provided by WebSphere. Covering JNDI or
Enterprise Java Services
207
CORBA in detail is beyond the scope of this book. However, there is a JNDI
tutorial on Sun’s Web site at
http://java.sun.com/products/jndi/tutorial/index.html and an OMG CORBA for
beginners page at http://www.omg.org/corba/beginners.html.
There are two possible methods that can be used by Java clients to access an
EJB home instance for an EJB hosted on a WebSphere server:
1. Explicit instance location
2. Using the EJBHelper class
Note: See 4.3.1.3, “Using Client Transactions” on page 212 for some important
considerations for using the EJS naming service and also using EJB client
transactions.
4.3.1.1 Explicit Instance Location
The steps involved in explicitly locating a reference to an object’s home interface
are described below. You may wish to refer to Figure 186 on page 209 for an
example taken from the Inc Client sample that is delivered with the WebSphere
code:
1. Prepare a hashtable containing the properties necessary to create a JNDI
initial context.
The constructor for the JNDI Initial Context requires a hashtable parameter. In
this hashtable are stored the necessary pieces of information required to
create an initial context. This initial context can then be used to look up the
location of an EJB home instance. For the WebSphere naming service the
following are the possible parameters:
• javax.naming.Context.INITIAL_CONTEXT_FACTORY
This constant is equal to the string "java.naming.factory.initial". This property
identifies the actual name service that the EJB client must use. For
WebSphere this value should be set to
"com.ibm.jndi.CosNaming.CNInitialContextFactory"
This value is required.
• javax.naming.Context.PROVIDER_URL
This constant is equal to the string "java.naming.provider.url". This property
specifies the host name and port of the name server used by the EJB
client. This is how a remote client specifies the address of a WebSphere
server. The property value must have the following format:
"iiop://hostname:port"
where hostname is the IP address or hostname of the machine on which
the name server runs and port is the port number on which the name
server listens. If not specified, this property defaults to the local host and
the port number specified on the EJS Global Properties page, usually
9019. For example, the property value
iiop://bankserver.mybank.com:9999
directs an EJB client to look for a name server on the host named
bankserver.mybank.com listening on port 9999. The property value
iiop://bankserver.mybank.com
208
WebSphere Application Servers: Standard and Advanced Editions
directs an EJB client to look for a name server on the host named
bankserver.mybank.com at port number 9019. The property value
iiop:///
directs an EJB client to look for a name server on the local host listening on
port 9019. This value is optional; its omission is identical to specifying
iiop:///. Omitting this value is most commonly used for EJB clients or
servlets accessing EJBs deployed on the same WebSphere server.
2. Create a JNDI Initial Context.
Call the javax.naming.InitialContext constructor with the properties file created
in step 1 as an argument to obtain an initial context. If the client needs to use
transactions, then it is safer to call the
com.ibm.ejs.client.EJClient.getInitialContext() method instead, with the same
arguments. This alternative method of getting the initial context sets up the
transaction environment correctly for distributed transactions. See 4.3.1.3,
“Using Client Transactions” on page 212 for further details.
3. Perform a JNDI lookup for the EJB’s home instance using the initial context.
Use the lookup (java.lang.String) method on the InitialContext obtained in step
2 to get an object reference to a CORBA object representing the EJB home
instance. The name of the home instance is specified in the EJB deployment
descriptor packaged in the EJB JAR file.
4. Extract the home instance reference from the CORBA object returned
Use the narrow method on the <bean name>HomeHelper class to extract a
reference to the home instance. The <bean name>HomeHelper class is
generated during deployment (See 4.2.3.3, “WebSphere Generated Classes”
on page 196).
5. Call methods on the home interface to create or reference the EJB.
For a session EJB, call one of the create methods on the home interface
instance. For an entity EJB, call either one of the create methods or one of the
findXXXXXX methods. This will give you a reference to an instance of the EJB.
Properties p = new Properties();
p.put(Context.INITIAL_CONTEXT_FACTORY,
"com.ibm.jndi.CosNaming.CNInitialContextFactory");
InitialContext ic = new InitialContext(p);
Object tmpObj = ic.lookup("IncBean");
IncHome incHome = IncHomeHelper.narrow((org.omg.CORBA.Object)tmpObj);
Inc inc = null;
try {
inc = incHome.create(new IncKey(primaryKey));
} catch (DuplicateKeyException ex) {
inc = incHome.findByPrimaryKey(new IncKey(primaryKey));
}
Figure 186. Accessing an EJB Home Instance
Enterprise Java Services
209
4.3.1.2 Using EJB Helper Classes
There are two helper classes that are used by the EJB samples that are useful in
locating EJBs:
1. <Server Root>\samples\ejs\com\transarc\jmon\examples\EJBHelper.java
Despite the location of this class, it is actually a member of the package
com.ibm.ejb.client.util and is a utility class to help clients find the EJB Home
instance of an EJB.
The aim of the EJB helper class is to hide the complexities of dealing with the
differences between the different naming services that could be used by the
server to locate the home instance of an EJB. It uses a standard naming
convention for a properties file for each EJB to contain the information needed
to deal with the naming service. Clients using the EJB helper class can then
remain unchanged if the server needs to change the details of the naming
service at any time. It also simplifies the code required by a client to find the
home instance of an EJB.
Since WebSphere provides its own naming service, this is of minimal value for
clients intending to access only WebSphere servers, other than simplifying the
client code at the expense of creating an extra properties file. If, however, a
client needs to remain portable across multiple heterogeneous EJB servers,
then this class provides real benefit.
To illustrate the difference in the client code, consider two examples taken
from the WAS EJB samples. In Figure 187 on page 210, you can see the
number of steps required to obtain a reference to the EJB home instance for
the Inc Bean sample. In contrast to this, in Figure 188 on page 210 you can
see the number of steps required to obtain a home instance for the business
Bean sample.
Properties p = new Properties();
p.put(Context.INITIAL_CONTEXT_FACTORY,
"com.ibm.jndi.CosNaming.CNInitialContextFactory");
p.put("java.naming.provider.url","iiop://your.server.name:9020");
InitialContext ic = new InitialContext(p);
Object tmpObj = ic.lookup("IncBean");
IncHome incHome = IncHomeHelper.narrow((org.omg.CORBA.Object)tmpObj);
Figure 187. Get a Reference to an EJB Home Instance for the Inc Bean Sample
businessHome = (BusinessHome) EJBHelper.getEJBHome(
"com.ibm.ejs.samples.simple.BusinessHome" );
Figure 188. Get a Reference to an EJB Home Instance for the Business Bean Sample
The code in the EJB helper class also allows for the possibility that you may
wish to define a subclass specific to a particular naming service and call that
rather than the generic implementation provided. This allows the name lookup
to incorporate additional functions, such as transforming a CORBA object
210
WebSphere Application Servers: Standard and Advanced Editions
reference into a proper Java object reference, the procedure used in
WebSphere.
In order to use the EJB helper class in your own applications you must do the
following:
• Include an import statement in your client similar to the following:
import com.ibm.ejb.client.util.EJBHelper;
• Create a properties file for each EJB that will be accessed through the EJB
helper.
The properties file should be named the same as the home interface of the
EJB but with a .properties extension. It should be placed in the EJB JAR
file as a resource in the same directory as the home interface file. Using
VisualAge for Java, this means putting the properties file in a directory
relative to <VA Java Home>\ide\Project Resources\<your project name>\
and then using the dot-separated components of the package name as
subdirectory names in the usual fashion. When the EJB JAR file is
generated from VisualAge, be sure to include this file as a resource file. By
doing this you will include the properties file in the JAR file with the correct
path information.
For example, the properties file for the Business Bean sample is included in
the JAR file under the path
/com/ibm/ejs/samples/simple/BusinessHome.properties. If this file were
included in a VisualAge for Java development environment it might be
placed in the path D:\IBMVjava\ide\Project Resources\Business Bean
Sample\com\ibm\ejs\samples\simple\BusinessHome.properties.
The properties file should contain key/value pairs separated by equal signs.
Table 20 on page 211 lists the possible keys and their values:
Table 20. Keys and Values for EJBHelper .properties Files
Key
Value
Mandatory
<Full package qualified name of the
EJBHome>
Name of the EJB Home interface in
the naming service. Typically this is
just the name of the EJB Home.
Yes
com.ibm.ejb.client.util.EJBHelper
Fully qualified name of the helper
class that subclasses EJBHelper to
provide an implementation for a
particular naming service. If this key
is not present the default RMI
lookup is used.
No
java.naming.factory.initial
Name of the factory class used to
create the
javax.naming.InitialContext for a
particular naming service.
Yes
other parameters
Other parameters used in creating
the javax.naming.InitialContext.
These are typically naming service
specific and may include things like
user ID and password for the
naming service.
No
Figure 189 on page 212 shows the .properties file from the business bean
example. Note the use of the JBrokerHelper class that implements the
Enterprise Java Services
211
naming function for the WebSphere naming service. The source for this
class can be found in <Server
Root>\samples\ejs\com\transarc\jmon\examples\JBrokerHelper.java.
com.ibm.ejs.samples.simple.BusinessHome=BusinessHome
com.ibm.ejb.client.util.EJBHelper=com.ibm.ejb.client.util.CosNaming.JBroke
rHelper
java.naming.factory.initial=com.ibm.jndi.CosNaming.CNInitialContextFactory
Figure 189. BusinessHome.properties
• Call (<YourHomeInterface>) EJBHelper.getEJBHome("<fully qualified
home interface name>") in your code to get a reference to the home
instance on the server. See Figure 188 on page 210 for an example from
the Business Bean client.
2. <server root>\samples\ejs\com\transarc\jmon\examples\Utils.java
The utils class, from the package com.transarc.jmon.examples, includes a
method, lookupUrl(String url), that performs a name lookup using the
WebSphere naming service. This is equivalent to using the EJBHelper and the
JBrokerHelper classes mentioned in the previous item. The advantage of
using this class over the EJB helper class is that it requires less setup as
properties files do not need to be created. The disadvantage is that it does not
give much productivity benefit over coding the API calls manually and it is
more prone to environment changes. Figure 190 on page 212 shows a code
segment from the Stock Portfolio Manager sample that gives an example of
how to use this class.
java.lang.Object o = Utils.lookupUrl(stockHomeName);
stockHome = StockHomeHelper.narrow((org.omg.CORBA.Object) o);
Figure 190. Using the Utils Class
4.3.1.3 Using Client Transactions
The EJB specification provides for the possibility that transactions may be used
by EJB clients to control the execution of EJB applications. It specifies an
interface, javax.jts.UserTransaction, for this purpose. It does not, however, specify
how a client may get an instance of the current transaction context for an EJB for
a server.
For a technical overview of how transactions work, see section 4 of the EJB
Developer’s Guide at http://java.sun.com/products/ejb/developers-guide.pdf.
WebSphere provides a means by which clients can obtain an instance of the
current transaction through the org.omg.CosTransactions.Current interface. This
interface is compatible with the CORBA transaction standard. This interface,
while not directly compatible with the EJB standard, can be used to provide
transactional support to EJB clients accessing EJBs deployed on WebSphere
servers. If better interoperability with other EJB servers is desired, the
WebSphere documentation provides some example code showing how the
javax.jts.UserTransaction interface can be implemented using the
org.omg.CosTransactions.Current interface. The code can be found at
http://<your server name>:9527/doc/whatis/ec007.html#transclient.
212
WebSphere Application Servers: Standard and Advanced Editions
For a client to obtain a reference to the current transaction it must call the static
com.ibm.ejs.client.EJClient.getCurrent() method like this:
org.omg.CosTransactions.Current current =
com.ibm.ejs.client.EJClient.getCurrent();
current.begin();
// do transactional work
current.commit(false);
Note: In order to propagate transactions correctly across method calls, a client
must either make sure that any calls to JNDI to obtain an initial context are made
prior to obtaining the current transaction or that the initial context is obtained by
calling the com.ibm.ejs.client.EJClient.getInitialContext() method rather than the
new javax.naming.InitialContext() method. See 4.3.1.1, “Explicit Instance
Location” on page 208 for more information on obtaining initial contexts.
4.3.2 Monitoring EJS
Enterprise Java Services provides two facilities to allow the monitoring of EJB
execution.
4.3.2.1 The EJS Process Monitor
WebSphere provides an EJS process monitor to give status information on the
three EJS processes. Access the process monitor by using the administration
interface and clicking Server Execution Analysis -> Monitors -> EJS Status
(see Figure 191):
Figure 191. Part of the EJS Status Monitor Page
Automatic update can be enabled by clicking the Start View button. Each of the
three EJS processes is shown, along with the response time for a sample request
to come back from each process.
4.3.2.2 EJS Trace Support
EJS trace support provides a facility to monitor the execution of each of the three
processes making up EJS:
• The Persistent Naming Service
• The Location Service Daemon
• The EJS Server Process
Of the three, the EJS server process trace is the most useful and, not
coincidentally, produces by far the most output.
To enable EJS tracing perform the following steps:
Enterprise Java Services
213
1. Ensure the global EJS Trace Enabled setting is set to yes (see 4.2.1, “Setting
Up the Environment” on page 188 for details on how to do this).
2. In the administration interface click Server Execution Analysis -> Trace (see
Figure 192 on page 214).
3. Select both the Tracer Name and LogFile check boxes for the following
Tracers:
•
•
•
•
•
•
EJS_stdout
EJS_stderr
LSD_stdout
LSD_stderr
PNS_stdout
PNS_stderr
Figure 192. The Trace Settings Page
The changes to tracing should be effective immediately. After enabling these
tracers you should begin to see EJS tracing information appearing in the <Server
Root>/logs/websphere_trace.log file. Each log entry will be prefixed by a time and
also the source of the tracer that produced it.
Figure 193 on page 215 shows an excerpt from the logs with output from all three
EJS processes.
214
WebSphere Application Servers: Standard and Advanced Editions
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.461 00188def EJSContainer
terminate
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.461 00188def EJSContainer
Container forcefully shutting down.
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.481 00188de6 server
ContainerManager$TerminationThread.run
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.491 00188de6 EJSContainer
terminate
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.491 00188de6 EJSContainer
Container forcefully shutting down.
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.491 00188de6 EJSSessionCon
EJSSessionContainer shutting down.
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.501 00188de6 EJSContainer
terminate
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.501 00188de6 server
ContainerManager$TerminationThread.run
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.501 00188def EJSEntityCont
TransarcEntityContainer shutting down.
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.511 00188def EJSContainer
terminate
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.511 00188def server
ContainerManager$TerminationThread.run
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.511 00188e08 server
ContainerManager.terminate
[5/18/99 3:10:31 PM EDT,EJS_stdout,1] 1099.521 00188e08 server
ServerAdmin$TerminationThread.run
[5/18/99 3:21:28 PM EDT,EJS_stderr,1] Connection closed: Host =
wtr05073.itso.ral.ibm.com (port 2312)
[5/18/99 3:21:28 PM EDT,PNS_stderr,1] Connection closed: Host =
wtr05073.itso.ral.ibm.com (port 2304)
[5/18/99 3:21:28 PM EDT,PNS_stderr,1] Connection closed: Host =
wtr05073.itso.ral.ibm.com (port 2309)
[5/18/99 3:21:28 PM EDT,LSD_stderr,1] Connection closed: Host =
wtr05073.itso.ral.ibm.com (port 2307)
>
E
>
>
E
E
<
<
E
<
<
<
<
Figure 193. Excerpt from websphere_trace.log Showing EJS Tracing Information
4.4 Running the EJS Samples
There are a number of EJS samples shipped with WebSphere in order to provide
illustrations of the use of the features of WebSphere EJS. Before running these
samples it is necessary to perform a number of configuration steps to prepare the
environment. After the configuration has been performed, the samples can be run
using the EJS samples Web page, which is accessed via a link from the main
WebSphere Samples Page or directly at:
http://<your server name>/IBMWebAS/samples/ejs/index.html.
Note: The samples have been designed to work with DB2. In order to configure
them to work with other databases, coding changes to the source files would have
to be made.
Enterprise Java Services
215
4.4.1 EJS Sample Configuration Steps
To run the EJB samples complete the following steps:
1. Create an EJS_SAMP database for the EJB samples.
In order to run the EJB samples, another database needs to be created in DB2
called EJS_SAMP. It is enough to create the database without any data. The
samples will add the information later.
Follow the configuration instructions on your platform to create a new
database with the name EJS_SAMP. The following command, when executed
in a DB2 command line environment, is one way to accomplish this:
db2 create database EJS_SAMP
2. Create two new EJB containers.
In order to run the EJB samples you will have to create two new EJB
containers, one for entity beans and one for session beans, and deploy EJBs
into them. Follow the procedures detailed in 4.2.2.1, “Creating a Container” on
page 190 to create two new containers with the values shown in Table 21:
Table 21. Parameter Values for Container Fields
Parameter
Value for Container 1
Value for Container 2
Container Name
Anything you choose
Anything you choose
Container Class
com.ibm.ejs.container.
EJSEntityContainer
com.ibm.ejs.container.
EJSSessionContainer
JDBC URL
jdbc:db2:ejs_samp
n/a
EJB JAR Directory
deployedEJBs
deployedEJBs
Container User ID
Your DB2 logon ID
n/a
Container Password
Your DB2 Password
n/a
3. Deploy Sample EJB JAR files.
Follow the procedure shown in 4.2.3, “Deploying an EJB” on page 192 to
deploy the sample EJB JAR files into the appropriate containers. There is
already deployment information contained within the JAR files, so there is no
need to regenerate it when asked.
Deploy the following JAR files into the entity container that you created in step
2:
•
•
•
•
Animal.jar
Inc.jar
SimpleServer.jar
StockServer.jar
Note that for each EJB in the JAR file, its type, entity or session is listed next
to its name, allowing you to determine whether the JAR file should be
deployed into an entity container or a session container or both.
Repeat the procedure to deploy the following files into the session container
that you created in step 2:
•
•
•
•
216
Animal.jar
HelloServer.jar
SimpleServer.jar
StockServer.jar
WebSphere Application Servers: Standard and Advanced Editions
4.4.2 Running the EJS Samples
The EJS samples can be accessed by selecting the Enterprise JavaBeans link
from the samples page (http://<your server name>/IBMWebAS/samples/) or directly
at http://<your server name>/IBMWebAS/samples/ejs/index.html. This brings up the
Enterprise JavaBean Samples page (see Figure 194 on page 217) which has
links to run the different EJB samples.
Figure 194. Part of the EJB Samples Page
Each of the samples is described on the page and provides a link to execute the
sample. The source code for each of the samples can be found in <server
root>\samples\ejs\com\ibm\ejs\samples\<sample name>. Additional notes on the
samples are provided below.
Hello
This is a very basic sample that uses a stateless session bean. See http://<your
server name>:9527/doc/whatis/ec010.html#HDRHELLO for more details on the
workings of this sample.
Enterprise Java Services
217
Inc
This is a basic entity bean sample that stores a simple counter in the database.
Try executing the sample from different machines and see how the state is
maintained across multiple clients.
See http://<your server name>:9527/doc/whatis/ec010.html#HDRINC for more
details on this sample.
Phone
This sample uses an entity bean with container managed persistence to wrapper
the employee data in the DB2 sample database in order to provide phone lookup
services.
See http://<your server name>:9527/doc/whatis/ec010.html#HDRPHONE for more
details about this sample.
Animal
This is an implementation of the classic beginners artificial intelligence program
Animals. It uses a stateful session bean to run the game and an entity bean to
maintain the knowledge tree. Figure 195 shows the message when the game
correctly guesses your animal.
See http://<your server name>:9527/doc/whatis/ec010.html#HDRANIMAL for more
details about this sample.
Figure 195. Playing the Animal Game
218
WebSphere Application Servers: Standard and Advanced Editions
Stock
This sample uses real stock price data taken from the Internet to store
information on an imaginary stock portfolio. The sample uses an entity bean to
maintain the portfolio information and a session bean to perform the buy and sell
transactions. This sample also uses the EJB transaction support.
Note: In order to run this sample your machine will have to be able to access the
Internet directly. If you are running behind a firewall you will need to "SOCKSify"
your TCP/IP stack using a SOCKS client. We were able to get the stock sample to
work SOCKSified with little trouble from behind our firewall.
Figure 196 on page 220 shows the result of investing large amounts of imaginary
money in some technology stocks. To help you get started in testing this sample
Table 22 shows the stock symbols and corresponding companies for the four
stocks shown in Figure 196:
Table 22. Ticker Symbols for Common Technology Stocks
Ticker Symbol
Company
IBM
International Business Machines Corp.
SUNW
Sun Microsystems
INTC
Intel Corporation
MSFT
Microsoft Corporation
See http://<your server name>:9527/doc/whatis/ec010.html#HDRSTOCK for more
information about this sample.
Enterprise Java Services
219
Figure 196. The Stock EJB Sample
Simple
The three simple samples, Business Bean, Customer Bean and Cart Bean,
implement a business record, a customer record and a shopping cart
respectively. With the business and customer beans, make sure you add and
delete records from the end of the list only (for example, use only sequential
numbers); otherwise, the JSP that displays them will not find them. The logic
reads sequentially until it cannot find the next number in sequence and then
stops. If you look in the <server root>\logs\jvm_stdout.log file you can see the
error messages as the bean attempts to read past the end of the data and fails to
find the next number in sequence.
See http://<your server name>:9527/doc/whatis/ec010.html#HDRSIMPLE for more
details about these samples.
220
WebSphere Application Servers: Standard and Advanced Editions
Chapter 5. Designing Applications for WebSphere
Web applications are becoming more and more important in the day-to-day
running of businesses. Along with this new focus comes significant complexity in
the design of the applications. There are several reasons that they are becoming
more complex. The need for scalability, manageability, performance, persistence
and reliability are driving new requirements to be implemented faster and faster.
WebSphere provides substantial tools to help meet these requirements.
In this chapter we also discuss details about session management. What is
session management and the reason why session management is important.
5.1 Session Management
A session is a connection between a client and a server where information is
exchanged. This section explains the problem in Web applications caused by the
stateless HTTP feature and provides hints and tips on how to handle those
sessions using the HTTP protocol.
5.1.1 Maintaining HTTP Sessions
The HTTP protocol is one of the most important protocols used in Web
applications. The HTTP protocol is stateless, that is, each request arrives
carrying only its request context. For example, if someone orders two books in
two different requests, the order gets accepted as two orders from different users
as shown in Figure 197:
Figure 197. Stateless HTTP Session
5.1.1.1 Using Cookies to Solve Stateless HTTP Sessions
Cookie technology was developed by Netscape Communications. Cookies are
named and have a single value. Cookies enable you to maintain context across
requests using the following steps:
© Copyright IBM Corp. 1999
221
1. A cookie gets generated in the Web server and then it gets sent to the Web
client.
2. The browser receives the data and maintains the information in memory or it
stores the data in a text file on the hard disk. An example of the cookie file
follows:
# Netscape HTTP Cookie File
# http://www.netscape.com/newsref/std/cookie_spec.html
# This is a generated file! Do not edit.
secure.webconnect.netFALSE/cgi-binFALSE12341173080873
990602114622957510011001
nemesis.makuhari.japan.ibm.comFALSE/~wakakoFALSE1924991999Times2
nemesis.makuhari.japan.ibm.comFALSE/~wakakoFALSE1924991999Date
1999/06/02%2011%3A53%3A31
.amazon.comTRUE/FALSE928828709session-id-time928828800
.amazon.comTRUE/FALSE928828709session-id002-1523943-4847406
.amazon.comTRUE/FALSE2082787110x-mainEm520rtC2lzqimMpKai4WG?2F6Tmp1rM
.amazon.comTRUE/FALSE2082787110
:
Figure 198. Cookie Information
3. The Web server gets the data from the client machine.
I
n
f
o
r
m
a
t
i
o
n
generate
Register
generate
Figure 199. All Information Is Sent in Each Request
Cookies provide a convenient technology to logically handle stateful sessions, but
they have some weak points:
222
WebSphere Application Servers: Standard and Advanced Editions
• The information saved in a cookie is easily seen.
It is possible to trace information on most networks or read it from a hard disk
since the information is typically not encrypted. Therefore, secure information,
such as credit card numbers or personal information, shouldn’t be stored in
cookies.
• All information is sent in each request.
If you set your personal information, such as name, address and phone
number, the information is sent as a cookie in each request while you are
doing your online shopping (as shown in Figure 199 on page 222). This is not
secure and it also causes increased HTTP traffic to flow. It usually doesn’t
affect network performance too much (since the amount of data is typically
small), but it is not a sophisticated application design.
For more information about cookies, see
http://www.netscape.com/newsref/std/cookie_spec.html.
5.1.1.2 HttpSession Object
HttpSession is another technological implementation that is used to manage
sessions on the stateless HTTP protocol. It is part of the Java Servlet API and it
is accessible in the Java Servlet development kit.
• The HttpSession object is the Java programing object that has a dictionary-like
interface to store user-defined data.
You can store data in the HttpSession object with any keyword (name) and
look up the data with that keyword.
• Each of the session objects has its own ID.
• HttpSessions are related to the client via the session ID.
The Session Tracker uses the session ID to find the user’s session object.
• It uses the cookie to carry the session ID that is associated with the client.
• You can also use URL rewriting (see 5.1.3.3, “Session Object Using URL
Rewriting” on page 239 for more details).
• The session object is not sent between the Web client and the server.
Only the ID is passed back and forth between the Web client and the Web
server (Figure 200 on page 224). This means the session object is suitable to
store the user’s secure data.
• The data stored in the HttpSession object is shared across requests from the
same machine.
Therefore, the HttpSession object is suitable to store individual data from the
client.
• The HttpSession object is not persistent data. It is deleted after a timeout
period, or by the invalidate() method. In order to store data persistently,
WebSphere provides you with a UserProfile (see 5.2, “User Profiles” on page
253). The HttpSession description can be found at
http://java.sun.com/products/servlet/2.1/api/javax.servlet.http.HttpSession
.html#_top_.
The HttpSession interface is: javax.servlet.http.HttpSession.
Designing Applications for WebSphere
223
More information on session tracking can be found at
http://java.sun.com/docs/books/tutorial/servlets/client-state/session-tracking.html.
generate
I
n
f
o
r
m
a
t
i
o
n
Register
Figure 200. Only Session ID Is Passed Between Web Client and Server
5.1.1.3 How the HttpSession Object Is Created
The HttpSession object is created on the WebSphere server with the first request
from a user. To get an instance of HttpSession, use the following method:
public abstract HttpSession getSession(boolean create)
This method gets the current valid session information associated with this
request. It does that if the value of create is false or, if necessary, it creates a new
session for the request, if the value of create is true.
If the HTTP request is authorized, the authorized name is set to
HttpSessionObject user name; if not, an anonymous name is set, as shown in
Figure 201 on page 226.
5.1.1.4 When Is the HttpSession Object Deleted?
The HttpSession object is deleted under the following two conditions:
1. TimeOut
After a time period defined by the Application Server Manager (the default setting
is 30 minutes) the HttpSession object is deleted.
2. When a specific method is used
224
WebSphere Application Servers: Standard and Advanced Editions
You can delete the HttpSession object using the HttpSession.invalidate()
method.
5.1.2 Session Tracking in the WebSphere Application Server
The WebSphere Application Server provides you with convenient functions for
session tracking. In the WebSphere Application Server environment, you can:
• Monitor active sessions and set up the session environment from the GUI
• Control the life cycle of HttpSession/IBMSessionData objects
• Share session objects among multiple WebSphere Application Servers with
technology called session clustering
• Make your data persistent using UserProfile ()
• Easily develop applications extending existing classes
5.1.2.1 IBMSessionData
The IBMSessionData class is the IBM extension to the implementation of
HttpSession. The IBMSessionData inherits the functions from HttpSession and
provides the following additional information for the user's convenience:
• UserName
If the Http request is authorized, the authorized name is set to HttpSession
object username. If it is not authorized, then the name is set to anonymous. In
IBMSessionData, UserName is also defined using the setUserName() method.
• UserPosition
The user's position within the Web site. For example:
/servlet/IbmSessionSample
• Referrer
The URL the user was visiting before this session was created.
• Message
Any user-defined message.
5.1.2.2 Monitoring HttpSession/IBMSessionData Object
You can monitor HttpSession/IBMSessionData objects from the Application
Server Manager.
You can see this monitor by clicking Server Execution Analysis -> Monitors ->
Active Sessions as shown in Figure 201 on page 226.
Designing Applications for WebSphere
225
Figure 201. Active Sessions Monitor
The middle of this monitor shows each session object that exists on the server. A
summary of each of the session’s objects fields is shown in Table 23:
Table 23. Summary of the Field about Session Object
Field
226
Comment
Session ID
The unique ID that identifies a particular session.
UserName
The user name of the user logged in to the session.
UserPosition
The servlet or Java Server Pages (JSP) the user last visited
during this user session. Usually, this value is the return value
from a request.getRequestURL() method call. However, the
value can be overridden using the setUserPosition() method.
Referrer Page
The URL of the Web page on which the user began the current
session. If the current session began by directly invoking the
servlet URL, this field is null.
TTL
Time to Live displays (in hh:mm:ss format) how long the current
session will remain active.
Cookie
Whether the session ID was set with a cookie for this session
(check mark if true).
URL
Whether the session ID was set via URL rewriting for this session
(check mark if true).
Creation Time
When the session was created.
Last Accessed Time
The last time the session was accessed.
WebSphere Application Servers: Standard and Advanced Editions
Status Information
The bottom of the page displays status information about active sessions.
Table 24. Summary Information about Active Sessions Status Field
Status Field
Comment
Created Sessions
Sessions created since the time the application server was last
started.
Invalidated Sessions
Sessions invalidated since the time the application server was
last started.
Invalidation Time
The amount of time a session is allowed to go unused before it is
no longer validated, as configured in the Invalidate
Time field on the Session Tracking page.
Active Sessions
The current number of active sessions.
Resident Sessions
The number of resident sessions in memory at this time.
Using Cookies
Whether cookies are being used to track Session IDs, as
configured on the Session Tracking page.
Sessions Accessed
The number of sessions accessed since the time the application
server last started.
Max Resident Session
The maximum number of sessions allowed to remain in memory
at one time, as configured in the Maximum Residents
field on the Session Tracking page.
Using URL
Whether URL rewriting is being used, as configured on the
Session Tracking page.
5.1.2.3 Session Tracking Setting
To see how session tracking is set up, click Setup -> Session Tracking from the
Application Server Manager.
There are five tabs: Enable, Cookies, Intervals, Persistence, and Host.
We discuss only the Enable and Cookies tabs in this section. For the Intervals
tab, see 5.1.2.4, “Swapping” on page 230. For information on the Persistence tab,
see 5.1.2.5, “Persistence” on page 231. The Host tab is explained in 5.1.4.1,
“Session Management Modes” on page 248.
Designing Applications for WebSphere
227
Figure 202. Enable Tab from Setup -> Session Tracking
Table 25. Fields on Enable Tab
Field
228
Comment
Enable Sessions
Whether session tracking is enabled, meaning the
session-related methods for the request and response objects
will be functional.
Default: Yes
Enable URL Rewriting
Whether session tracking uses rewritten URLs to carry the
session IDs. If it is enabled, the Session Tracker recognizes
session IDs that arrive in the URL and, if necessary, rewrites the
URL to send the session IDs.
Default: No
Enable Cookies
Whether session tracking uses cookies to carry the session
IDs. If Yes, session tracking recognizes session IDs that arrive
as cookies and tries to use cookies as a means for sending the
session IDs.
Default: Yes
Enable Protocol
Switch Rewriting
Whether the session ID is added to URLs when the URL
requires a switch from HTTP to HTTPS or from HTTPS to
HTTP. Whether the session is passed to different protocols.
Default: No
WebSphere Application Servers: Standard and Advanced Editions
Figure 203. Cookie Tab from Setup > Session Tracking
The fields on the cookie page are described below:
Table 26. Fields on Cookie Tab
Field
Comment
Cookie Name
If cookies are enabled, specifies the name of the cookie.
Default: session ID.
Comment
Comments about the cookie.
Default: servlet Session Support.
Domain
If specified, defines the value of the domain field that is sent for
session cookies. Specifies a value to restrict where session
cookies will be sent. For example, if you specify a particular
domain, session cookies will only be sent to hosts in that domain.
Note: If you specify this field, the session object won’t work
properly from the access using "localhost" or IP address.
Maximum Age
If specified, defines the value of the maximum age of the cookie.
Specifies a value to restrict or extend how long the session
cookie will live on the client browser. The value is an integer that
specifies the cookie age in milliseconds.
Default: The cookie persists only for the current invocation of the
browser. When the browser shuts down, the cookie is deleted.
Path
If specified, defines the value of the path field that will be sent for
session cookies. Specifies a value to restrict which paths on the
server (and therefore, which servlets, JHTML files, and HTML
files) the cookies will be sent. By default, the path is "/" or the root
directory, which means that the cookie will be sent on any access
to the given server.
Designing Applications for WebSphere
229
Field
Secure
Comment
Specifies whether session cookies include the secure field.
Specifies a value to restrict the exchange of cookies to only
HTTPS sessions.
Default: No
5.1.2.4 Swapping
When many users access the Session Manage Application, the number of
session objects is increased. That causes a reduction in the amount of memory
resources available to your server.
WebSphere provides you with an interface to limit the number of session objects
in memory. When the number of session objects generated exceeds the setting,
WebSphere swaps out the least recently used session object to the hard disk.
For this setting, click the Intervals tab from the page Setup -> Session
Tracking.
Figure 204. Intervals
Specify the fields:
Table 27. Fields on Interval Tab
Field
Invalidation
Interval
230
Default
Value
Comment
10000
(millisecond)
The amount of time between the checks that
session tracking makes to determine if a
session is no longer valid because it has not
been used. The value must be an integer.
WebSphere Application Servers: Standard and Advanced Editions
Field
Comment
Default
Value
Swap Interval
10000
(millisecond)
The time between checks to see if we are past the
maximum resident count and should start
swapping the session out to disk.
Maximum
Residents
1024
The number of sessions allowed to remain in
memory at one time. If the number of sessions
exceeds this number,
sessions are swapped to disk on a least recently
used basis to reduce the number of resident
sessions.
Invalidate
Time
1800000
(millisecond)
The amount of time a session is allowed to go
unused before it is not validated. The value must be
an integer.
Click Save.
For serialization technology in Java to be used in swapping, the data stored in the
session object must implement java.io.Serializable or java.io.Externalizable.
5.1.2.5 Persistence
WebSphere provides you with a function called persistence to protect the session
objects when the system is down.
The session values are swapped to disk when the Session Tracker shuts down
and they are restored from disk when it restarts.
For persistence settings, open the session tracking page by clicking Setup ->
Session Tracking from the Application Server Manager.
Figure 205. Session Tracking Persinstence Setting
Designing Applications for WebSphere
231
Table 28. The Field Summary on Persistence Tab
Field
Comment
Persistence
Whether session tracking keeps session data persistent. If
Yes, sessions are swapped to disk when Session Tracker
shuts down and are restored from disk when it restarts. If No,
Session Tracker removes session swap files every time it
starts. Default: Yes
Swap Directory
Name of the directory used to swap out session data. No
other data should be kept in this directory. The default
directory is <ASRoot>\logs\sessSwap.
If you specify a different directory from the Swap Directory field, the
administration service will verify before saving that you have entered a fully
qualified path name.
If it is not an absolute path name (for example, SwapTestDirectory for C:\
SwapTestDirectory), the following message will appear:
Figure 206. Absolute Path Name Is Required
That means that the file does not already exist (it can be an existing directory
name). See Figure 207:
Figure 207. The Message When a File Name Is Specified Instead of the Directory
The directory can be written using the permissions granted to the IBM
WebSphere Application Server, as shown in Figure 208 on page 233:
232
WebSphere Application Servers: Standard and Advanced Editions
Figure 208. If the Permissions Are Not Granted
The default location for the swap directory is <ASRoot>\logs\sessSwap.
The following window shows how session objects are swapped out to a specific
directory. When the Application Server goes down, the session objects are saved
to these files.
Figure 209. Swapped Out Session Objects
5.1.3 Session Object Sample
Here is a very simple example of session objects.
The first request to the SessionSample servlet generates a session object and
stores an integer value in it. After the second request the servlet restores the
integer value from the session object and increments it.
You can invoke the SessionSample servlet from Referrer.html. The
SessionSample servlet, requested from the Web client, generates a session
object and stores an integer value of 1 into an integer object called intvalue. After
the second request from the same machine, the servlet looks up the session
object (referring to its ID) and picks the intvalue out from the object. After
incrementing it, it writes it back to the session object.
5.1.3.1 How to Work SessionSample Servlet
This part shows the steps required to work with this sample.
Designing Applications for WebSphere
233
<html>
<head>
<meta http-equiv="Content-Type" content="text/html">
<title>Referrer</title>
</head>
<body>
<H1>Referrer Page</H1>
<a href="/servlet/SessionSample">SessionSample</a><P>
<a
href="/servlet/IBMSessionSample">IBMSessionSample</a><
BR>
</body>
</html>
Figure 210. Referrer.html
1. Create the SessionSample.java and Referrer.html.
You can copy SessionSample.java from
http://<hostname>//IBMWebAS/doc/howto/SessionSample.java.html
For this HTML file, copy it from your browser window as shown in Figure 211:
Figure 211. Copy and Paste from Your Browser
234
WebSphere Application Servers: Standard and Advanced Editions
import
import
import
import
java.io.*;
java.util.*;
javax.servlet.*;
javax.servlet.http.*;
public class SessionSample extends HttpServlet {
public void doGet (HttpServletRequest request, HttpServletResponse
response)
throws ServletException, IOException
{
// Step 1: Get the Session object
boolean create = true;
HttpSession session = request.getSession(create);
// Step 2: Get the session data value
Integer ival = (Integer)
session.getValue ("sessiontest.counter");
if (ival == null) ival = new Integer(1);
else ival = new Integer (ival.intValue () + 1);
session.putValue ("sessiontest.counter", ival);
// Step 3: Output the page
response.setContentType("text/html");
PrintWriter out = response.getWriter();
out.println("<html>");
out.println("<head><title>Session Tracking Test</title></head>");
out.println("<body>");
out.println("<h1>Session Tracking Test</h1>");
out.println ("You have hit this page " + ival + " times" + "<br>");
out.println ("Your " + request.getHeader("Cookie"));
out.println("</body></html>");
}
Figure 212. SessionSample.java
2. Place the Referrer.html in your HTTP document root. For example, the default
document root of IBM HTTP Server V1.3.3 on Windows NT is \Program
Files\IBM HTTP Server\htdocs.
3. Place SessionSample.java in <ASRoot>/servlets. Compile
SessionSample.java and create the class file.
C:\WEBSPH~1\APPSER~1\servlets>javac SessionSample.java
C:\WEBSPH~1\APPSER~1\servlets>
4. Open http://<hostname>/Referrer.html. The following window will appear:
Designing Applications for WebSphere
235
Figure 213. The Referrer Page
5. Click the SessionSample URL link. You get the following result sent to the
requesting SessionSample servlet:
Figure 214. The Result of Session Sample
6. Click the Reload button on your browser. You get an incremented value each
time you reload the window.
5.1.3.2 How to Use the IBMSessionSample Servlet
We show another example using the IBMSessionData, instead of HttpSession. It
works similarly to SessionSample.java. Additionally, it uses set and
getUserName() and set and getMessage() from the class
com.ibm.servlet.personalization.sessiontracking.IBMSessionData.
236
WebSphere Application Servers: Standard and Advanced Editions
import
import
import
import
import
java.io.*;
java.util.*;
javax.servlet.*;
javax.servlet.http.*;
com.ibm.servlet.personalization.sessiontracking.IBMSessionData;
public class IBMSessionSample extends HttpServlet {
public void doGet (HttpServletRequest request, HttpServletResponse
response)
throws ServletException, IOException
{
// Step 1: Get the Session object casting to IBMSessionData
boolean create = true;
IBMSessionData session =(IBMSessionData)request.getSession(create);
// Step 2: Get the session data value
Integer ival = (Integer) session.getValue ("IBMsessiontest.counter");
String name=session.getUserName(); //Specific to IBMSessionData
String message=(String)session.getMessage();//Specific to
IBMSessionData
if (ival == null){
ival = new Integer (1);
//Specific to IBMSessionData
session.setUserName("YourName");
session.setMessage("You can put any object that implements
Serializable");
}
else{
ival = new Integer (ival.intValue () + 1);
}
session.putValue ("IBMsessiontest.counter", ival);
// Step 3: Output the page
response.setContentType("text/html");
PrintWriter out = response.getWriter();
out.println("<html>");
out.println("<head><title>IBM Session Tracking Test</title></head>");
out.println("<body>");
out.println("<h1>IBM Session Tracking Test</h1>");
out.println ("You have hit this page " + ival + " times" + "<br>");
out.println ("Your " + request.getHeader("Cookie")+"<BR>");
out.println ("User Name: " + name +"<BR>");
out.println ("Message: " +message+"<BR>");
out.println("</body></html>");
}
Figure 215. IBMSessionSample.java
This sample used Referrer.html. Before performing the following steps, steps 1
and 2 from 5.1.3.1, “How to Work SessionSample Servlet” on page 233 are
required:
1. Create IBMSessionSample.java.
2. Place IBMSessionSample.java in <ASRoot>/servlets. Compile
IBMSessionSample.java and create the class file.
Designing Applications for WebSphere
237
C:\WEBSPH~1\APPSER~1\servlets>javac IBMSessionSample.java
C:\WEBSPH~1\APPSER~1\servlets>
3. Open http://<hostname>/Referrer.html. The following window appears:
Figure 216. The Referrer Page
4. Click the IBMSessionSample URL link. The first time you try it you get the
following result. The User Name is anonymous because it has not been set
yet. The same is true for Message.
Figure 217. The Result of IBMSessionSample (1)
5. After the second request (click the Reload button on your browser), you can
see that User Name and Message changed, as shown in the following window:
238
WebSphere Application Servers: Standard and Advanced Editions
Figure 218. The Result of IBMSessionSample (2)
6. Click Server Execution Analysis -> Monitors -> Active Sessions from the
Application Server Manager. You can see UserName set to the YourName
property of the session object.
Figure 219. "YourName" Was Set to User Name Field
5.1.3.3 Session Object Using URL Rewriting
Cookies are not necessarily valid on all browsers. Some browsers can’t use
cookies and some browsers disable cookies. If you can’t use cookies you can use
URL rewriting to carry the session ID. To use URL rewriting, specific coding is
necessary (in addition to configuring the Application Server Manager), as shown
in Figure 220 on page 240. If the engine sends a cookie in the client’s incoming
request, the URL will not be encoded with the session ID.
Designing Applications for WebSphere
239
Configuration for URL Rewriting
To enable URL rewriting:
1. Click Setup -> Session Tracking from the Application Server.
2. Open the Enable tab on the Session Tracking page.
3. Check the Yes option to enable URL rewriting, and click Save.
Figure 220. Enable URL Rewriting
URL Rewriting Sample
This sample uses three files:
1. URLRewrite.html calls the URLRewriteServlet1 servlet passing the string in
the memo field.
2. URLRewriteServlt1.java processes the request, creates the session object
and outputs HTML with a link to the URL RewriteServlet2 servlet with
res.encodeRedirectUrl(rewriteURL). This method is indispensable to
managing sessions using URL rewriting.
3. URLRewriteServlt2.java gets the memo and session ID from the session
object. This servlet doesn’t require URL rewriting specific coding.
240
WebSphere Application Servers: Standard and Advanced Editions
<html><head>
<title>Test of URL Rewrite Servlet </title></head>
<body>
<form method=GET action=/servlet/URLRewriteServlet1>
<H1>
Please input your message!
</h1>
<input type="text" name="memo">
<input type="submit" value="Submit">
</form>
</body>
</html>
<!-- hhmts start -->
Last modified: Fri Jun 04 14:12:59 1999
<!-- hhmts end -->
Figure 221. URLRewrite.html
Designing Applications for WebSphere
241
import
import
import
import
import
import
import
java.io.*;
java.util.*;
javax.servlet.*;
javax.servlet.http.HttpSession;
javax.servlet.http.HttpServlet;
javax.servlet.http.HttpServletRequest;
javax.servlet.http.HttpServletResponse;
public class URLRewriteServlet1 extends HttpServlet {
public void doGet(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException {
HttpSession session = req.getSession(true);
PrintWriter out = res.getWriter();
res.setContentType("text/html");
out.println("<html><head><title>This is a URLRewrite Servlet.
</title></head>");
out.println("<body>");
out.println("<hr>SessionID : " + session.getId());
String memo = (String) session.getValue("memo");
if (memo == null){
out.println("<H2>There is no memo.</H2>");
}
else{
out.println("<hr> The last memo is<B> " + memo +"</B><BR>");
}
memo =req.getParameterValues("memo")[0];
session.putValue("URLRewrite.memo",memo);
session.putValue("OriginURL",req.getRequestURI());
out.println("<h1> Now, the new memo is " + memo);
out.println("</h1>");
out.println("<a href=\"");
String rewriteURL = "/servlet/URLRewriteServlet2";
out.println(res.encodeRedirectUrl(rewriteURL));
out.println("\"> Go to URLRewrite Servlet2 </a>");
out.println("<p>");
out.println("<hr>");
out.println("<a href=\"/URLRewriteServlet.html\"> Go back to URLrewrite
HTML</a>");
out.println("</body></html>");
out.flush();
}
}
Figure 222. URLRewriteServlet1.java
242
WebSphere Application Servers: Standard and Advanced Editions
import
import
import
import
import
import
import
java.io.*;
java.util.*;
javax.servlet.*;
javax.servlet.http.HttpSession;
javax.servlet.http.HttpServlet;
javax.servlet.http.HttpServletRequest;
javax.servlet.http.HttpServletResponse;
public class URLRewriteServlet2 extends HttpServlet {
public void doGet(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException {
res.setContentType("text/html");
PrintWriter out = res.getWriter();
HttpSession session = req.getSession(false);
String originURL = (String) session.getValue("OriginURL");
String memo = (String) session.getValue("URLRewrite.memo");
out.println("<html><head><title>URLRewriteServlet2 </title></head>");
out.println("<body>");
out.println("<h1> URLRewriteServlet2 </h1>");
out.println("<P>");
if (memo == null){
out.println("<hr>There is no memo.");
}
else{
out.println("<hr> The last memo is <B>" + memo+"</B>");
}
out.println("<p>");
out.println("<hr> Session ID : " + session.getId());
out.println("<P>");
out.println("<hr>");
out.println("<a href=\"/URLRewrite.html\"> Go back to URLrewrite
HTML</a>");
out.println("</body></html>");
}
}
Figure 223. URLRewriteServlet2.java
To use this sample:
1. Create URLRewrite.html, URLRewriteServlet1.java and
URLRewriteServlet2.java.
2. Place URLRewrite.html in the servlets directory.
3. Compile URLRewriteServlet1.java and URLRewriteServlet2.java. Place the
class files to <ASRoot>/servlets.
C:\WebSphere\AppServer\Servlets>javac URLRewriteServlet1.java
C:\WebSphere\AppServer\Servlets>javac URLRewriteServlet2.java
C:\WebSphere\AppServer\Servlets>
4. Open http://<hostname>/URLRewrite.html.
Designing Applications for WebSphere
243
Figure 224. Referred URLRewrite.html
5. Input the message and click the Submit button. The following window will
appear. You can see the ID of the created session in this window (Figure 225
on page 245). Click the Go to URLRewriteServlet2 link.
244
WebSphere Application Servers: Standard and Advanced Editions
Figure 225. The Result of URLRewriteServlet1
6. You can see the message was stored from session object (Figure 226 on page
246). This way the session is managed with the requests. The session ID is
added to the URL because the URLRewriteServlet1 uses URL rewriting.
Designing Applications for WebSphere
245
http://localhost/servlet/URLRewriteServlet2;$sessionid$GAX014IAAAAAACIYNA
Figure 226. The Result of URLRewriteServlet2
7. Click Server Execution Analysis -> Monitors -> Active Sessions from the
Application Server Manager. You can make sure that URL rewriting was used
if you see the green check box under the URL field in the following window:
246
WebSphere Application Servers: Standard and Advanced Editions
Figure 227. URL Was Used
8. If your browser can accept cookies (Figure 228 on page 247), you can see this
application using cookies instead of URL rewriting (Figure 229 on page 248):
Figure 228. Cookie Option Is Enabled in Netscape
Designing Applications for WebSphere
247
Figure 229. Cookie Is Used
5.1.4 Session Clustering
Session clustering is the technology that is used to share session objects among
multiple application servers. This is accomplished by one application server,
called a cluster server, maintaining information about the session objects, and
another application server, called a cluster client, asking for information from the
cluster server. The class that handles these processes is
com.ibm.servlet.personalization.sessiontracking.IBMSessionContextImpl. It is
also called the Session Tracker.
Specific coding for clustering is not necessary.
Class files get added to the session object for the WebSphere Application Server
class path. In the session clustering environment, the class file for session
objects should be referred to in every machine in the cluster. To build a clustering
environment, eNetwork Dispatcher in WebSphere Performance Pack is required.
WebSphere Performance Pack enhances and manages the performance of
WebSphere Web sites. See 1.1.3, “WebSphere Performance Pack” on page 5 for
more details.
5.1.4.1 Session Management Modes
There are three models in which session support operates:
1. Stand-Alone
This is the default setting. The server maintains its own session information. It
does not request session information about the other servers.
2. Session Cluster Client
One of the WebSphere Application Servers that uses session clustering.
248
WebSphere Application Servers: Standard and Advanced Editions
3. Session Cluster Server
The WebSphere Application Server host that maintains the information for all
session objects.
To see the settings for each server click Setup -> Session Tracking from the
Application Server Manager. Click the Host tab. The following setting will be
on the Host Page of the Session Tracking.
Stand-Alone
This is the default setting. The Stand Alone Host option is checked Yes and the
other fields are left blank (see Figure 230).
Click the Save button and restart the application server for the changes to take
place.
Figure 230. Setting for Stand Alone
Session Cluster Server
For the session cluster server setting:
1. Check the No option on the Stand Alone Host option (Figure 231). Click the
Save button and restart the application server.
Designing Applications for WebSphere
249
Figure 231. Check the Option Stand Alone - No
2. Leave the Session Cluster Server field blank. That sets up this instance of the
IBM WebSphere Application Server as the session cluster server.
Session Cluster Client
To set up the Session cluster client:
1. Check the No option on the Stand Alone Host option (Figure 231 on page
250). Click the Save button and restart the application server.
If you try to make further changes before restarting the application server, the
following dialog box will come up, and the setting will be lost after restarting:
Figure 232. Dialog Box for Validation
2. Restart the WebSphere Application Server.
3. Open the Host tab on the Session Tracking page (click Setup -> Session
Tracking from the Application Server Manager and click the Host tab).
4. In the Session Cluster Server field, type the host name or IP address of
another instance of the IBM WebSphere Application Server that is set up as a
cluster server (Figure 233).
250
WebSphere Application Servers: Standard and Advanced Editions
Figure 233. The Cluster Client Setting
5. Restart the WebSphere Application Server.
5.1.4.2 Session Clustering Scenario
Figure 234 on page 252 shows the flow for session clustering. This example
shows the flow when the requested session object exists in a different server from
the one that processed the request from the client.
1. The session object is generated when HttpServletRequest.getSession(ture) is
called. The generated session object is stored on the server where it was
generated, whether it was a clustered server or not.
2. WAS (WebSphere Application Server) registers the generated session object
at the cluster server, sending information about the session object.
3. The cluster client that requested the session object from the Web client
doesn’t know where it is. Therefore, the cluster client asks for the location from
the cluster server.
4. The cluster server notifies the cluster client of the WAS host that is
maintaining the requested session object.
5. The WAS host that processed the request from the Web client requests the
session object from the WAS host that maintains the requested session
object.
6. The WAS host maintaining the requested session object locks the session
object.
7. The WAS host maintaining the requested session object sends the session
object to WAS.
Designing Applications for WebSphere
251
8. When the service() method that processes the Web client request is
terminated, notification of the termination is sent to the WAS host maintaining
the session object with refreshed object information.
9. The WAS host unlocks the requested session object and applies changes to
the session object.
Figure 234. Session Clustering Flow
If the requested session object is stored at the host that processes the request
from the Web client, it doesn’t ask the location of the session object from the
cluster server.
Note: The parameters for the cluster server are used for the clustered
environment. To be consistent with the clustered environment, the valid
parameters in the cluster’s client are limited to the Enable Sessions parameter in
the Enable tab (Setup -> Session Tracking from the Application Server Manager
as shown in Figure 202 on page 228) and the Persistence tab (Figure 205 on
page 231).
The object placed in the session data must implement the serializable interface
(Figure 235 on page 253) to propagate the object along with a given session
since the session is serialized across the cluster.
252
WebSphere Application Servers: Standard and Advanced Editions
public class ShoppingCart implements java.io.Serializable{
:
:
}
Figure 235. Objects Placed in Session Data Must Implement the Serializable Interface
5.2 User Profiles
The Application Server has an API called UserProfile that makes it easy to
maintain persistent information about your Web site visitors. The UserProfile
enables you to store the user’s data in a database without coding any SQL. The
UserProfile contains the interface to store the user’s personal data, such as
name, postal and e-mail addresses, telephone numbers and shopping cart
information. For further information, see the UseProfile API Reference:
http://<hostmame>/IBMWebAS/doc/apidocs/Package-com.ibm.servlet.personalization
.userprofile.html
5.2.1 Setting Up User Profiles
Before setting up the user profile, you must set up a JDBC connection to the
database. Refer to 2.3.5.1, “Setting Up DB2 in the WebSphere Environment” on
page 74.
1. Click Setup -> User Profile from the Application Server Manager.
2. Click the Enable tab and select Yes for the Using User Profiles? option.
3. Leave the Class Name field with its default value. If you want to use a created
subclass for UserProfile, specify the absolute class name.
Figure 236. User Profile Page
4. Click the Database tab.
Designing Applications for WebSphere
253
Figure 237. Database Tab on User Profile Page
5. Fill in the fields. You must specify an existing database name in the Database
Name field. You shouldn’t create a userprofile table in the database. It will be
created automatically for you when the first request to the user profile occurs.
Table 29. Field Summary on Database Tab on User Profile Page
Field Name
Default Value
Comment
Database Used
db2
The database product name (for example,
DB2 or Oracle). This information is used in
creating the JDBC connection to the
database.
JDBC Driver Used
COM.ibm.db2.jdbc.app.DB2Driver
The name of the JDBC driver for the
database. Note: Include the.zip or .jar file for
the driver (such as db2java.zip for
DB2) in the Java classpath of the
Application Server (see the Paths tab on the
Java Engine page to set the classpath).
Database Name
N/A
The database used to store the user profile
tables and data. You must create this
database before you use user profile first, or
specify an existing database. But you need
not create any tables in the database.
Database Owner
N/A
The ID of the owner of the database.
254
WebSphere Application Servers: Standard and Advanced Editions
Field Name
Default Value
Comment
Table Name
userprofile
The table to store user profile data. The user
profile class will create this table using each
of these applicable configuration variables
when it is first enabled. You need only
specify a name for the table.
User ID
N/A
The user ID used to access the database
and its tables.
Password
N/A
The password associated with the defined
user ID.
6. Click the ConnMgr tab.
Figure 238. ConnMgr Tab on User Profile Page
7. Click the Save button.
5.2.2 How to Use UserProfile in Your Servlet
The following steps show the easiest process to follow to use the user profile in a
servlet:
1. Import userprofile packages.
import com.ibm.servlet.personalization.userprofile.*;
2. Create the UserProfile object.
UserProfile up = new UserProfile();
3. Use the UserProfile.retrieveUserProfileByUserName() method to get the
UserProfile object referenced by the specified userName.
(up = UserProfile.retrieveUserProfileByUserName(userName)
Designing Applications for WebSphere
255
Many methods are provided to get the UserProfile object, for example,
UserProfile.retrieveUserProfileByXXXX. See the UserProfile API reference for
more details:
http://<hostname>//IBMWebAS/doc/apidocs/com.ibm.servlet.personalization.use
rprofile.UserProfile.htm
4. Use the UserProfile.addUserProfile() method to create a new user profile for a
user:
up = UserProfile.addUserProfile(userName);
5. Use the UserProfile.updateUserProfile() method to update a user profile for a
user:
Hashtable userInfo = new Hashtable();
userInfo.put("userName",userName);
userInfo.put("email",req.getParameterValues("email")[0]);
userInfo.put("dayPhone",req.getParameterValues("dayPhone")[0]);
userInfo.put("fax",req.getParameterValues("fax")[0]);
userInfo.put("address1",req.getParameterValues("address1")[0]);
up.updateUserProfile(userInfo);
6. Use UserProfile.getXXXXX() method to get the data of the user profile:
pw.println("<tr><td>userName:</td><td>"+up.getUserName()+"</td></tr>");
pw.println("<tr><td>email :</td><td>"+up.getEmail()+"</td></tr>");
pw.println("<tr><td>dayPhone :</td><td>"+up.getDayPhone()+"</td></tr>");
pw.println("<tr><td>fax :</td><td>"+up.getFax()+"</td></tr>");
pw.println("<tr><td>address1 :</td><td>" +up.getAddress1()+"</td></tr>");
Update UserProfile
UserProfile
UserProfile
UserProfile
User Name
Email
User Name
retrieveUserProfileByXXXX
User Name
Email
DayEmail
Phone
Day Phone
Fax
Address1
FaxDay Phone
Fax
Address1
getUserName( )
Address1
getEmail( )
getDayPhone( )
getFax( )
getAddress1( )
Figure 239. retrieveUserProfileByXXXX
5.2.3 UserProfile Sample
We show a simple example on how to use UserProfile. A user can retrieve or add
data for a specified user in HTML. A servlet processes the request from the
HTML and accesses the UserProfile.
To work with the User Profile sample:
256
WebSphere Application Servers: Standard and Advanced Editions
1. Create UserProfileSample1.html and UserProfileSample1.java:
<html> <head>
<title>User Profile Sample1</title>
</head>
<BODY TEXT="#000000" BGCOLOR="#eeffee">
<h1>User Profile Sample1</h1>
<p><br>
<form action = "http://localhost/servlet/UserProfileSample1" method =
"POST">
<table COLS=2 >
<tr><td>User Name:</td>
<td><input type = "text" name = "userName"></td></tr>
<tr><td>email:</td>
<td><input type = "text" name = "email"></td></tr>
<tr><td>dayPhone:</td>
<td><input type = "text" name = "dayPhone"></td></tr>
<tr><td>fax:</td>
<td><input type = "text" name = "fax"></td></tr>
<tr><td>address1:</td>
<td><input type = "text" name = "address1"></td></tr>
<tr><td><INPUT TYPE="submit" NAME="button" VALUE="retrieve" ></td>
<td><INPUT TYPE="submit" NAME="button" VALUE=" add
" ></td></tr>
</table>
</form>
<hr>
<!-- hhmts start -->
Last modified: Mon May 24 13:03:50 1999
<!-- hhmts end -->
</body> </html>
Figure 240. UserProfileSample1.html
Designing Applications for WebSphere
257
import
import
import
import
import
import
com.ibm.servlet.personalization.sessiontracking.*;
com.ibm.servlet.personalization.userprofile.*;
java.io.*;
java.util.*;
javax.servlet.*;
javax.servlet.http.*;
public class UserProfileSample1 extends HttpServlet {
public void doPost(javax.servlet.http.HttpServletRequest
req,javax.servlet.http.HttpServletResponse res) throws ServletException,
IOException {
String button = null;
String userName = null;
String message = null;
UserProfile up = new UserProfile();
Hashtable userInfo = new Hashtable();
button = req.getParameterValues("button")[0];
userName = req.getParameterValues("userName")[0];
if (button.equals("retrieve")){
if((up = UserProfile.retrieveUserProfileByUserName(userName)) ==
null){
message = "No Data Exists for <B> "+userName+" </B>";
}else{
message = "Search Finished";
}
}else{
if((up = UserProfile.retrieveUserProfileByUserName(userName)) ==
null){
up = UserProfile.addUserProfile(userName);
message = "New User was Resistered";
}else{
message = "Updated User Info";
}
Figure 241. UserProfileSample1.java (1/2)
258
WebSphere Application Servers: Standard and Advanced Editions
userInfo.put("userName",userName);
userInfo.put("email",req.getParameterValues("email")[0]);
userInfo.put("dayPhone",req.getParameterValues("dayPhone")[0]);
userInfo.put("fax",req.getParameterValues("fax")[0]);
userInfo.put("address1",req.getParameterValues("address1")[0]);
up.updateUserProfile(userInfo);
}
res.setContentType("text/html");
res.setHeader("Pragma","No-cache");
res.setHeader("Cache-Control","no-cache");
res.setDateHeader("Expires",0);
PrintWriter pw = res.getWriter();
pw.println("<HTML><HEAD>");
pw.println("<TITLE>The Result of UserProfileSample1</TITLE></HEAD>");
pw.println("<BODY TEXT=\"#000000\" BGCOLOR=\"#eeffee\">");
pw.println("<H1>The Result of UserProfileSample1</H1>");
pw.println("<HR WIDTH=\"100%\">");
pw.println("<BR>" + message);
pw.println("<FORM ACTION = \"http://localhost/userProfileSample1.html\"
METHOD = \"GET\">");
if(up != null){
pw.println("<table COLS=2 ><B>");
pw.println("<tr><td>userName:</td><td>"+up.getUserName()+"</td></tr>");
pw.println("<tr><td>email :</td><td>"+up.getEmail()+"</td></tr>");
pw.println("<tr><td>dayPhone
:</td><td>"+up.getDayPhone()+"</td></tr>");
pw.println("<tr><td>fax :</td><td>"+up.getFax()+"</td></tr>");
pw.println("<tr><td>address1 :</td><td>"
+up.getAddress1()+"</td></tr>");
pw.println("</B></table>");
}
pw.println("<P><INPUT TYPE = \"submit\" VALUE = \"Back\"></FORM>");
pw.println("</BODY></HTML>");
pw.flush();
pw.close();
}
}
Figure 242. UserProfileSample1.java (2/2)
2. Place UserProfileSample1.html in your HTTP document root. For example, the
default document root for IBM HTTP Server V1.3.3 on Windows NT is
\Program Files\ IBM HTTP Server\htdocs.
3. Place UserProfileSample1.java in <ASRoot>/servlets. Compile
UserProfileSample1.java and create the UserProfileSample1.class file.
Designing Applications for WebSphere
259
C:\WEBSPH~1\APPSER~1\servlets>javac UserProfileSample1.java
C:\WEBSPH~1\APPSER~1\servlets>
4. Open the URL http://<hostname>/UserProfileSample1.html. The following
window will appear:
Figure 243. The Referred UserProfilesample1.html
5. Enter your data in each of the fields and click the add button as shown in
Figure 244:
260
WebSphere Application Servers: Standard and Advanced Editions
Figure 244. Input Data for Each Field
6. The request will be sent to the UserProfileSample1 servlet, and the result will
be returned. It may take a little bit of time on your first request to UserProfile,
because the servlet needs to connect to the database and create a new table.
Figure 245. The Result from UserProfile Sample1
7. Click the Back button on the page, which brings you back to the
UserProfileSample1.html.
Designing Applications for WebSphere
261
8. On the first page, input the name you registered to the userName field and
click the retrieve button as shown in Figure 244 on page 261.
Figure 246. Input the Name You Registered
9. You can get the data that you input earlier as shown in Figure 247:
Figure 247. The Retrieved Data
10.If you specify a name that is not registered in the database, the following
window will appear:
262
WebSphere Application Servers: Standard and Advanced Editions
Figure 248. The Result When You Specify Wrong Name
After you work on this sample you will find the table (the default name is
userprofile) in the database that you specified at 5.2.1, “Setting Up User Profiles”
on page 253. You will also find that the Connection Manager was used.
1. To make sure the table was created by the UserProfile, if you use DB2 for
Windows NT, start the DB2 Control Center by clicking Start -> Program Files
-> DB2 for Windows NT -> Administration Tools -> Control Center from the
Start Menu of Windows NT.
2. The following window will come up (Figure 249). On the left frame of this
window, expand the machines node until you find the tables icon in the
database name that you specified.
3. Select the Tables icon. You will find the user profile table in the right frame.
Designing Applications for WebSphere
263
Figure 249. DB2 Control Center
4. Double-click the USERPROFILE table icon. This will bring up the following
window:
Figure 250. Created User Profile Table
264
WebSphere Application Servers: Standard and Advanced Editions
To make sure that the Connection Manager was used:
Click Server Execution Analysis -> Monitors -> DB Pool Connections from
the Application Server Manager. The following window will come up.
Figure 251. UserProfile Uses Connection Manager
5.2.4 Linking User Profiles to Sessions
As mentioned in 5.1.1.2, “HttpSession Object” on page 223, session objects can’t
store data persistently. By linking the session objects to the user profile, the data
from the session objects can be stored persistently.
The method addUserProfile(HttpSession) enables you to associate UserProfiles
and SessionObject very easily. UserProfileSample2.html and
UserProfileSample2.java are the samples you can use to link the user profiles
and the sessions objects.
Designing Applications for WebSphere
265
Create UserProfileSample2.html and UserProfileSample2.java as shown in
Figures 252, 253, and 254.
<html> <head>
<title>User Profile Sample2</title>
</head>
<BODY TEXT="#000000" BGCOLOR="#ddeeff">
<h1>User Profile Sample2</h1>
<p><br>
<form action = "http://localhost/servlet/UserProfileSample2" method =
"POST">
<table COLS=2 >
<tr><td>User Name:</td>
<td><input type = "text" name = "userName"></td></tr>
<tr><td>email:</td>
<td><input type = "text" name = "email"></td></tr>
<tr><td>dayPhone:</td>
<td><input type = "text" name = "dayPhone"></td></tr>
<tr><td>fax:</td>
<td><input type = "text" name = "fax"></td></tr>
<tr><td>address1:</td>
<td><input type = "text" name = "address1"></td></tr>
<tr><td><INPUT TYPE="submit" NAME="button" VALUE="retrieve" ></td>
<td><INPUT TYPE="submit" NAME="button" VALUE=" add
" ></td></tr>
</table>
</form>
<hr>
<!-- hhmts start -->
Last modified: Wed May 26 09:45:31 1999
<!-- hhmts end -->
</body> </html>
Figure 252. UserProfileSample2.html
266
WebSphere Application Servers: Standard and Advanced Editions
import
import
import
import
import
import
com.ibm.servlet.personalization.sessiontracking.*;
com.ibm.servlet.personalization.userprofile.*;
java.io.*;
java.util.*;
javax.servlet.*;
javax.servlet.http.*;
public class UserProfileSample2 extends HttpServlet {
public void doPost(javax.servlet.http.HttpServletRequest
req,javax.servlet.http.HttpServletResponse res) throws ServletException,
IOException {
String button = null;
String userName = null;
String message = null;
UserProfile up = new UserProfile();
Hashtable userInfo = new Hashtable();
button = req.getParameterValues("button")[0];
userName = req.getParameterValues("userName")[0];
//--------IBMsession----------------------------------------// Step 1: Get the Session object casting to IBMSessionData
IBMSessionData isession =(IBMSessionData)req.getSession(true);
// Step 2: Get the session data value
Integer ival = (Integer) isession.getValue
("UserProfileSample2.counter");
if (ival == null){
ival = new Integer (1);
isession.setUserName(userName);
}
else{
ival = new Integer (ival.intValue () + 1);
}
isession.putValue ("UserProfileSample2.counter", ival);
//--------IBMsession-----------------------------------------
if (button.equals("retrieve")){
if((up = UserProfile.retrieveUserProfileByUserName(userName)) ==
null){
message = "No Data Exists for <B> "+userName+" </B>";
}else{
message = "Search Finished";
}
Figure 253. UserProfileSample2.java (1/2)
Designing Applications for WebSphere
267
}else{
if((up = UserProfile.retrieveUserProfileByUserName(userName)) ==
null){
//up = UserProfile.addUserProfile(userName);
up = UserProfile.addUserProfile(isession);
message = "New User was Resistered";
}else{
message = "Updated User Info";
}
userInfo.put("userName",userName);
userInfo.put("email",req.getParameterValues("email")[0]);
userInfo.put("dayPhone",req.getParameterValues("dayPhone")[0]);
userInfo.put("fax",req.getParameterValues("fax")[0]);
userInfo.put("address1",req.getParameterValues("address1")[0]);
up.updateUserProfile(userInfo);
}
res.setContentType("text/html");
res.setHeader("Pragma","No-cache");
res.setHeader("Cache-Control","no-cache");
res.setDateHeader("Expires",0);
PrintWriter pw = res.getWriter();
pw.println("<HTML><HEAD>");
pw.println("<TITLE>The Result of UserProfileSample2</TITLE></HEAD>");
pw.println("<BODY TEXT=\"#000000\" BGCOLOR=\"#ddeeff\">");
pw.println("<H1>The Result of UserProfileSample2</H1>");
pw.println("<HR WIDTH=\"100%\">");
pw.println("<BR>" + message +"<BR>");
pw.println ("<B>You have hit this page " + ival + " times" +
"</B><br>");
pw.println("<FORM ACTION = \"http://localhost/userProfileSample2.html\"
METHOD = \"GET\">");
if(up != null){
pw.println("<table COLS=2 ><B>");
pw.println("<tr><td>userName:</td><td>"+up.getUserName()+"</td></tr>");
pw.println("<tr><td>email :</td><td>"+up.getEmail()+"</td></tr>");
pw.println("<tr><td>dayPhone
:</td><td>"+up.getDayPhone()+"</td></tr>");
pw.println("<tr><td>fax :</td><td>"+up.getFax()+"</td></tr>");
pw.println("<tr><td>address1 :</td><td>"
+up.getAddress1()+"</td></tr>");
pw.println("</B></table>");
}
pw.println("<P><INPUT TYPE = \"submit\" VALUE = \"Back\"></FORM>");
pw.println("</BODY></HTML>");
pw.flush();
pw.close();
}
}
Figure 254. UserProfileSample2.java (2/2)
268
WebSphere Application Servers: Standard and Advanced Editions
1. Copy UserProfileSample2.html into your HTTP document root. For example,
the default document root for IBM HTTP Server V1.3.3 on Windows NT is
\Program Files\ IBM HTTP Server\htdocs.
2. Copy UserProfileSample2.java into <ASRoot>/servlets. Compile
UserProfileSample2.java and create the UserProfileSample2.class file.
C:\WEBSPH~1\APPSER~1\servlets>javac UserProfileSample2.java
C:\WEBSPH~1\APPSER~1\servlets>
3. Open the URL http://<hostname>/UserProfileSample2.html. The following
window will appear:
Figure 255. The Referred UserProfileSample2.html
4. On this page, input the name you resistered in 5.2.3, “UserProfile Sample” on
page 256 to the User Name field and click the retrieve button as shown in
Figure 256 on page 270.
Designing Applications for WebSphere
269
Figure 256. Input the Name You Registered Earlier
5. You can get the data that you input earlier and the value of the counter in the
session object as shown in Figure 257:
Figure 257. The Retrieved Data
270
WebSphere Application Servers: Standard and Advanced Editions
Figure 258. The Session Object Associated with UserProfile
5.2.5 Extending the UserProfile Class
Even though the UserProfile has enough fields to store user data, it is possible
that you might need extra fields to meet your application requirements. You can
extend your user profile by extending
com.ibm.servlet.personalization.userprofile.UserProfile. In this part, we show
how to configure your Application Server Manager for a new user profile and how
to extend the user profile from the servlet.
5.2.5.1 Extending the UserProfile Class
There is a sample extension of the WebSphere UserProfile class,
UserProfile2.java, in the directory <ASRoot>\samples\userprofile. It shows how to
add fields to the default user profile class. The source code for
com.ibm.servlet.personalization.userprofile.UserProfile, UserProfile.java is also
in the same directory. In UserProfile2.java, there are detailed comments to help
extend the UserProfile. Therefore, you can just copy UserProfile2.java and modify
the part that refers to user profile.java. Basically UserProfile3.java, which we
created for this sample, is almost the same as UserProfile2.java. Only the
addUserProfile method is modified and the updateUserProfile method is created
for the sample application used in 5.2.5.3, “Using Customized UserProfile” on
page 280.
To extend the UserProfile class:
1. Declare data members specifying new columns and the attribute of the column
in the database.
Designing Applications for WebSphere
271
import
import
import
import
java.net.*;
java.sql.*;
java.util.*;
java.io.*;
import
import
import
import
import
import
import
javax.servlet.*;
javax.servlet.http.*;
com.sun.server.*;
com.ibm.servlet.personalization.userprofile.UserProfile;
com.ibm.servlet.personalization.sessiontracking.*;
com.ibm.servlet.connmgr.*;
com.ibm.servlet.debug.DebugSupport;
Figure 259. UserProfile3.java (1/9)
2. Create an SQL statement to add the new column.
public class UserProfile3 extends
com.ibm.servlet.personalization.userprofile.UserProfile
{
static String newColumnName = "cellPhone"; /* the new column */
static String newColumnType = "varchar (20)";
private String cellPhone;/* the data member that will store this column *
static{
Connection con = null;
IBMJdbcConn cmConn = null;
//cmConn = (IBMJdbcConn)cm.getIBMConnection (spec);
try{
cmConn = (IBMJdbcConn)connMgr.getIBMConnection (spec,"UserProfile3");
con = cmConn.getJdbcConnection();
Statement s = con.createStatement();
s.executeUpdate("alter table " + tableName + " add " + newColumnName +
newColumnType + " ;");
s.close();
}catch (SQLException e){
e.getMessage();
}catch (IBMConnMgrException e){
System.out.println (e.getMessage());
}finally{
if (con != null){
try{
cmConn.releaseIBMConnection();
}catch(IBMConnMgrException e2){
System.out.println (e2.getMessage());
}
} //if
}//finally
}//static
Figure 260. UserProfile3.java (2/9)
272
WebSphere Application Servers: Standard and Advanced Editions
3. This is a constructor (getter and setter methods) for the new data item (Figure
261).
public UserProfile3(){
super();
}
public String getCellPhone(){
return cellPhone;
}
public synchronized void setCellPhone(String value){
{ cellPhone = value;}
updateUPField(newColumnName, value);
}
Figure 261. UserProfile3.java (3/9)
4. The retrieveUserProfile3 method is in Figure 264 on page 276. You must
provide a new retrieveUserProfilemethod. Modify the parameter for the
executeQuery method to meet the new data requirement.
Designing Applications for WebSphere
273
static protected UserProfile3 retrieveUserProfile3(String type, String
key){
UserProfile3 result = null;
result = (UserProfile3)UserProfile.retrieveUserProfile (type, key);/*
first, call the parent's method */
if (result != null){
ResultSet rs = null;
Connection con = null;
IBMJdbcConn cmConn = null;
if ( key != null ){
try{
cmConn = (IBMJdbcConn)connMgr.getIBMConnection (spec);
con = cmConn.getJdbcConnection();
Statement s = con.createStatement();
rs = s.executeQuery("select " + newColumnName + " from " + tableName + "
where " + type + "= '" + key + "'");
/* Modify the above statement to select all the new data items:
select newColumnName1, newColumnName2, ... newColumnNamen ..
*/
while ( rs.next() ){
result.cellPhone = rs.getString(newColumnName);
}
rs.close(); //added
s.close();
}catch (SQLException e){
DebugSupport.logException("invalid UserProfile search criteria:" + type +
" , "+ key, e);
try{
if (con != null) con.rollback();
}catch (SQLException e2){
}
return null;
Figure 262. UserProfile3.java (4/9)
274
WebSphere Application Servers: Standard and Advanced Editions
}catch (IBMConnMgrException e2){
System.out.println (e2.getMessage());
}finally{
try{
if (rs != null)
rs.close();
}catch (SQLException e){
System.out.println("problem closing result set");
try{
if (con != null) con.rollback();
if (con != null) cmConn.releaseIBMConnection();
}catch (Exception e2){
System.out.println (e2.getMessage());
}
return result;
}
}
}
if (con != null){
try{
cmConn.releaseIBMConnection();
}catch (IBMConnMgrException e){
System.out.println (e.getMessage());
}
}
return result;
}
else return null;
}
Figure 263. UserProfile3.java (5/9)
5. Override retrieveUserProfileByUserName (Figure 264 on page 276).
6. Create retrieveUserProfilesByXXX where "XXX" is a new data item you
created (see Figure 264 on page 276).
7. Override getUserProfile to force it to use the subclass's
retrieveUserProfileByUserName method (Figure 264 on page 276).
Designing Applications for WebSphere
275
static public UserProfile retrieveUserProfileByUserName(String userName){
return((retrieveUserProfile3("userName",userName)));
}
static public Enumeration retrieveUserProfilesByCellPhone(String cellPhone,
Statement s){
return(retrieveUserProfiles("cellPhone",cellPhone, s));
}
static public UserProfile getUserProfile(HttpServletRequest req){
IBMSessionData ss = (IBMSessionData)(req.getSession(false));
String userName = req.getRemoteUser();
if (userName == null)
userName = UserProfile.ANONYMOUS_USERNAME;
if ((ss != null) && (ss.isAppUserName()))
userName = ss.getUserName();
return(retrieveUserProfileByUserName(userName));
}
Figure 264. UserProfile3.java (6/9)
8. Override updateUserProfile(Hashtable clipboard) to update and store the new
data item(s) from the clipboard (Figure 265 on page 277). This method is not
in UserProfile2.java. We created the method to use this in the sample
application shown in 5.2.5.3, “Using Customized UserProfile” on page 280.
276
WebSphere Application Servers: Standard and Advanced Editions
public synchronized void updateUserProfile(Hashtable clipboard)
{
String v_userName = nullify(clipboard.get ("userName"));
String tmp = null;
UserProfile3 userProfile=new UserProfile3();
super.updateUserProfile(clipboard);
if (((tmp = nullify (clipboard.get ("cellPhone"))) != null) &&
(UserProfile.getConfigEnabled()) && (v_userName != null)){
/* Check to see if any of the new items are in the clipboard */
/* If so, store the item in a local variable */
String uname = (String)(clipboard.get("userName"));
Connection con = null;
IBMJdbcConn cmConn = null;
try{
cmConn = (IBMJdbcConn)connMgr.getIBMConnection
(spec,"UserProfile3-addUserProfile ");
con = cmConn.getJdbcConnection();
Statement s = con.createStatement();
String s1 = new String(" where username = '" + uname + "'");
String s2 = new String("update " + tableName + " set cellPhone = '" + tmp
+ "'");
/* Modify this statement to 'SET' the values of any new items which were in
the clipboard */
System.out.println("UserProfile3: update " +s2 + s1);
int numRows = s.executeUpdate(s2 + s1);
s.close();
userProfile.cellPhone = tmp;
}catch (SQLException e){
DebugSupport.logException("addUserProfile SQLException", e);
try{
if (con != null) con.rollback();
if (con != null)
cmConn.releaseIBMConnection();
}catch (Exception e2){
}
return;
}catch (IBMConnMgrException e2){
System.out.println (e2.getMessage());
}finally{
if (con != null){
try{
cmConn.releaseIBMConnection();
}catch (IBMConnMgrException e){
System.out.println (e.getMessage());
}
}
}
}//end if
return;
}
Figure 265. UserProfile3.java (7/9)
Designing Applications for WebSphere
277
9. Override addUserProfile(Hashtable clipboard) to retrieve and store the new
data item(s) from the clipboard. This method for UserProfile3 is a little different
from UserProfile2.java, since UserProfile3.updateUserProfile(Hashtable
clipboard) is used in this method (see Figure 266 on page 278).
static public UserProfile addUserProfile(Hashtable clipboard){
String v_userName = nullify(clipboard.get ("userName"));
UserProfile3 userProfile = (UserProfile3)addUserProfile(v_userName);
if (userProfile == null)
return null;
userProfile.updateUserProfile(clipboard);
return userProfile;
}
Figure 266. UserProfile3.java (8/9)
10.Override toHTML and toString:
public String toHTML () {
return(super.toHTML() + "<b> cellPhone</b> : " + cellPhone + "<BR>");
/* Add code to output any other data items to the string above */
}
public String toString(){
return(super.toString() + " cellPhone= " + getCellPhone());
/* Add code to output any other data items to the string above */
}
}
Figure 267. UserProfile3.java (9/9)
Compile UserProfile3.java and create UserProfile3.class.
C:\WebSphere\AppServer\classes>javac UserProfile3.java
C:\WebSphere\AppServer\classes>
Configuring the Application Server Manager for UserProfile3 is discussed in the
next section.
5.2.5.2 Configuring a Customized UserProfile Class
In this section, UserProfile3 is used as an example of an extended UserProfile.
To use UserProfile3 instead of
com.ibm.servlet.personalization.userprofile.UserProfile, follow these steps:
1. Copy UserProfile3.class into the <ASRoot>/classes directory. This directory
must be added to the Application Server classpath field in the Java Engine
Page of the Application Server Manager (Figure 268 on page 279).
278
WebSphere Application Servers: Standard and Advanced Editions
Figure 268. Whatever Directory Is Chosen in the Application Server Classpath Field
2. Open the UserProfile page on the Application Server Manager. Specify your
UserProfile class name in the Class Name field on the Enable tab (Figure
269):
Designing Applications for WebSphere
279
Figure 269. Specify the UserProfile Class Name
3. Click the Save button.
4. If the UserProfile is used by any servlet, restart the Application Server. If not,
the older UserProfile gets used.
5.2.5.3 Using Customized UserProfile
To use a customized UserProfile, the servlet needs some modifications for the
new class.
Figure 270 on page 281, Figure 271 on page 282 and Figure 272 on page 283
(UserProfileSample3.java) are the examples to use for UserProfile3. The bold
parts are modified in UserProfile3. Import UserProfile3 instead of
com.ibm.servlet.personalization.userprofile.*. Use the UserProfile3 method to
retrieve and add UserProfile3. Some methods need to point to UserProfile3.
280
WebSphere Application Servers: Standard and Advanced Editions
import com.ibm.servlet.personalization.sessiontracking.*;
//import com.ibm.servlet.personalization.userprofile.*;
import UserProfile3;
import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class UserProfileSample3 extends HttpServlet {
public void doPost(javax.servlet.http.HttpServletRequest
req,javax.servlet.http.HttpServletResponse res) throws ServletException,
IOException {
String button = null;
String userName = null;
String message = null;
//
UserProfile up = new UserProfile();
UserProfile3 up = new UserProfile3();
Hashtable userInfo = new Hashtable();
button = req.getParameterValues("button")[0];
userName = req.getParameterValues("userName")[0];
//--------IBMsession----------------------------------------// Step 1: Get the Session object casting to IBMSessionData
IBMSessionData isession =(IBMSessionData)req.getSession(true);
// Step 2: Get the session data value
Integer ival = (Integer) isession.getValue
("UserProfileSample3.counter");
if (ival == null){
ival = new Integer (1);
isession.setUserName(userName);
}
else{
ival = new Integer (ival.intValue () + 1);
}
isession.putValue ("UserProfileSample3.counter", ival);
//--------IBMsession----------------------------------------if (button.equals("retrieve")){
if((up
=(UserProfile3)UserProfile3.retrieveUserProfileByUserName(userName))
== null){
message = "No Data Exists for <B> "+userName+" </B>";
}else{
message = "Search Finished";
}
Figure 270. UserProfileSample3.java (1/3)
Designing Applications for WebSphere
281
}else{
userInfo.put("userName",userName);
userInfo.put("email",req.getParameterValues("email")[0]);
userInfo.put("dayPhone",req.getParameterValues("dayPhone")[0]);
userInfo.put("fax",req.getParameterValues("fax")[0]);
userInfo.put("address1",req.getParameterValues("address1")[0]);
userInfo.put("cellPhone",req.getParameterValues("cellPhone")[0]);
if((up =
(UserProfile3)UserProfile3.retrieveUserProfileByUserName(userName)) ==
null){
up = (UserProfile3)UserProfile3.addUserProfile(userName);
message = "New User was Resistered";
}else{
message = "Updated User Info";
}
up.updateUserProfile(userInfo);
}
res.setContentType("text/html");
res.setHeader("Pragma","No-cache");
res.setHeader("Cache-Control","no-cache");
res.setDateHeader("Expires",0);
PrintWriter pw = res.getWriter();
pw.println("<HTML><HEAD>");
pw.println("<TITLE>The Result of UserProfileSample3</TITLE></HEAD>");
pw.println("<BODY TEXT=\"#000000\" BGCOLOR=\"#ffeedd\">");
pw.println("<H1>The Result of UserProfileSample3</H1>");
pw.println("<HR WIDTH=\"100%\">");
pw.println("<BR>" + message +"<BR>");
pw.println ("<B>You have hit this page " + ival + " times" +
"</B><br>");
pw.println("<FORM ACTION = \"http://localhost/userProfileSample3.html\"
METHOD = \"GET\">");
Figure 271. UserProfileSample3.java (2/3)
282
WebSphere Application Servers: Standard and Advanced Editions
up
=(UserProfile3)UserProfile3.retrieveUserProfileByUserName(userName);
if(up != null){
pw.println("<table COLS=2 ><B>");
pw.println("<tr><td>userName:</td><td>"+up.getUserName()+"</td></tr>");
pw.println("<tr><td>email :</td><td>"+up.getEmail()+"</td></tr>");
pw.println("<tr><td>dayPhone
:</td><td>"+up.getDayPhone()+"</td></tr>");
pw.println("<tr><td>cellPhone
:</td><td>"+up.getCellPhone()+"</td></tr>");
pw.println("<tr><td>fax :</td><td>"+up.getFax()+"</td></tr>");
pw.println("<tr><td>address1 :</td><td>"
+up.getAddress1()+"</td></tr>");
pw.println("</B></table>");
}
pw.println("<P><INPUT TYPE = \"submit\" VALUE = \"Back\"></FORM>");
pw.println("</BODY></HTML>");
pw.flush();
pw.close();
}
}
Figure 272. UserProfileSample3.java (3/3)
Designing Applications for WebSphere
283
<html> <head>
<title>User Profile Sample3</title>
</head>
<BODY TEXT="#000000" BGCOLOR="#ffeedd">
<h1>User Profile Sample3</h1><p><br>
<form action = "http://localhost/servlet/UserProfileSample3" method =
"POST">
<table COLS=2 >
<tr><td>User Name:</td>
<td><input type = "text" name = "userName"></td></tr>
<tr><td>email:</td>
<td><input type = "text" name = "email"></td></tr>
<tr><td>dayPhone:</td>
<td><input type = "text" name = "dayPhone"></td></tr>
<tr><td>cellPhone:</td>
<td><input type = "text" name = "cellPhone"></td></tr>
<tr><td>fax:</td>
<td><input type = "text" name = "fax"></td></tr>
<tr><td>address1:</td>
<td><input type = "text" name = "address1"></td></tr>
<tr><td><INPUT TYPE="submit" NAME="button" VALUE="retrieve" ></td>
<td><INPUT TYPE="submit" NAME="button" VALUE=" add
" ></td></tr>
</table>
</form>
<hr>
<!-- hhmts start -->
Last modified: Mon May 31 17:48:40 1999
<!-- hhmts end -->
</body> </html>
Figure 273. UserProfileSample3.html
To use this sample:
1. Copy UserProfileSample3.html into your HTTP document root. For example,
the default document root for IBM HTTP Server V1.3.3 on Windows NT is
\Program Files\ IBM HTTP Server\htdocs.
2. Copy UserProfileSample3.java into <ASRoot>/servlets. Compile
UserProfileSample3.java and create the UserProfileSample3.class file.
C:\WEBSPH~1\APPSER~1\servlets>javac UserProfileSample3.java
C:\WEBSPH~1\APPSER~1\servlets>
3. Open the URL http://<hostname>/UserProfileSample3.html. The following
window will appear. Specify each of the fields and click the add button (Figure
274):
284
WebSphere Application Servers: Standard and Advanced Editions
Figure 274. Specify Each of the Fields and Click on the add Button
4. In the following window, you can see the updated value of the cellPhone field:
Figure 275. The cellPhone Field Was Updated as well as Other Fields
Designing Applications for WebSphere
285
5.3 Using the Personalization Utilities
The package com.ibm.servlet.servlets.personalization.util contains servlets that
enable Web administrators to post site-wide bulletins and also permits Web
visitors to exchange messages. These servlets’ class files are copied to the
servlet directory and are registered to the Servlet Configuration page when you
install WebSphere Application Server. Therefore, you can use these utilities with
some minor additional configuration.
5.3.1 Creating Bulletins
SetVariableText and GetVariableText in the package
com.ibm.servlet.servlets.personalization.util are useful servlets to add bulletins
or news flashes to your Web site on a page-by-page basis.
You can:
• Store the message for the Site Queue with SetVariableText servlet.
• Embed the message from the Site Queue to your Web page with
GetVariableText instance.
5.3.1.1 How to Store a Message in the Site Queue
To make a site queue and store a message, you can use the SetVariableText
servlet. This servlet has to be used with the <SERVLET> tag in a JSP file as
shown in Figure 276. That provides access to the advertiser to store messages.
<html>
<head>
<meta http-equiv="Content-Type" content="text/html">
<title>Create Bulletin</title>
</head>
<body>
<H1>Create Bulletin</H1>
<SERVLET NAME="SetVariableText">
</SERVLET>
<HR>
</body>
</html>
Figure 276. CreateBulletin.jsp
1. Create the CreateBulletin.jsp file and place it in your HTTP document root. For
example, the default document root of IBM HTTP Server V1.3.3 on Windows
NT is \Program Files\IBM HTTP Server\htdocs.
2. Open the URL http://<hostname>/CreateBulletin.jsp. The following window
will appear:
286
WebSphere Application Servers: Standard and Advanced Editions
Figure 277. Set the Site Queue Name via SetVariableText
3. Specify the site queue name and type your message in the Site Message field.
4. Click Submit Request button and the following window appears:
Figure 278. The Message Added Successfully
5.3.1.2 Showing Bulletin
To propagate the message created in the previous steps:
1. Add the <SERVLET> tags with GetVariableText and queueName properties to
the Web page on which you want to show the message, for example,
Bulletin.jsp (Figure 279):
Designing Applications for WebSphere
287
<html>
<head>
<meta http-equiv="Content-Type" content="text/html">
<title>Bulletin Test</title>
</head>
<body>
<H1>Bulletin Test1 (TestQueue)</H1>
<H2>
<SERVLET NAME="GetVariableText" queueName="TestQueue">
</SERVLET>
</H2>
</body>
</html>
Figure 279. Bulletin.jsp
2. After placing Bulletin.jsp in your HTTP document root, open the URL
http://<hostname>//Bulletin.jsp. You can see the message stored in
TestQueue (Figure 280 on page 288).
Figure 280. Stored Message from TestQueue
5.3.1.3 Creating Multiple Site Queues in a Server
When you want to create multiple site queues in a server (which is a common
requirement), you need additional configurations for the instance of
GetVariableText servlet. Since the queueName parameter is passed to the servlet
as an initial parameter, once the instance of the GetVariableText servlet is loaded,
the parameter can’t be changed until the servlet is unloaded. For example, if you
store different messages in the TestQueue and the plants’ queues (Figure 282),
GetVariableText can’t handle both these queues at once (Figure 283 and Figure
284 on page 290). You need to make a new instance of GetVariableText for each
of the new site queues.
288
WebSphere Application Servers: Standard and Advanced Editions
SetVariable
Text
Queue Name Queue Name Queue Name
Browser
QueueName1 QueueName2 QueueName3
Message
Message
Message
GetVariable
Text 1
GetVariable
Text 2
GetVariable
Text 3
Message 1
Message 2
Message 3
Browser
the instances of
GetVariableText
<ServletNameGetVariableText1
</Servlet
5460\546007
Figure 281. GetVariableText
Figure 282. If You Store the Different Messages to the Plants Queue
Designing Applications for WebSphere
289
<html><head>
<meta http-equiv="Content-Type" content="text/html">
<title>Two Site Queues 1(TestQueue, plants)</title>
</head><body>
<H1>Two Site Queues 1(TestQueue, plants)</H1><HR>
This is the message of the TestQueue.
<H2>
<SERVLET NAME="GetVariableText" queueName="TestQueue">
</SERVLET>
</H2><HR>
Is this the message of the plants.....<B>?</B>
<H2>
<SERVLET NAME="GetVariableText" queueName=plants>
</SERVLET>
</H2><HR>
</body></html>
Figure 283. TwoSiteQueues1.jsp
Figure 284. The Referred TwoSiteQueues1.jsp
To create another servlet instance:
1. Go to the Servlet Configuration page by clicking Servlets -> Configuration
from the Application Server Manager. You can see the GetVariableText servlet
is already registered to this page as shown in Figure 285 on page 291.
290
WebSphere Application Servers: Standard and Advanced Editions
Figure 285. Servlet Configuration Page
Click the Add button on this page and add “PlantGetVarText”. Place
com.ibm.servlet.servlets.personalization.util.GetVariableText in the Servlet Class
field. Click the Add and Save buttons (Figure 286).
Figure 286. Add a PlantGetVarText Servlet
Place the TwoSiteQueues2.jsp (Figure 287) in your HTTP document root.
Designing Applications for WebSphere
291
<html><head>
<meta http-equiv="Content-Type" content="text/html">
<title>Two Site Queues 2(TestQueue, plants)</title>
</head><body>
<H1>Two Site Queues 2(TestQueue, plants)</H1><HR>
This is the message of the TestQueue.
<H2>
<SERVLET NAME="GetVariableText" queueName="TestQueue">
</SERVLET>
</H2><HR>
This is the message of the plants.
<H2>
<SERVLET NAME="PlantGetVarText" queueName=plants>
</SERVLET>
</H2><HR>
</body></html>
Figure 287. TwoSiteQueues2.jsp
2. Open the URL http://<hostname>/TwoSiteQueues2.jsp. You can see the
messages for each of the queues at this time (Figure 288):
Figure 288. The Referred TwoSiteQueues2.jsp
You can specify the queueName property on the Servlet Configuration page and
in the <SERVLET> tags.
1. Click the Add button in the Servlet Properties field and specify the
queueName property name and value (Figure 289 on page 293). Click Save.
292
WebSphere Application Servers: Standard and Advanced Editions
Figure 289. Specifying queueName Property on Servlet Configuration Page
2. Store the message in the plants2 site queue (Figure 290):
Designing Applications for WebSphere
293
Figure 290. Storing the Message to plants2 Queue
3. Open the URL http://<hostname>/TwoSiteQueues2.jsp and the following window
will appear. The queueName specified in the <SERVLET> tag is ignored:
Figure 291. The queueName Parameter of the <SERVLET> Tag Is Ignored
The servlet uses the parameter values from where it is loaded. Therefore, we
recommend that you specify the same parameters for both the <SERVLET> tag
and the Servlet Configuration page.
294
WebSphere Application Servers: Standard and Advanced Editions
5.3.2 Web Site Messaging
SendMessage, CheckMessage and GetMessage servlets in the package
com.ibm.servlet.servlets.personalization.util enable Web site users to exchange
messages on your Web server.
• The SendMessage servlet checks the users on the Web site using the session
object and creates a Java script to send the message back to the
SendMessage servlet (Figure 292 on page 295). The SendMessage servlet
stores the message in the Message property of the session object (the
instance of IBMSessionData).
<SCRIPT LANGUAGE="JavaScript" >
function sendMessage() {
SM=window.open('','SendMessage','scrollbars=no,width=400,height=200');
SM.document.write("<FORM METHOD='POST' ACTION='/servlet/SendMessage'");
SM.document.write("<P>Recipient: <SELECT NAME='userID'>");
SM.document.write("<OPTION SELECTED> Choose a person ");
SM.document.write("<OPTION>wakako")
SM.document.write("<OPTION>fox")
SM.document.write("</SELECT>" );
SM.document.write("<P>Message to send: <INPUT TYPE='option'
NAME='messageText'>");
SM.document.write("<p><INPUT TYPE='submit' VALUE='Submit Message'
onClick='document.forms[0].submit()' >");
SM.document.write("</FORM>");
}
Figure 292. Java Script Created by SendMessage Servlet
• The CheckMessage servlet checks whether the message is stored in the
user’s session object. If there is a message, the CheckMessage servlet
renders the MessageWaiting image and it adds a hot link to the GetMessage
servlet:
<a href="/servlet/GetMessage"><img
src="/IBMWebAS/samples/XtremeTravel/phonring.gif" BORDER=0 >
Figure 293. If There Is a Message
If there isn’t any message it renders the NoMessageWaiting image:
Designing Applications for WebSphere
295
<img src="/IBMWebAS/samples/XtremeTravel/phonflat.gif" BORDER=0 >
Figure 294. If There Is No Message
• The GetMessage servlet is called from the MessageWaiting image link. It
checks and presents the Message property of the user’s session object.
5.3.2.1 Sample Model of Message Exchanging
We show a sample scenario exchanging messages below:
1. Only the users registered to user profile can open the interface to exchange
messages.
2. Two users are logged on to this Web server to use this application.
• The MessageLogin.html (Figure 295 on page 297) passes the user name from
the form to the MessageLogin servlet.
• The MessageLogin servlet (Figure 296 on page 298 and Figure 297 on page
299) creates the session object by storing the user name and it retrieves the
user profile by that name. If the user has the user profile, this servlet presents
the ExchangeMessage.jsp. If not, the session object is invalidated and the
user can’t log in.
• The MessageLogin.jsp (Figure 298 on page 300) calls SendMessage and the
CheckMessage servlet with the <SERVLET> tag. The user can send or check
the message on this screen.
296
WebSphere Application Servers: Standard and Advanced Editions
<html> <head>
<title>Message Login</title>
</head>
<BODY>
<h1>Message Login</h1><p><br>
<form action = "/servlet/MessageLogin" method = "Get">
Input <B>User Name</B> and Click login button.<P>
<input type = "text" name = "userName"><P>
<tr><td><INPUT TYPE="submit" VALUE="login" >
</form>
<hr>
<!-- hhmts start -->
Last modified: Tue Jun 01 10:44:27 1999
<!-- hhmts end -->
</body> </html>
Figure 295. MessageLogin.html
Designing Applications for WebSphere
297
import com.ibm.servlet.personalization.sessiontracking.*;
//import com.ibm.servlet.personalization.userprofile.*;
import UserProfile3;
import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class MessageLogin extends HttpServlet {
public void service(javax.servlet.http.HttpServletRequest
req,javax.servlet.http.HttpServletResponse res) throws ServletException,
IOException {
String button = null;
String userName = null;
String message = null;
//
UserProfile up = new UserProfile();
UserProfile3 up = new UserProfile3();
Hashtable userInfo = new Hashtable();
// button = req.getParameterValues("button")[0];
userName = req.getParameterValues("userName")[0];
//--------IBMsession----------------------------------------// Step 1: Get the Session object casting to IBMSessionData
IBMSessionData isession =(IBMSessionData)req.getSession(true);
// Step 2: Get the session data value
Integer ival = (Integer) isession.getValue ("MessageLogin.counter");
if (ival == null){
ival = new Integer (1);
isession.setUserName(userName);
}
else{
ival = new Integer (ival.intValue () + 1);
}
isession.putValue ("MessageLogin.counter", ival);
//--------IBMsession----------------------------------------Figure 296. MessageLogin.java (1/2)
298
WebSphere Application Servers: Standard and Advanced Editions
if((up
=(UserProfile3)UserProfile3.retrieveUserProfileByUserName(userName)) ==
null){
message = "No Data Exists for <B> "+userName+" </B><BR> Login denied<BR>";
isession.invalidate();
}else{
message = "Search Finished";
((com.sun.server.http.HttpServiceResponse)
res).callPage("/ExchangeMessage.jsp", req);
return;
}
//
up.updateUserProfile(userInfo);
res.setContentType("text/html");
res.setHeader("Pragma","No-cache");
res.setHeader("Cache-Control","no-cache");
res.setDateHeader("Expires",0);
PrintWriter pw = res.getWriter();
pw.println("<HTML><HEAD>");
pw.println("<TITLE>Login Denied</TITLE></HEAD>");
pw.println("<BODY>");
pw.println("<H1>Login Denied</H1>");
pw.println("<HR WIDTH=\"100%\">");
pw.println("<BR>" + message +"<BR>");
pw.println ("<B>You have hit this page " + ival + " times" +
"</B><br>");
pw.println("<FORM ACTION = \"/MessageLogin.html\" METHOD = \"GET\">");
pw.println("<P><INPUT TYPE = \"submit\" VALUE = \"Back\"></FORM>");
pw.println("</BODY></HTML>");
pw.flush();
pw.close();
}
}
Figure 297. MessageLogin.java (2/2)
Designing Applications for WebSphere
299
<html> <head>
<title>Exchange Message</title>
</head>
<BODY>
<h1>Exchange Message</h1>
<hr>
<h2>Send Message</h2>
<SERVLET NAME="SendMessage">
</SERVLET>
<B> Click The Button and Send User Message!</B>
<hr>
<h2>Check Message</h2>
<SERVLET NAME="CheckMessage">
</SERVLET>
<P><B> Click The Phone and Get Your Message!</B>
<hr>
</body> </html>
Figure 298. ExchangeMessage.jsp
To use this sample:
1. Copy MessageLogin.html and ExchangeMessage.jsp into your HTTP
document root. For example, the default document root for IBM HTTP Server
V1.3.3 on Windows NT is \Program Files\ IBM HTTP Server\htdocs.
2. Copy MessageLogin.java into <ASRoot>/servlets. Compile
MessageLogin.java and create the MessageLogin.class file:
C:\WEBSPH~1\APPSER~1\servlets>javac MessageLogin.java
C:\WEBSPH~1\APPSER~1\servlets>
3. In this scenario, the users wakako and fox are already registered in the user
profile. To make a user profile, please refer to 5.2.3, “UserProfile Sample” on
page 256.
4. Open the URL http://<hostname>/MessageLogin.html. The following window
appears:
300
WebSphere Application Servers: Standard and Advanced Editions
Figure 299. Login Interface for Exchanging Messages
5. The user wakako was logged in from this window.
6. The user fox was logged in to the server from another client machine.
7. The user wakako sees the following window (Figure 300 on page 302). The
noMessageWaiting image is rendered below the Check Message string, since
this user hasn’t received the message yet.
Designing Applications for WebSphere
301
Figure 300. If the User Name Exists in the User Profile, This Windows Will Appear
8. Click the Send User Message button to send a message to someone.
9. The following window comes up. Click the Recipient pull-down menu and the
users with a session object are shown (Figure 301):
Figure 301. Sending a Message
10.If you open the Active Session Monitor page at that time (click Server
Execution Analysis -> Monitors -> Active Sessions from the Application
Server Manager), the following sessions will be monitored:
302
WebSphere Application Servers: Standard and Advanced Editions
Figure 302. Active Session Monitor
11.The user wakako chooses the user fox, specifies the message and clicks the
Submit Message button.
Figure 303. Input the Message and Click the Submit Message Button
12.The following dialog box comes up. Click OK .
Figure 304. Message Posted
Designing Applications for WebSphere
303
Figure 305. "fox" Login from Another Machine
13.If the user fox logs in after these steps (Figure 305), the following window will
appear. The messageWaiting image will be rendered with a hot link to the
GetMessage servlet (Figure 306).
Figure 306. Fox Has Message
304
WebSphere Application Servers: Standard and Advanced Editions
14.Click the image or the string below the image and you can get the following
message:
Figure 307. The Message from wakako
15.If you reload this page, you will get the following message (Figure 308), since
the GetMessage servlet clears the message after retrieving it:
Figure 308. The Message is Disabled
16.If the user is not registered to the user profile, the following window will appear
and the user’s session is invalidated from the MessageLogin servlet:
Designing Applications for WebSphere
305
Figure 309. Login Denied
5.4 Connection Pooling
Connecting and disconnecting from a data server causes you to use resources
inefficiently. The connection manager lets you connect and disconnect to a data
server more efficiently by pooling connections and reusing them. That reduces
the overhead of connecting and disconnecting
The servlets use the connection pool as follows:
When a user makes a request over the Web to a servlet, the servlet uses an
existing connection from the pool, meaning the user request does not incur the
overhead of a data server connection. When the request is satisfied, the servlet
returns the connection to the connection manager pool for use by other servlets.
The user request, therefore does not incur the overhead of a data server
disconnection.
The connection manager also lets you control the number of concurrent
connections to a data server product. This is very useful if the data server license
agreement limits you to a certain number of concurrent users.
There is a good introduction to connection manager in the WebSphere
documentation at http://[hostname]/IBMWebAS/doc/whatis/iccmgr.html.
5.4.1 Key Terms
Data server refers to many different data sources, including:
• Relational databases such as DB2, Oracle, Informix, and Sybase.
• Other types of products, whose special services for managing and accessing
data vary by product.
Connection Manager Connection - We use this term to distinguish from "real"
connections to the underlying data server, for example, a database or MQ.
306
WebSphere Application Servers: Standard and Advanced Editions
5.4.2 Connection Manager Architecture
The Connection Manager maintains a pool of open data server connections to
specific data server products. Each data server can have one or more identical or
non-identical pool(s). Multiple data servers can be supported by one running
instance of the connection manager.
Figure 310 illustrates the typical interactions between the connection manager
and a servlet seeking to use a connection from the connection manager's
connection pool. The following list traces the steps that are followed when a
connection request is made. The sequence changes if a connection is not
available when the servlet requests one.
Web Server
Application Server
2
8
Servlet
Connection
5
1
3
4
Connection Manager
Pool
7
9
10
6
DB
Figure 310. Connection Manager Architecture
1. The connection manager, which runs under the application server, is loaded
by the application server when the first servlet tries to communicate with the
connection manager. The connection manager stays loaded as long as the
application server is running.
2. The application server passes a user request to a servlet.
3. The servlet uses methods from the connection manager to request a
connection from the pool.
4. The pool gives the servlet a connection.
5. The servlet uses the connection to talk directly to the data server, using the
standard APIs for the specific data server.
6. The data server returns data through the connection to the servlet.
Designing Applications for WebSphere
307
7. When the servlet ends communications with the data server, the servlet
returns the connection to the pool for use by another user request.
8. The servlet sends the response back through the application server to the
user.
5.4.2.1 Monitoring the Connection Manager
The application server manager provides a monitor for the connection manager
called DB Pool Connections. See the application server help menus for a detailed
description of the information the monitor provides. You can use that information
to see how connection pools are performing and to suggest possible changes in
the connection pool parameters. You can monitor a pool after you change the
parameters in order to see the change in pool behavior and to assist you in
further tuning of the pool. You can see this monitor by clicking Server Execution
Analysis -> Monitors -> DB Pool Connections (Figure 311):
Figure 311. DB Pool Connections
You can select the specific pool to monitor from a selection list (Figure 312).
308
WebSphere Application Servers: Standard and Advanced Editions
Figure 312. You Can Select the Specific Pool
The resulting monitor display consists of:
• Each connection in the pool
• Summary information about the entire pool
5.4.2.2 Each Connection in the Pool
Information provided by the connection list includes:
• Owner Class
The servlet class that currently owns the connection (or the servlet class that
last released the connection, if it is free) as shown in Figure 313.
Designing Applications for WebSphere
309
Figure 313. Owner Class Field
You can get a class name that is known to the connection manager by using
the getIBMConnection(IBMConnSpec connSpec, String ownerClass) method
in your servlet. NoRelease.java uses this method as you can see below. If you
use the getIBMConnection(IBMConnSpec connSpec) method, then
"Unknown" appears in this field.
A Piece of NoRelease.java
cmConn0 =
(IBMJdbcConn)connMgr.getIBMConnection(spec0,"NoRelease");
• In-Use
This determines if the connection is in use by a servlet. If the connection is
currently free or available for a servlet connection, then this field is blank.
Otherwise, the field contains a check mark (as shown in Figure 313).
• Verify Time
The verify time stamp and the last used time stamps for the connection.
• DB URL, DB User, Driver Class
Additional information, some of which may depend on the type of data server.
The fields, for example DB URL, are specific to each JDBC data server.
310
WebSphere Application Servers: Standard and Advanced Editions
5.4.2.3 Summary Information about the Entire Pool
Information provided by the pool summary includes:
• Pool Name
This is the unique name of a pool, used by the servlet programmer to access
the pool and used within the monitor to identify a pool and the statistics
associated with it.
• Total Connections
This is a cumulative total of the successful requests for connections made to
the pool.
• Requests
This is a cumulative total of both the successful and the unsuccessful requests
for connections made to the pool.
• Waiting
This is the number of connection requests currently waiting for a connection
from the specified pool. When a servlet's waitRetry parameter is set to true,
the servlet can wait for a short time for a connection if the pool doesn’t have
one immediately available. Requests waiting for a connection will fail if the
connection is not made available within the time specified by the connection
timeout parameter. See the rejected statistic below for the number of requests
that actually failed. If the servlets using this pool are important, you may want
to increase the maximum connections parameter for the pool to reduce the
chances that a connection request will have to wait.
• Rejected
This is the number of connection requests that were refused a connection. It is
the cumulative total of the waiting requests that failed to get a connection, plus
failed requests from servlets whose waitRetry parameter was set to false and
thus failed right away when a connection was not available. Generally, you will
want rejected to be a small number compared to total connections, particularly
if important servlets are using the pool. Look at increasing the maximum
connections and the connection timeout parameters of the connection pool to
keep rejected to a small percentage of total connections.
• Orphaned
This is the number of connections taken away from servlets that have died or
otherwise become unresponsive, or taken away from servlets that may have
been coded improperly. The connections are taken away from the servlets in
the periodic reap process and are returned to the pool so that other servlets
can use them. Something is probably wrong if the orphaned statistic is
something other than zero, and you should look at making some servlet
coding changes. If the value is other than zero, it may mean that connections
are not being used and yet the connections are not available to be used by a
new request. This can happen if a servlet fails without explicitly releasing
connections that it owns, or if the servlet performs normally but the
programmer neglects to explicitly release the connection after sending the
response back to the user. The servlet should probably be changed to use the
releaseIBMConnection() method in case of a servlet failure and at the end of a
successful response. The orphaned statistic can also be greater than zero if a
servlet neglects to periodically verify with the connection manager that it still
needs to hold a connection over an extended period of time.
Designing Applications for WebSphere
311
For example, we tested the "NoRelease" servlet that doesn't execute the
releaseIBMConnection method. See Table 30 for the results of that test:
Table 30. DB Pool Setting
Parameters
Values
Parameters
Values
Maximum Connections
10
Maximum
Age
10
Minimum Connections
2
Maximum
Idle Time
30
Connection Timeout
200000
Reap Time
60
After executing this servlet, we found this servlet using CM connection in DB Pool
Monitor (Figure 314):
Figure 314. "No Release" Servlet That Doesn’t Release the Connection
At that time, we found that the orphaned statistic was not zero (Figure 314).
• Idled
This is the cumulative number of connections that the reap process has
removed from the pool (and disconnected from the data server). The
connections may be removed after they remain idle (unassigned to any
servlets) beyond a certain time. If the Inactive statistic is high compared to
total connections, it may mean that there is a lot of connect/disconnect
overhead compared to the number of requests actually serviced. This in turn
might be due to excessive fluctuations in the number of user requests.
Connections are created to satisfy a temporary peak, and then discarded
312
WebSphere Application Servers: Standard and Advanced Editions
during a temporary lull. You might want to make the pool less sensitive to such
fluctuations by increasing the reap time or maximum idle time pool
parameters.
5.4.2.4 Managing Connections
Use the Connection Management page to define connection pools corresponding
to data servers, such as DB2. The application server connection manager lets
user servlets borrow data server connections from these pools, helping you
control and reduce the resources used by your Web-based applications.
Viewing the Pool Types Supported by the Application Server
Click the Pool Types tab to view the types of data servers supported by the
connection manager. Currently, Java Database Connectivity (JDBC)-compliant
databases are supported.
Adding Connection Pools
To add connection pools:
1. View the Setup -> Connection Management page. (see Figure 315.)
2. Click the Pool List tab.
Figure 315. Pool List
3. Click the Add button.
4. In the Pool Name field, specify the pool to create (Figure 316).
Designing Applications for WebSphere
313
Figure 316. Pool Congfiguration
5. In the other fields, enter your preferred configuration settings.
6. Click the OK button.
Note: Tell your servlet programmers the Pool Name so they can use it in the
servlets that access the connection pool.
5.4.2.5 Each of the Fields in the Pool
You can see this field information at
http://<hostname>/:9527/admin/webexec/WASHelp/hfcm.htm.
• Pool Type
The type of data server used by this pool of connections. JDBC indicates a
JDBC-compliant database. A data server is a product that helps you manage
and access data. Usually, it is a relational database such as DB2, Oracle,
Informix, or Sybase.
• Pool Name
The unique name for this pool of connections. Servlet programmers need to
know this name for their servlets to use this connection pool.
• Maximum Connections
Maximum number of connections that can be in the pool. Consider setting it to
the maximum number of users permitted by your data server product license
agreement.
• Minimum Connections
The minimum number of connections that can remain in the pool as a result of
the reap process. The connection manager periodically removes connections
that become idle or orphaned. Use this setting to keep from removing too
many connections, erasing resource usage performance gains.
• Connection Time Out
The length of time (in milliseconds) the connection manager will wait for a
connection to become free when all connections in the pool are currently in
314
WebSphere Application Servers: Standard and Advanced Editions
use and the number of connections has reached the maximum (meaning no
new connections can be created to fulfill the need).
• A value of 0 allows the connection manager to wait forever.
• A value of -1 disables the wait (an exception is immediately thrown if a
connection is not available).
• A value of 1000 to 2000 (1 to 2 seconds) is suggested.
Servlet programmers must know the value of the connection timeout to
effectively set the waitRetry parameter in their servlets.
• Maximum Age
The maximum number of seconds a connection can be idle before the reap
process releases the connection from the servlet that owns it.
• A value of -1 disables this function; the reap process will not release any
connections from idle servlets.
• A value of 900 to 1800 (15 to 30 minutes) is suggested.
• Maximum Idle Time
The maximum number of seconds an unassigned connection can remain in
the pool.
• A value of -1 disables this function; the reap process will not remove any
connection from the pool and disconnect it from the data server.
• A value of 900 to 1800 (15 to 30 minutes) is suggested.
• Reap Time
The interval (in seconds) at which the connection manager performs the reap
process.
• A value of -1 disables this function; the reap will not be performed,
regardless of the values specified in the Maximum Age or Maximum Idle
Time parameters.
• A value of 1800 to 3600 (30 to 60 minutes) is suggested.
5.4.2.6 How to Manage CM Connections When the DB Server Is Down
When CM connections lose DB connections for some reason (for example, a DB
server goes down or there are network problems), the connection objects still
remain in the pools.
If we execute an SQL query with this connection, an SQL exception would be
thrown even after the DB connections were recovered. For example, the SQL
exception might look like the following:
get connection, process statement: [IBM][CLI Driver][DB2/NT] SQL1224N A datab
agent could not be started to service a request, or was terminated as a resul
database system shutdown or a force command. SQLSTATE=55032
When the DB connection was terminated from the DB2 command line processor,
the DB Pool Connection seemed OK since the DB connections still existed (see
Figure 317 on page 316).
Designing Applications for WebSphere
315
C:\WebSphere\AppServer\classes>cd \
C:\>db2 list applications
Auth Id Application
Name
Appl.
Handle
Application Id
DB
Name
# of
Agents
-------- -------------- ---------- ------------------------------ -------- ----DB2INST1 java.exe
142
*LOCAL.DB2.990601224056
SAMPLE
1
DB2INST1 java.exe
141
*LOCAL.DB2.990601223702
WBSPHERE 1
C:\>db2 force application all
DB20000I The FORCE APPLICATION command completed successfully.
DB21024I This command is asynchronous and may not be effective immediately.
C:\>db2 list applications
SQL1611W No data was returned by Database System Monitor.
Figure 317. The Connections in the Pool
The servlet can’t connect to the database using this connection (Figure 318 on
page 317):
316
WebSphere Application Servers: Standard and Advanced Editions
Figure 318. SQL Exception
We can solve this no DB connection problem with the removeIBMConnection
method of the com.ibm.servlet.connmgr.IBMConnection class. This method
removes the connection handle from the pool. We should design all servlets to
implement this method when they catch an SQL exception.
rs.close();
stmt.close();
}catch(Exception e ){
pw.println("Exception!<BR>");
e.printStackTrace(pw);
//************************
// remove IBMConnection
//************************
try{
cmConn.removeIBMConnection();
pw.println("removeIBMConnection...<BR>");
}catch(Exception e2 ){
pw.println("Exception at removeIBMConnection<BR>");
pw.println(e.toString()+"<BR>");
}//end of catch e2
pw.flush();
}//end of catch e
Figure 319. The removeIBMConnection Method
The one thing we must be careful about is that this method removes only one
connection handle at a time. If you want to remove all of the connection objects,
you must implement proper program procedures.
Note: You can use the removeIBMConnection method with the WebSphere
Application Server V2.X API or later. WebSphere V1.X doesn’t implement this
method.
Designing Applications for WebSphere
317
5.4.2.7 Reap Process
The connection manager removes idle connections from the pool because they
waste resources. To decide which connections are idle the connection manager
checks the connection flags and time stamps in a periodic reap of the connection
pool. There are two kinds of reap:
1. Reap Connections from the Servlet
The connection manager looks at the last-used time stamp of the in-use
connections. If the time between the last-used and current time exceeds the
maximum age configuration parameter, the connection is assumed to be an
orphaned connection, meaning the owning servlet has died or is otherwise
unresponsive. The orphaned connection is returned to the pool for use by
another servlet, its in-use flag is set to false and its verify and last used time
stamps are set to the current time.
2. Reap Idle Connections from the Pool
The connection manager examines connections not in use by any servlet, that
is, those connections whose in-use flags are false. If the time between the
last-used and current time exceeds the maximum idle time configuration
parameter, the connection is assumed idle. Idle connections are removed from
the pool, down to the lower limit specified by the Minimum Connections
configuration parameter.
We tested this function in the following setting:
• Change the JdbcDb2 Pool setting as follows, so that we can evaluate the reap
process and get sensitive status changes:
Table 31. DB Pool Setting
Parameters
Values
Parameters
Values
Maximum Connections
10
Maximum
Age
10
Minimum Connections
2
Maximum
Idle Time
30
Connection Time Out
200000
Reap Time
60
• Executed servlets named.
• NoRelease - This servlet doesn't execute the releaseIBMConnection()
method. This causes the problem that:
• Some connections are not being used, and are not available.
• The orphaned statistic is not 0. Check the DB monitor.
• For the orphaned statistic we already showed the result in 5.4.2.3,
“Summary Information about the Entire Pool” on page 311.
• NoRelease2 - This servlet doesn't execute the releaseIBMConnection()
method. The class name of this servlet appeared as an "Unknown" class
because it doesn’t tell the servlet name to the connection manager.
• Websphere - This servlet doesn't execute the releaseIBMConnection()
method. This opens the connection to the wbsphere database, while two of
the servlets above connect to the sample database.
• Checked DB Pool Monitor.
318
WebSphere Application Servers: Standard and Advanced Editions
At first we could see this status on the DB Pool ConnectionsMonitor. As you
can see, we can connect to multiple databases in one pool:
Figure 320. Servlets Owing Connections
You can get the latest information by clicking the Refresh button (Figure 321).
Figure 321. DB Monitor Refresh Button
After a few minutes, we could see the connection manager reaped CM
connections from the pool (Figure 322):
Figure 322. Connection Manager Reaped Connections from Servlets
The minimum connections parameter is two, so two connections remain in the
pool. Take note of the fact that the connection to the wbsphere database was
reaped although it was only connected to this database. That’s why we don’t
Designing Applications for WebSphere
319
recommend connecting to multiple databases from one pool. If you want to
connect to multiple databases, it is easier to manage connections to each
database in separate pools.
Figure 323. Connection Manager Reaped Idle Connections from the Pool
You can create multiple pools for the same database. The pools can be
configured to provide different service levels, so that an important servlet
using a "high service-level" pool is more responsive than a less critical servlet
(Figure 324).
Figure 324. Multiple Connection Manager Pools on the Same Database
5.4.3 Creating Connection Manager Applications
Edit the properties files for the XtremeXML and IBMConnMgrTest samples using
the DB2 user ID and password information.
• Copy the file <server root>\samples\login.properties to <server
root>\servlets. Edit the file and change the database owner and login
parameters. Figure 325 shows an extract from the file with the values
change shown in bold. Change DB2owner to the DB2 user ID that you used
to create the sample database in step 1 in 5.4.2.7, “Reap Process” on page
318. If you want to access DB2 with a user ID other than the user ID and
password that WebSphere uses, change the dbUserid and dbPassword
values appropriately; otherwise leave them as null. On Windows NT the
WebSphere service does not run under any user ID by default, so you must
change these values. If you have changed the name of the sample
database that you created in step 1 in 5.4.2.7, “Reap Process” on page 318
to something other than sample, then change the dbName parameter to
that value.
320
WebSphere Application Servers: Standard and Advanced Editions
XtremAdvXml.dbOwner=DB2owner
XtremAdvXml.dbUserid=YourDB2Userid
XtremAdvXml.dbPassword=YourDB2Password
...
JDBCServlet.dbOwner=DB2owner
JDBCServlet.dbUserid=YourDB2Userid
JDBCServlet.dbPassword=YourDB2Password
JDBCServlet.dbName=sample
Figure 325. Lines to Change in <server root>\servlets\login.properties
• Edit the file <server root>\servlets\IBMConnMgrTestStrings.properties and
change the values shown in Figure 326:
# UserProfileConfig
upc.db=SAMPLE
upc.owner=DBOwner
upc.userid=DBUser
upc.password=DBPassword
# HTML text
# LOCALIZE THIS
html.title=Test for IBMConnMgrTest Servlet
html.nobodyfound=Nobody named Parker
html.greeting=G'day
# END OF MATERIAL TO LOCALIZE
Figure 326. Changes in <server home>/servlets/IBMConnMgrTestStrings.properties
Change the upc.db parameter to the name of the sample database
(probably sample) and the upc.owner parameter to the owner of the sample
database. If you want to log in to DB2 with a user ID and password that is
different from the user ID and password that WebSphere runs under,
change the upc.userid and upc.password settings appropriately. Otherwise,
change them to the word null. On Windows NT the WebSphere service
does not run under a user ID and password by default so you must change
these values.
If you want to localize the servlet for your country change the html.* parameters
to something in your local language. The title heading html.title is used on the
servlet. When no results are returned from the database, the message
html.nobodyfound, is displayed. To greet someone, html.greeting is used.
IBM Connection Manager Test Servlet
This servlet, while not terribly exciting visually, demonstrates the IBM connection
manager performing connection pooling. To run the servlet:
• Click the Database Servlet (Figure 327) from the Samples page. Another
browser window will come up.
Designing Applications for WebSphere
321
Figure 327. Sample Page ( http://[hostname]/IBMWebAS/samples/index.html)
• Click Run IBMConnMgrTest (Figure 328). Yet another browser window
should come up with a greeting for JOHN Parker(). The form of the greeting
derives from the text you entered in the database setup on page 320 for the
html.greeting parameter.
322
WebSphere Application Servers: Standard and Advanced Editions
Figure 328. Click Run IBMConnMgrTest
Figure 329. The Result of IBMConnMgtTest
• If something goes wrong you should get the error message that you entered
for the html.nobodyfound parameter in the database setup on page 320.
5.4.3.1 How Servlets Use the Connection Manager
All servlets using the connection manager will follow these steps; RmvCon2.java
is used to following these steps.
Designing Applications for WebSphere
323
import
import
import
import
import
import
import
import
java.io.*;
javax.servlet.*;
javax.servlet.http.*;
java.sql.*;
java.util.*;
java.text.*;
com.sun.server.util.*;
com.ibm.servlet.connmgr.*;
//for conmgr
/**
* This is an example of a IBMConnection Manager
* Servlet.
**/
public class RmvCon2 extends HttpServlet
{
// for IBMConnMgr
static IBMConnMgr connMgr = null;
static IBMConnSpec spec0
= null;
static String poolName
= "JdbcDb2"; // from Webmaster
// ResourceBundle class constant
public final String BASENAME = "samples";
// con is initialized at startup of servlet
static String url0=null;
static String Debug = null;
static String jdbcDriver = "COM.ibm.db2.jdbc.app.DB2Driver";
static{
try{
// register the driver with DriverManager
Class.forName(jdbcDriver);
}catch (ClassNotFoundException e){
e.printStackTrace();
}
}
Figure 330. RmvCon2.java
1. Create the connection specification (Figure 331).
The servlet prepares a specification object identifying information necessary
for connecting to the underlying data server. Some of the information is unique
to the specific data server, while some is general, applying to any underlying
data server. The servlet either prepares the specification only once and uses it
for all user requests, or it prepares a new specification for each user request. If
a new specification is prepared for each user request, it must be done before
step 3 on page 325, which uses the specification. It is usually done in the init
method.
324
WebSphere Application Servers: Standard and Advanced Editions
public void init(ServletConfig sc){
try{
super.init(sc);
}catch (ServletException e){
e.printStackTrace();
}
// URL is
url0 = "jdbc:db2:sample";
//local DB
try{
// **********
// * STEP 1 *
// **********
// Create JDBC connection specification.
spec0 = new IBMJdbcConnSpec
(poolName,
// pool name from Webmaster
true,
// waitRetry
jdbcDriver, // Remaining four
url0,
// parameters are
"db2inst1",
// specific for a
"db2inst1");
// JDBC connection.
Figure 331. Create JDBC Connection Specification
It is worth noting that different specifications can be used to get connections
with different properties. For example, a data server may allow access to
certain critical data only if the connection was created with a specific user ID.
Therefore, the specification must properly identify the user ID in order to get
the suitable connection to the data server.
2. Get a reference to the connection manager (Figure 332).
The servlet gets a reference to the connection manager to communicate with
the connection manager. This needs to be done only once in the lifetime of the
servlet.
// **********
// * STEP 2 *
// **********
// Get a reference to the connection manager.
connMgr = IBMConnMgrUtil.getIBMConnMgr();
}catch(Exception e){
System.out.println("set connection spec, get connection manager: " +
e.getMessage());
}
} // init
Figure 332. Get a Reference to the Connection Manager RmvCon2.java
3. Get a connection manager connection (Figure 333).
The servlet asks the connection manager for a connection to a specific data
server using the connection specification prepared in step 1 on page 324. The
Designing Applications for WebSphere
325
connection object returned is from a connection manager pool and is an
instance of a class defined in the connection manager APIs. It isn’t an object
from a class in the API set of the underlying data server. It calls this first
connection a connection manager connection, or a CM connection for short.
Usually, your servlet gets a CM connection for every user request.
public void doGet(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException{
IBMJdbcConn cmConn0
= null;
// for IBMConnMgr
String
String
Object
String
tbl = null, col = null;
colStr = null;
colVal = null;
[] qArgs = new String [6];
MessageFormat mf = null;
PrintWriter pw = null;
try{
res.setContentType("text/html; charset=SJIS");
pw = res.getWriter();
pw.println("<HTML>");
pw.println("<HEAD><TITLE>RmvCon</TITLE></HEAD>");
pw.println("<BODY>");
pw.println("<H1>RmvCon Test</H1>");
pw.println("getIBMConnectiotion<BR>");
cmConn0 = (IBMJdbcConn)connMgr.getIBMConnection(spec0,"RmvCon");
Figure 333. Get a Connection Manager Connection
4. Use the CM connection to access a pre-established data server connection.
The servlet invokes a method on the CM connection returned in step 3,
retrieving an object defined in the API set of the underlying data server. Call
this object a data server connection (or a data connection for short) to
distinguish it from the CM connection. The data connection, unlike the CM
connection, is from the underlying data server API set. The data connection is
not created for the servlet. The servlet instead uses the pre-established data
connection by virtue of owning a CM connection pool from the pool. The data
connection will be used for the actual interactions with the data server, using
the methods from the underlying data server API set. For example, in the
sample servlet code the underlying data server will be a JDBC database and
the data connection object will be from the connection class in the JDBC APIs.
The JDBC APIs are found in the java.sql package.
326
WebSphere Application Servers: Standard and Advanced Editions
pw.println("getJdbcConnection<BR>");
// **********
// * STEP 5 *
Run DB query (printRows)
// **********
try{
Connection con= cmConn0.getJdbcConnection();
Figure 334. get Connection Object of java.sql Package
5. Interact with the data server (Figure 335).
The servlet interacts with the data server, retrieving data, updating data, and
so on, using methods of the data connection object. These methods will be
specific to the underlying data server, because the data connection will
actually be from the API set of the underlying data server. The data
connection for a different underlying data server will have different methods.
Statement stmt = con.createStatement();
pw.print("<B>select * from employee </B><BR>");
ResultSet rs=stmt.executeQuery("select * from employee");
Figure 335. Execute SQL Query and Get ResultSet
Full documentation for the methods are available with the API documentation
for the specific data server product. For example, for a JDBC data connection,
you will need to look at the documentation for the java.sql package and at any
documentation that comes with the JDBC-enabled relational database you are
using. If you use the data connection for more than one data server interaction
within the same user request, you may want to verify before the additional
interactions that your servlet still owns the associated CM connection. To
verify that it still owns a connection, the servlet invokes the
verifyIBMConnection() method that in turn gets the connection manager to
check the verify time stamp of the connection. If the servlet still owns the
connection, the last-used time stamp is automatically updated to the current
time, as part of invoking the verifyIBMConnection() method. The servlet then
uses the connection to communicate with the data server, confident that the
connection will work. When the servlet finishes with the connection, it releases
it back to the connection pool. The connection manager sets the in-use flag to
false, and sets the verify and last-used time stamps to the current time.
6. Prepare and send the response.
The servlet prepares and returns the response to the user request. In this step
you will probably not be using any connection manager APIs.
Designing Applications for WebSphere
327
// print out a header row of column names
ResultSetMetaData rsmd = rs.getMetaData();
int numCols = rsmd.getColumnCount();
for(int i = 1;i <= numCols;i++){
col = rsmd.getColumnName(i);
pw.print("<B>" + col + " </B>");
}
pw.println("<BR>");
}
rs.close();
stmt.close();
Figure 336. RmvCon2.java ()
Add a removeConnection statement when the exception is caught (Figure
337):
}catch(Exception e ){
pw.println("Exception!<BR>");
e.printStackTrace(pw);
//************************
// remove IBMConnection
//************************
try{
cmConn0.removeIBMConnection();
pw.println("removeIBMConnection...<BR>");
}catch(Exception e2 ){
pw.println("Exception at removeIBMConnection<BR>");
pw.println(e.toString()+"<BR>");
}//end of catch e2
//************************
}
pw.println("</BODY>");
pw.println("</HTML>");
pw.flush();
}catch( Throwable e ){
pw.println(e.toString());
pw.flush();
}
Figure 337. RmvCon2.java
7. Release the connection (Figure 338).
The servlet returns the CM connection to the connection manager pool,
freeing the connection for use by another servlet or by another request to the
same servlet.
328
WebSphere Application Servers: Standard and Advanced Editions
// **********
// * STEP 6 *
// **********
// Release the connection back to the pool.
finally{
if(cmConn0 != null){
try{
cmConn0.releaseIBMConnection();
pw.println("cmConn0 released");
}catch(IBMConnMgrException e){
System.out.println("release connection: " + e.getMessage());
}
}
}
} // end of doGet()
}//end of class RmvCon2
Figure 338. Release the Connection
Connection Manager APIs
You can find the connection manager APIs at:
http://[hostname]/IBMWebAS/doc/apidocs/Package-com.ibm.servlet.connmgr.html.
Designing Applications for WebSphere
329
330
WebSphere Application Servers: Standard and Advanced Editions
Chapter 6. Enterprise Access
In a conventional enterprise system, relational databases implement enterprise
data, whereas transaction processing such as CICS implements enterprise logic.
In many cases, this model brings up many issues such as reusability, application
complexity, distributed processing, presentation quality and difficulties in serving
an emerging service channel such as the Internet. Current Internet technology
has enabled enterprises to serve customers, or even to serve other enterprises
via business-to-business transaction directly over the Internet. In any case,
enterprise logic and data accesses are very crucial.
The first modification to the conventional model is to change the view of
enterprise data and logic into an object model. In this model, the object not only
represents data but also logic pertaining to the data and relationships to other
objects. Next, to improve architectural performance such as distributed
computation and better reusability, we extend the object model into a component
model. The Java bean is the component model in the Java language. The
Enterprise Java Bean is the refinement of the Java bean model to support critical
enterprise tasks.
The ultimate goals in using a component model in the enterprise access
architecture are:
• Reusability of enterprise computational elements
• Scalability, managing application complexity
• Maintainability of applications
• Separation of responsibility between presentation and content generation
(enterprise logic)
• Object persistence, storing object in a database
The EJB model is designed specifically to address these issues. It is the best
model in the Java platform for handling enterprise access. The EJB encapsulates
enterprise data and associated logic into one component. Since EJB represents
data, it should be persisted (stored) into a database. As EJB may need to store its
logic state, the persistency means storing the EJB data and logic state into the
database. The EJB model delivers two types of persistence:
1. EJB Container Managed Persistence
It provides a simple persistence solution by letting the container handle the
persistence. However, it can’t handle complex issues such as object
associations, inheritance and complex mappings.
2. EJB Bean Managed Persistence
In this EJB type, the EJB manages its own persistence. Any persistence
issues should be handled by the EJB.
The EJB model is still undergoing refinement. Some of the current EJB issues are
handling complex persistence and better managing object relationships.
In WebSphere Application Server, there are three enterprise access options:
© Copyright IBM Corp. 1999
331
• Using servlets to access enterprise data/logic directly. It is appropriate only for
simple applications, as it is not scalable to a complex model and it has no
inherent reusability.
• Using Data Beans to handle simple data operations directly. This technique
has no object persistence and is not scalable to the complex model.
• Using Enterprise Java Beans would be the logical answer for an enterprise
access issue.
Enterprise System
Application Server
Web Server
HTTP
Servlet
Engine
Browser
Database
DATA
BEAN
IIOP
EJB
Connector
Transaction
Processing
System
External
Enterprise
Systems
5460\546004
Figure 339. Enterprise Access in the WebSphere Environment
In this chapter, we discuss enterprise access in the WebSphere environment for
the following:
• Enterprise data access using a Java component to access an enterprise
relational database. We will discuss two underlying Java data access models:
the JDBC and the SQLJ.
• Enterprise logic accesses using connectors. This makes use of an existing
transaction processing system using the component model. Here, we describe
the two best techniques from IBM:
1. Using MQSeries for exchanging messages on any platform.
2. Using the CICS connector for accessing CICS servers that serve most
enterprise legacy systems.
6.1 JDBC
This section shows how to set up connectivity between WebSphere Application
Server and back-end databases.
6.1.1 JDBC Concepts
JDBC is a Java data interface standard that provides access to a wide range of
relational databases. To deliver database-independent access in Java language,
Java has included JDBC as a standard part of the Java platform. JDBC is a set of
interfaces that are implemented by the database vendor, and the vendor
implementation of these interfaces is called the JDBC driver for that vendor. The
332
WebSphere Application Servers: Standard and Advanced Editions
latest JDBC level is JDBC 2.0, which is available as a separate package from
Sun, or as a part of the Java 2 platform. Virtually all database vendors have
adapted the JDBC specification into their database products. However, the
vendor may not have implemented the latest JDBC version and does not have all
driver types as specified in the specification. Contact your database vendor for
specific information about its JDBC drivers. To find general information about
JDBC products and drivers, go to http://java.sun.com/products/jdbc.
JDBC enables Java programs to create sessions to databases, execute SQL
statements, and retrieve the results. The JDBC specification delivers a call-level
SQL interface for Java based on the X/Open SQL call level interface specification.
To confine SQL syntax and semantic diversities across database platforms, JDBC
also sets minimum SQL conformance to the SQL92 entry level SQL standard.
This gives guaranteed wide portability for applications designed to run on many
platforms.
The call-level interface limits operations to execute only raw SQL statements and
to retrieve the results. A Java program can issue an SQL string to be processed
by a database server at runtime. This mechanism also means dynamic
compilation, privilege and authorization checks. It allows flexibility for the program
to construct variable queries that are defined at run time. This model is also
known as the dynamic SQL model.
The JDBC specifies four major components: JDBC drivers, connections,
statements, and a result set. The database vendors deliver only the driver, which
should comply with JDBC specifications. Other components are in the JDBC API
package, which is the java.sql package. The JDBC API provides interface classes
for working with these components:
• The java.sql.Driver and java.sql.DriverManager for managing JDBC drivers
• The java.sql.Connection for using connections
• The java.sql.Statement, for constructing and executing SQL statements
• The Java.sql.ResultSet for processing the results
6.1.1.1 JDBC Driver
JDBC defines standard API calls to a specified JDBC driver. A JDBC driver is a
piece of software that performs the actual data interface commands. It is also
considered as the lower level JDBC API. This driver has interfaces in the form of
database client calls or database network protocol commands that are serviced
by a database server.
Depending on the interface type, there are four types of JDBC drivers:
1. Type 1, JDBC-ODBC bridge
The Type 1 driver translates JDBC API calls into ODBC API calls.
2. Type 2, Native-API driver
The Type 2 driver translates JDBC API calls into database native API calls. As
the driver uses native APIs, a Type 2 driver is vendor dependent. The driver
consists of two parts: a Java language part that performs the translation, and a
set of native API libraries.
3. Type 3, Net-Protocol
Enterprise Access
333
The Type 3 driver translates JDBC API calls into DBMS-independent network
protocol calls. The database server interprets these network protocol calls into
specific DBMS operations.
4. Type 4, Native-Protocol
The Type 4 driver translates JDBC API calls into DBMS native network
protocol calls. These native protocol calls are then converted by the database
server into DBMS operations.
A Java program can create several connections to several different databases
using different drivers. To manage driver operations, JDBC provides a driver
manager class, the java.sql.DriverManager, which is responsible for loading
drivers and creating new database connections.
The DriverManager registers any JDBC driver that is going to be used. If a Java
program issues a JDBC operation on a non-registered driver, JDBC will raise a
No Suitable Driver exception. There are several ways to register a driver:
• Register the driver explicitly by using:
DriverManager.registerDriver(<driver-instance>)
where <driver-instance> is an instance of the JDBC driver class.
• Load the driver class by using:
Class.forName(<driver-class>)
where <driver-class> is the JDBC driver class.
This will load the driver into the Java Virtual Machine. When loaded, each
driver must register itself implicitly by using the DriverManager.registerDriver
method.
For example, to register the DB2 JDBC Type 2 driver which is in the
COM.ibm.db2.jdbc.app package, you can use either:
DriverManager.registerDriver( new COM.ibm.db2.jdbc.app.DB2Driver());
or
Class.forName("COM.ibm.db2.jdbc.app.DB2Driver");
Note: When a driver has a native API part and Java can’t find the native API
library, JDBC will raise a No Suitable Driver condition, even when the
DriverManager has registered the driver. In WebSphere you should also include
the native library directory path into the user libpath in the Java Engine setup.
6.1.1.2 JDBC Connection
When a program accesses a database, the program should create a session into
the database. This session holds a context for executing SQL statements and
returning the results. In the JDBC specification the session is represented by a
connection. Therefore, a JDBC connection is a session from a Java program to a
database.
A connection is identified by a URL, which has the following format:
"jdbc:<subprotocol>:<subname>"
where <subprotocol> specifies a particular database connectivity mechanism as
supported by a particular driver. The <subname> is a specific parameter of the
334
WebSphere Application Servers: Standard and Advanced Editions
subprotocol or driver, and it is dependent on the selected subprotocol. For
example, to define a connection to the SAMPLE database:
String urlString = String("jdbc:db2:SAMPLE");
To open a connection, a Java program should ask the DriverManager to open a
connection using a specified protocol and database:
Connection aConnection = DriverManager.getConnection(urlString);
The DriverManager will ask each driver in its driver list to support the specified
protocol. The first driver that can support the protocol is selected and is used to
open a connection to the specified database. By specifying different connection
URLs, a Java program can create several connections to several databases
simultaneously, even with different drivers.
6.1.1.3 JDBC SQL Statement
JDBC allows you to create and execute SQL statements. The SQL statements
being used should comply with the SQL92 entry level standard, which is
reasonably powerful. The program creates SQL statements and sends them to
the database server to be executed in the session context.
The JDBC has three interface classes for SQL statements: the java.sql.Statement
and its two sub-interfaces: java.sql.PreparedStatement and
java.sql.CallableStatement. Based on these interfaces, there are three
alternatives for creating SQL statements:
• Create a statement object by instantiating the java.sql.Statement class.
This object initially does not represent any SQL statement. It can construct
and execute an SQL statement by calling one of its execute methods. For
every execute method call, the JDBC driver sends the SQL statement for
run-time compilation and execution in the database server. For example:
Statement stmt = aConnection.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM EMPLOYEE");
• Create a prepared statement object for executing pre-compiled SQL statement
by instantiating the java.sql.PreparedStatement class.
When created, the object sends the SQL statement for compilation. The
compilation result is stored to be used in the subsequent execute methods.
This mechanism provides more efficient SQL execution than using a
statement object.
A prepared statement allows parameterized SQL statements. The parameter
is passed by value (as an IN parameter) and identified by ? tokens inside the
SQL statement. There are several setter methods, set <DataType> (DataType
is one of the common SQL data types), to set a parameter based on its
relative position among other parameters in the SQL statement. The
statement is executed when the program calls an execute method on the
object. For example:
// Select all employees which have salary > 30000.00 and
// bonus < 500.00
PreparedStatement stmt = aConnection.prepareStatement(
"SELECT * FROM EMPLOYEE WHERE SALARY > ? AND BONUS < ?");
stmt.setFloat(1,30000f);
stmt.setFloat(2,500f);
ResultSet rs = stmt.executeQuery();
Enterprise Access
335
• Create a callable statement object for executing database stored procedures
by instantiating the java.sql.CallableStatement class.
A callable statement is a type of prepared statement that is used for handling a
stored procedure call statement. Its interface is a class that extends the
PreparedStatement class. When created, the object sends the call statement
to the database server for compilation. The compilation result is stored to be
used in the subsequent execute methods.
A callable statement also allows parameterized stored procedures. In addition
to IN parameter passing, the interface also handles OUT parameter passing.
The CallableStatement.registerOutputParameter method registers the type of
parameter in the statement. After execution, use a getter method with the
same data type to retrieve the parameter. For example:
// Calculate, update and retrieve the new salary
// Call GetNewSalary(name,salary)
// name is IN parameter, salary is OUT parameter
CallableStatement stmt = aConnection.prepareCall("CALL GetNewSalary(?,?)");
stmt.setString(1,"Dilbert");
stmt.registerOutputParameter(2,java.sql.Types.DECIMAL,0);
stmt.executeUpdate();
BigDecimal newSalary = stmt.getBigDecimal(2,0);
The statement, prepared statement, and callable statement have several execute
methods:
• executeQuery(String aSQLStatement) for executing a query that returns a
single result set.
• executeUpdate(String aSQLStatement) for executing a statement that returns
no row, such as UPDATE, DELETE and INSERT statements.
• execute() or execute(String aSQLStatement) for executing a complex or
several SQL statements altogether which may return several result sets. Use
getResultSet and getMoreResults methods for obtaining the next result set.
6.1.1.4 JDBC Result Set
The JDBC result set contains a set of rows from the results of executing a query.
The java.sql.ResultSet interface class implements the result set. A column in a
row is specified by a positional index or by a column name. To retrieve a column
value, the ResultSet class provides several getter methods in the form of
get< DataType> (where DataType is one of common SQL data types). The getter
methods accepts column position or column name as its parameter. The
ResultSet.next method advances at the next row. It returns true if the next row
exists; otherwise, it returns false. For example:
Statement stmt = aConnection.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM EMPLOYEE");
while (rs.next()) { // Retrieve next record
String employeeNum = rs.getString(1");
String firstName = rs.getString("FIRSTNME");
float salary = rs.getFloat(3);
System.outl.println("Employee No: " + employeeNum
+ " First name: " + firstName
+ " Salary: " + salary);
}
336
WebSphere Application Servers: Standard and Advanced Editions
6.1.2 Using JDBC in Java Programs
After discussing JDBC components, we can put these components together in a
Java program. There are common steps in implementing JDBC in your Java
program:
1. Import JDBC classes. JDBC has become a standard in the Java platform. Its
classes are contained in the java.sql package, which is in the default JDK/JRE
class libraries. To include this package in your Java program, insert the
following line at the beginning of your program:
import java.sql.*;
2. Register the JDBC driver. This needs to be done only once in a program’s life
time. For example, to register the DB2 Type 2 driver:
Class.forName("COM.ibm.db2.jdbc.app.DB2Driver");
You can put this line inside a static initialization block so that it is executed only
once.
3. Create a connection to the database:
Connection conn = DriverManager.getConnection("jdbc:db2:SAMPLE");
4. Create SQL statements and execute them. Store the result set in ResultSet.
5. When processing finishes, do not wait for the Java garbage collection. Close
the connection immediately to release valuable database resources:
conn.close();
6.1.2.1 Transaction Support
All new JDBC connections are in auto-commit mode, which means that each
statement is executed as a separate transaction. To create a transaction that
consists of several statements, you must disable the auto-commit mode by using
the Connection.setAutoCommit(false) method. Then the connection will set an
implicit transaction up to the point where Connection.Commit or
Connection.Rollback is issued. The Commit or Rollback also set a new implicit
transaction.
conn = DriverManager.getConnection("jdbc.db2:SAMPLE");
// Disable the Auto-Commit mode
conn.setAutoCommit(false);
// A new transaction begins ...
...
... Some SQL statements are executed here ....
...
// The end of the first transaction
Connection.commit();
// A new transaction begins
...
...
// The end of the second transaction
Connection.rollback();
6.1.2.2 Example: JDBCAccess Utility Class
The following Java class illustrates the concepts we have discussed so far. The
JDBCAccess class is a utility class for creating a general SQL query. It has three
methods for basic JDBC operations: open, query and close. The class registers a
JDBC driver in its static initialization block. Any Java program can supply an
arbitrary SELECT statement into a query method.
Enterprise Access
337
The query catches an SQL exception if the query condition is not a valid SELECT
statement, or if the user does not have necessary privileges. In fact, this shows
the disadvantage of using a dynamic SQL statement model. The application can’t
guarantee that the SQL statement will run.
By default, the class static initializer reads file properties/connection.properties
for the driver name. The file must contain a line that specifies the driver name, for
example:
...
jdbc.driver = COM.ibm.db2.jdbc.app.DB2Driver
...
This file can also contain JDBC and SQLJ parameters. In the WebSphere
Application Server environment, you should put this file as:
<ASROOT>\properties\connection.properties.
The class provides three forms of open methods:
1. open(), which does the actual connection creation.
2. open(String url, String user, String password) sets connection parameters and
calls open().
3. open(String propertyFileName). To enable easy configuration, this class can
read connection parameters from a property file. The file should contain
property entries for a URL connection, database user ID and password. For
example, a property file might look like the following:
#
# Sample property file for JDBC ...
#
jdbc.url = jdbc:db2:SAMPLE
jdbc.user = tsup1
jdbc.password = SWA109R
The following lines of codes illustrate the usage of this class:
...
JDBCAccess jdbc = new JDBCAccess();
jdbc.open("jdbc:db2:SAMPLE", "db2inst1", "SWA109R");
String qSql = "SELECT firstnme, salary FROM employee";
ResultSet rs = jdbc.query(qSql);
while(rs.next()) {
System.out.println("First Name: " + rs.getString(1)
+ " Salary: " + rs.getFloat(2));
}
...
Later in this chapter, we use this class again for generic JDBC query for DB2 and
Oracle platforms.
338
WebSphere Application Servers: Standard and Advanced Editions
package com.ibm.redbook.sg245460;
import java.sql.*;
import java.util.*;
import java.io.*;
public class JDBCAccess
{
private Connection conn=null;
private Statement stmt = null;
private ResultSet rset = null;
//
// Default driver and connection parameters
//
private static String driverName = "COM.ibm.db2.jdbc.app.DB2Driver";
private String urlString = "jdbc:db2:SAMPLE";
private String dbUser = "tsup1";
private String dbPassword = "SWA109R";
static {
try {
Properties p = new Properties();
p.load(new FileInputStream("properties/connection.properties"));
driverName = p.getProperty("jdbc.driver");
Class.forName(driverName);
} catch(IOException e) {
e.printStackTrace();
} catch(ClassNotFoundException e) {
e.PrintStackTrace();
}
}
public Connection open() throws SQLException {
conn = DriverManager.getConnection (urlString,dbUser,dbPassword);
return conn;
}
public Connection open(String url, String user, String password) throws SQLException {
urlString = url;
dbUser = user;
dbPassword = password;
return open();
}
public Connection open(String propertyFileName) throws SQLException {
try {
Properties p = new Properties();
p.load(new FileInputStream(propertyFileName));
urlString = p.getProperty("jdbc.url");
dbUser = p.getProperty("jdbc.user");
dbPassword = p.getProperty("jdbc.password");
} catch(IOException e) {
e.getMessage();
}
return open();
}
Figure 340. JDBC Example: JDBCAccess Utility Class (1/2)
Enterprise Access
339
public ResultSet query(String qSql) {
rset = null;
try {
stmt = conn.createStatement ();
rset = stmt.executeQuery (qSql);
} catch(SQLException e) {
e.printStackTrace();
}
return rset;
}
public void close() {
try {
rset.close();
stmt.close();
conn.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
}
Figure 341. JDBC Example: JDBCAccess Utility Class (2/2)
6.1.3 SQLJ
SQLJ is the embedded SQL in Java language. SQLJ statements are similar to the
embedded SQL statements in ordinary programming languages, which are
precompiled and bound into the database. SQLJ statements are static and based
on the ANSI standard SQLJ language syntax. The SQLJ static SQL model is
designed to complement the JDBC dynamic SQL model. In a static SQL
environment, a program that contains SQL statements can’t change SQL
statements during run time. The program undergoes pre-compilation, which
checks SQL syntax, verifies SQL consistency against database schema, checks
data transformation between Java data types and SQL data types. For more
information about SQLJ, visit its Web site at http://www.sqlj.org.
SQLJ has two components: the translator and the run-time components. Both are
written in pure Java. The SQLJ translator performs precompilation and translates
embedded SQL statements into SQLJ run-time calls. The SQLJ specification
allows the run-time component to perform SQL operations directly into the
database or to issue JDBC calls to the database via the JDBC layer.
Developers create embedded SQL programs by creating Java programs with the
.sqlj extension. SQLJ programs embed SQL statements among Java statements.
A #sql token in the beginning of a statement identifies an SQLJ statement. The
SQLJ translator precompiles .sqlj files into .java files and then automatically calls
the Java compiler to produce the .class files. When the program runs, it
automatically invokes SQLJ run-time components that call JDBC drivers or call
native database operations.
6.1.3.1 SQLJ and JDBC Comparison
SQLJ contains static SQL statements; JDBC supports dynamic SQL statements.
In a dynamic SQL model, an application may change any SQL statement during
run time, hence it is more flexible. Nevertheless, dynamic SQL statements require
run-time compilation, which may catch some run time errors. SQLJ pre-compiles
SQL statements before the program executes. It enforces strong type checking
between Java data types and SQL data types. The pre-compiled static
340
WebSphere Application Servers: Standard and Advanced Editions
statements will ensure all SQL statements are verified against database and will
run. Thus, it will reduce application maintenance costs.
SQLJ syntax is more concise than JDBC. SQLJ can embed Java variables into
SQL statements. JDBC requires separate statements to bind variables using their
position or column name. Developers will find it more convenient to use SQLJ
statements. Therefore, it may reduce the development costs.
SQLJ binds static statements into a database. The bind process provides
privilege and authorization checking. SQLJ separates the package owner from
the package runner, providing better data manageability. JDBC programs can’t
check user privileges until run time.
Most applications require more static statements than dynamic statements. Yet,
to exploit JDBC dynamic SQL features, you can combine SQLJ and JDBC
together inside one program. Since SQLJ includes JDBC support, the program
can create a JDBC connection and use the connection for JDBC dynamic SQL
statements, and use the same connection to set a connection context for SQLJ
static SQL statements.
6.1.3.2 SQLJ Statement Construct
SQLJ programs embed SQL statements among Java statements. SQLJ
statements are not Java statements. To identify SQL statements inside a
program, SQLJ statements always begin with #sql. In the pre-compilation, the
SQLJ translator will convert each statement that starts with #sql into
corresponding Java statements.
The syntax of SQLJ statement is:
#sql <sqlj-clauses>;
The semicolon (;) ends the SQLJ statement.
There are two SQLJ statement main constructs: SQLJ declarations and
executable statements.
SQLJ Declaration
SQLJ implementations use several Java classes. In developing SQLJ programs,
you do not write these classes using Java statements directly. Instead SQLJ
allows you to write a concise description of the classes using an SQLJ
declaration clause. Since a declaration represents a class, the rules for placing a
declaration is the same as those of Java classes.
Now there are only two types of SQLJ classes: the connection context classes
and the iterator classes. The syntax of a connection context declaration is:
#sql <modifier> context <context_class_name>
implements <interface_class>
with (var1=val1,..);
where <modifier> can be any Java class modifier, such as abstract, final, and
public. The implements clause is optional and is used to derive some interfaces
from interface classes. The with clause is optional and is used to initialize
variables with constants.
The syntax of iterator declaration is:
Enterprise Access
341
#sql <modifier> iterator <iterator_class_name>
implements <interface_class>
with (var1=val1,..)
(<type_declaration>);
where <type_declaration> contains class parameter type declaration.
SQLJ Executable Statement
An SQLJ executable statement represents a block of Java statements. The
embedded SQL statement will be translated into a block of corresponding Java
statements that perform the actual database calls. In the executable statement,
embedded SQL is enclosed with curly brackets. Depending on the SQL
statement, an executable statement may or may not return rows of records. An
assignment clause has a result expression for returning the result set. The syntax
of the executable statements is either in the form of a statement clause:
#sql [<context>] { <embedded-sql-statements> };
which returns no result, or in the form of an assignment clause:
#sql [<context>] <result> = { <embedded-sql-statements> };
which has the <result> variable to hold the resulting rows or operation counts.
The <context> is optional and specifies either a connection context or an
execution context.
Java Host Variable and Host Expression
SQLJ allows Java variables to be included inside SQLJ statements. Such
variables are known as host variables. You can also create Java expressions
using Host Variables inside SQLJ statements, to form Java host expressions.
A host variable or a host expression begins with a colon (:). The syntax for a Java
host expression is:
:<mode><a-java-variable>
or
:<mode>(<a-java-expression>)
where <mode> is optional and can be IN, OUT or INOUT (default).
SQLJ Context
An SQLJ context holds the state information for processing and retrieving the
result of SQL statements. There are two types of SQLJ contexts: the connection
context and the execution context.
1. A connection context represents a session into a database. One program may
access several databases by using multiple connection contexts. You can use
a connection context to perform SQL operations on the corresponding
database session. To create a connection context, you should create a new
connection context class by using the SQLJ connection context declaration.
Then, you create a new instance of the created class.
2. An execution context represents an instance of the SQLJ run-time component.
By specifying execution contexts, you can use multiple threads, with each
execution context using a thread; or you can use different SQL execution flows
with separate status information for each execution context. Each connection
context has its own default. Therefore, you do not need to specify the
342
WebSphere Application Servers: Standard and Advanced Editions
execution context for newly created connections. To create a new execution
context, you create a new instance of the sqlj.runtime.ExecutionContext class.
Then, you can combine this execution context with any connection context in
the <context> clause of SQLJ executable statements.
Result Set Iterator
The Result Set Iterator is the cursor equivalent in SQLJ. To retrieve resulting rows
from a query, use a result set iterator object. To create an iterator, create the
iterator class using the iterator declaration statement, then declare an object of
the class. Use this object to hold the result of the SQLJ assignment clause. This
operation, in effect, populates the iterator with the resulting rows from the query.
You can then retrieve column values from the iterator object.
To access a column in a row, SQLJ allows an iterator to specify columns by data
type or by the name and data type. Based on this criteria, SQLJ differentiates two
types of iterator:
1. Positioned Iterator. This iterator specifies a column by its relative position in
the query and its data type. To retrieve a row, use the FETCH executable
statement with the iterator as the cursor. The INTO clause in the FETCH
statement retrieves column values into Java host variables. The column
position in the INTO is the same as what is defined in the iterator declaration.
For example:
#sql public iterator PosIter (short, String, float);
...
class Staff{
...
public void getStaffInfo() {
...
short id;
String name = String("");
float salary;
PosIter staffCursor = null;
...
#sql staffCursor = { SELECT ID, NAME, SALARY FROM STAFF };
...
while (true) {
#sql FETCH :staffCursor INTO :id, :name, :salary;
if( staffCursor.endFetch() ) break;
System.out.println("Id:" + id
+ " name:" + name
+ " salary:" + salary);
}
...
staffCursor.close();
}
}
2. Named Interator. This iterator specifies a column by its name and its data
type. To retrieve the next row, use the next() method of iterator class. To
access a column in a row, use the corresponding accessor method. SQLJ
translator automatically adds an accessor method for each column into the
iterator class. The accessor method has the same name as the column name
and returns the same data type as the column data type. For example:
#sql public iterator NamedIter (short id, String name, float salary);
...
Enterprise Access
343
class Staff{
...
public void getStaffInfo() {
...
NamedIter staffCursor = null;
...
#sql staffCursor = { SELECT id, name, salary FROM STAFF };
...
while (staffCursor.next()) {
System.out.println("Id:" + staffCursor.id()
+ " name:" + staffCursor.name()
+ " salary:" + staffCursor.salary());
}
...
staffCursor.close();
}
}
6.1.3.3 Compiling SQLJ Programs
SQLJ defines a static SQL model, which precompiles embedded SQL statements
inside Java programs. The SQLJ translators perform the precompilation. It
translates embedded SQL statements in an .sqlj file into the corresponding Java
statements in a .java file. The translator is database vendor dependent. Typically
the translator can be called from the system’s command line by using the sqlj
command:
sqlj <filename>.sqlj
This will generate the corresponding java file that has the same file name but with
.java extension: filename.java. Then, this Java file can be compiled using Java’s
javac compiler to produce the class file.
6.1.3.4 SQLJ Profiles and Customization
The SQLJ translator also generates SQLJ profiles for each connection context
class. The profile contains information about embedded statement operations. It
is useful for separating vendor-specific operations from generic operations. The
customization process uses the SQLJ profile for creating a class to support
vendor-specific operations.
You can perform another customization for the same application in another
database platform by using the same SQLJ profile. The customization never
removes SQLJ profile entries; it adds or modifies only entries for the
corresponding platform. Using this mechanism SQLJ programs retain binary
compatibility across the database vendor even when you use vendor-specific
operations.
The database vendor may include customization process as an option in the sqlj
program. Alternatively, the vendor may provide a separate Java program by
extending the sqlj.runtime.profile.util.DataCustomizer class.
The translator writes the profiles into serialized objects, which can be put in the
same application package. The name of profile file is in the following format:
<filename>_SJProfile<n>.ser
344
WebSphere Application Servers: Standard and Advanced Editions
where n is 0,1,2, and so on, depending on how many connection contexts are in
the program. For example, if the file name is CustomerBean and the bean has
three connection contexts, the profile file name is CustomerBean_SJProfile0.ser,
CustomerBean_SJProfile1.ser and CustomerBean_SJProfile2.ser.
Some of the browsers (such as Netscape 4.x) don’t support serialized objects. To
enable such browsers, the customization process can generate .class file from
the .ser file. The class file name usually follows the serialized object file name,
replacing the .ser file extension with .class.
6.1.3.5 SQLJ JDBC Interoperability
In some cases, a Java program may require both static and dynamic SQL
statements. The program should contain both SQLJ and JDBC statements. To do
this, SQLJ provides some JDBC support that performs conversion between a
connection context and a connection, and between an iterator and a result set.
Using this mechanism, the JDBC connection and the corresponding SQLJ
connection context will refer to the same database session.
• To convert an SQLJ connection context into a JDBC connection, use the
getConnection method of the connection context class:
Connection jdbcConn = sqljContext.getConnection();
• To convert a JDBC connection into an SQLJ connection context, use a
connection context constructor that takes a JDBC connection as its input
parameter and returns the corresponding SQLJ connection context:
#sql context SQLJContext;
SQLJContext sqljContext = new SQLJContext(jdbcConn);
• To convert an SQLJ iterator into a JDBC result set, use the getResultSet
method of iterator class to return a JDBC result set:
SQLJIterator sqljIterator;
ResultSet jdbcResultSet = sqljIterator.getResultSet();
• To convert a JDBC result set into an SQLJ iterator, use a CAST executable
statement to populate a named or positional iterator object by result set data:
ResultSet jdbcResultSet;
...
jdbcResultSet = jdbcStatement.executeQuery("SELECT * FROM EMPLOYEE);
...
SQLJIterator sqljIterator;
#sql sqljIterator = { CAST :jdbcResultSet };
...
6.1.4 Using SQLJ in Java Programs
The SQLJ class libraries are available in an sqlj.runtime package from your
database vendor. Some SQLJ implementations require JDBC support as well.
Therefore, the program needs to import the JDBC support package.
6.1.4.1 Application Flow
In general, the format of SQLJ programs require the following:
• Import SQLJ run-time classes and JDBC support classes that are required by
SQLJ. Put the following lines in the beginning of your program:
import sqlj.runtime.*; // SQLJ support package
import java.sql.*; // For JDBC support
Enterprise Access
345
• Create a connection to the database. If your SQLJ implementation runs on top
of a JDBC driver, you should create a JDBC connection first. This connection
will be used for creating the SQLJ connection context. For example, suppose
you use the DB2 JDBC Type 2 driver to create a session to the SAMPLE
database:
...
Class.forName("COM.ibm.db2.jdbc.app.DB2Driver");
...
Connection conn = DriverManager.getConnection("jdbc:db2:SAMPLE");
conn.setAutoCommit(false); // disable JDBC Auto-Commit mode
• Create an SQLJ connection context class by adding a connection declaration
clause:
#sql context ConnContext
• Create a connection context object by using an existing JDBC connection:
ConnContext ctx = new ConnContext(conn);
Or, alternatively, if you do not create a JDBC connection, you can specify the
connection URL directly:
ConnContext ctx = new ConnContext("jdbc:db2:SAMPLE",false);
• Create iterator class to hold the result set:
#sql iterator PosIter (String, String, float);
• Create executable statements. Populate iterator objects with resulting query
results:
...
PosIter staffCursor;
...
#sql [ctx] staffCursor = { SELECT empno, firstnme, salary FROM EMPLOYEE
};
...
while (true) {
#sql FETCH :staffCursor INTO :empno, :firstName, :salary;
if( staffCursor.endFetch() ) break;
System.out.println("Employee Number:" + empno
+ " First Name:" + firstName
+ " Salary:" + salary);
}
...
• Retrieve column values using iterator accessor methods or FETCH
statements:
...
while (true) {
#sql FETCH :staffCursor INTO :empno, :firstName, :salary;
if( staffCursor.endFetch() ) break;
System.out.println("Employee Number:" + empno
+ " First Name:" + firstName
+ " Salary:" + salary);
}
...
• After the program finishes processing the query, close the iterator objects to
release valuable database resources:
ctx.close();
346
WebSphere Application Servers: Standard and Advanced Editions
6.1.4.2 Example: ReservationSQL
The following Java class illustrates the concepts we have discussed so far. The
ReservationSQL is a utility class for database operations on a reservation table. It
encapsulates database operations on the tsup_reservation table.
By default, the class static initializer reads file properties/connection.properties
for the driver name. The file must contain a line that specifies the driver name. For
example:
...
sqlj.driver = COM.ibm.db2.jdbc.app.DB2Driver
...
This connection.properties file can also contain JDBC and SQLJ parameters. In
the WebSphere Application Server environment, you should put this file as:
<ASROOT>/properties/connection.properties.
The class provide three forms of open methods:
• open(), which does the actual connection creation.
• open(String url, String user, String password) sets connection parameters and
calls open().
• open(String propertyFileName). To enable easy configuration, this class can
read connection parameters from a property file. The file should contain
property entries for a URL connection, database user ID and password. For
example, a property file might look like the following:
#
# Sample property file for SQLJC ..
#
sqlj.url = jdbc:db2:@SAMPLE1
sqlj.user = db2inst1
sqlj.password = SWA109R
The following lines of codes illustrate the usage of this class:
...
ReservationSQL reservation = new ReservationSQL();
reservation.open("properties/connection.properties");
ResultSet rs = reservation.queryAll();
while(rs.next()) {
System.out.println("Agent Id: " + rs.getString(1)
+ " Ref Id: " + rs.getInt(2)
+ " Package Name: " + rs.getString(3));
}
...
Later in this chapter, we use this class in Oracle platforms.
Enterprise Access
347
package com.ibm.redbook.sg245460;
import
import
import
import
java.sql.*;
oracle.sqlj.runtime.Oracle;
java.io.*;
java.util.*;
#sql context ConnContext;
#sql iterator ReservIter(String, int, String);
public class ReservationSQL {
private
private
private
private
static
String
String
String
String driverName = "COM.ibm.db2.jdbc.app.DB2Driver";
urlString = "jdbc:db2:SAMPLE";
dbUser = "tsup1";
dbPassword = "SWA109R";
private Connection jdbcConn;
private ConnContext sqljConn;
private ResultSet
rs;
static {
try {
Properties p = new Properties();
p.load(new FileInputStream("properties/connection.properties"));
driverName = p.getProperty("sqlj.driver");
Class.forName(driverName);
} catch(IOException e) {
e.printStackTrace();
} catch(ClassNotFoundException e) {
e.printStackTrace();
}
}
public int open() {
int rc=0;
try {
jdbcConn = DriverManager.getConnection(urlString,dbUser,dbPassword);
jdbcConn.setAutoCommit(false);
sqljConn = new ConnContext(jdbcConn);
} catch (SQLException e) {
e.printStackTrace();
rc = e.getErrorCode();
}
return -rc;
}
public int open(String propertyFileName) {
try {
Properties p = new Properties();
p.load(new FileInputStream(propertyFileName));
urlString = p.getProperty("sqlj.url");
dbUser = p.getProperty("sqlj.user");
dbPassword = p.getProperty("sqlj.password");
} catch (IOException e) {
e.printStackTrace();
}
return open();
}
public int open(String url, String user, String password) {
urlString = url;
dbUser = user;
dbPassword = password;
return open();
}
Figure 342. SQLJ Example: ReservationSQL.sqlj (1/2)
348
WebSphere Application Servers: Standard and Advanced Editions
public int create(String agentId, int refId, String packageId)
{
int rc = 0;
try {
#sql [sqljConn] { INSERT INTO tsup_reservation
VALUES (:agentId,:refId,:packageId)};
#sql [sqljConn] { COMMIT };
} catch(SQLException e) {
e.printStackTrace();
rc = e.getErrorCode();
}
return -rc;
}
public ResultSet queryAll() {
rs = null;
try {
ReservIter reservCursor;
#sql [sqljConn] reservCursor = { SELECT agent_id, ref_id, package_id
FROM tsup_reservation };
rs = reservCursor.getResultSet();
} catch(SQLException e) {
e.printStackTrace();
}
return rs;
}
public int delete(String agentId, int refId) {
int rc=0;
try {
#sql [sqljConn] { DELETE FROM tsup_reservation
WHERE agent_id = :agentId
AND ref_id = :refId };
#sql [sqljConn] { COMMIT };
} catch (SQLException e) {
e.printStackTrace();
rc = -e.getErrorCode();
}
return rc;
}
public void close() {
try {
sqljConn.close();
jdbcConn.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
Figure 343. SQLJ Example: ReservationSQL.sqlj (2/2)
6.2 Using DB2 UDB for WebSphere Applications
WebSphere applications use Java language as the underlying language. To
perform database access, the applications require a Java interface to the
database. DB2 provides Java support for accessing the database using Java
language. DB2 has delivered JDBC drivers and SQLJ support in its product for
OS/2, Windows NT, AIX, Solaris, HP/UX, SCO-UNIX, Linux, OS/400 and OS/390
platforms. Although our focus is on Windows NT and AIX Java support, the
techniques discussed in this section should also apply to other platforms.
A Java program can access DB2 databases in various ways. In any case, the
Java program acts as a client to the DB2 Server component. The program uses
the DB2 Client component to interface with the DB2 Server.
You can install the DB2 Server in the same machine as the WebSphere
Application Server. However, as the server, the DB2 Server normally resides in
Enterprise Access
349
the data server. In typical enterprise environments, the Web server (application
server) and the data server are located on different machines. Otherwise, the
Web server might overload data server performance. In such cases, you will need
a DB2 Client component on the Web server machine and a remote connection
between the DB2 Server and the DB2 Client component. To set up a remote DB2
connection, follow the steps described in 2.1.7.3, “Configuring Remote Interface”
on page 55.
6.2.1 DB2 Java Support
For Windows NT and AIX, DB2 Java support is available in DB2 UDB, CAE and
SDK. The minimum requirements for Java support are DB2 UDB Version 5.0 and
IBM JDK 1.1.6. To use JDBC and SQLJ, you need to set up your DB2
environment properly. Follow the steps described in 2.1.7.2, “Setting Up DB2 in
WebSphere Environment” on page 53.
6.2.1.1 DB2 JDBC Drivers
DB2 JDBC main usages are for executing dynamic SQL statements and for
supporting upper data layers such as SQLJ and IBM DataAccess beans.
DB2 provides two JDBC drivers: a native API Type 2 driver and a net protocol
Type 3 driver. In DB2 UDB 5.2, DB2 delivers a set of JDBC 1.1 drivers and
another set of JDBC 2.0 drivers. The Java class libraries are in db2java.zip. The
native API library is in db2java.dll (NT) or libdb2java.so (AIX).
• The native API driver is for server-side applications that run on the application
server. The driver consists of Java parts and a C native API interface (DB2
CLI). The driver translates JDBC calls into DB2 CLI calls. It then gives the
calls to the DB2 Client component, which passes them to the DB2 Server.
After that, the driver returns the result back to the application. The class name
for this JDBC driver is COM.ibm.db2.jdbc.app.DB2Driver, which is in
db2java.zip.
• The net protocol driver is for creating an application using the Java applet
model. The driver is a 100% Java program that is downloaded along with the
applet to the client browser. The driver exchanges messages, by using the
TCP socket protocol, to a JDBC Applet Server in the application server
machine. The JDBC Applet Server translates applet messages into DB2 CLI
calls. It sends the calls into the DB2 Client component, which passes them to
the DB2 Server. Then, the JDBC Applet Server passes the results back to the
applet. The class name for this JDBC driver is
COM.ibm.db2.jdbc.net.DB2Driver, which is in db2java.zip.
The JDBC Applet Server is a stand-alone socket server application. To activate
the JDBC Applet Server, enter the following command:
db2jstrt <port>
This will activate the JDBC Applet Server listening on port <port>.
Connection URL Syntax
To open a database connection, the program should supply a connection URL,
database owner, logon user ID and password. A DB2 JDBC connection URL has
the following formats:
• Using DB2 native API driver:
350
WebSphere Application Servers: Standard and Advanced Editions
"jdbc:db2:<database_name>"
• Using DB2 net protocol driver:
"jdbc:db2://<jdbc_applet_server_hostname>:<port>/<database_name>"
For example, to open a connection to the SAMPLE database using the DB2
native API driver, the connection URL is:
String urlString = "jdbc:db2:SAMPLE";
Or using the DB2 net protocol driver with JDBC Applet Server listening on
mylocal.host.com port 9090, the connection URL would be:
String urlString = "jdbc:db2://mylocal.host.com:9090/SAMPLE";
Other information can be supplied as Java properties to the
DriverManager.getConnection method. For example, to open a connection using
the sDB2 native API to the SAMPLE database owned by db2inst1, log on as user
"auser", with password "letmein":
Properties infoProp = new Properties;
infoProp.set("owner","db2inst1");
infoProp.set("userid","auser");
infoProp.set("password","letmein");
Connection aConnection = DriverManager.getConnection(urlString,infoProp);
For accessing a database in a remote data server, DB2 Client maps the given
database name <database_name> into a remote database, using its remote
interface configuration. To do this, you should configure a remote interface as
explained in 2.1.7.3, “Configuring Remote Interface” on page 55. Alternatively,
you can supply the data server host name and port number directly to the
connection URL:
"jdbc:db2://data_server_name:data_server_port/<database_name>"
For example, to access the SAMPLE database on remote.host.com using port
9090, the connection URL becomes:
String urlString = "jdbc:db2://remote.host.com:9090/SAMPLE"
Note that the syntax for the native API JDBC driver accessing a remote database
is the same as the net protocol JDBC driver syntax.
6.2.1.2 DB2 SQLJ Support
DB2 SQLJ main usage is for static SQL execution and Java stored procedures.
You can use SQLJ in a client-side Java applet or a server-side Java application.
DB2 delivers SQLJ support that complies with the ANSI X.3.135 standard. DB2
SQLJ runs on top of DB2 JDBC drivers. It provides SQLJ Java classes, translator,
run-time, and customization tools. The DB2 SQLJ Java libraries are in sqlj.zip and
runtime.zip.
The SQLJ translator will precompile SQLJ file into a Java program. To use the
translator, make sure that sqlj.zip and runtime.zip are in your system classpath,
then call sqlj program from the command line:
sqlj <filename>.sqlj
Enterprise Access
351
This will create a Java program with the same name, <filename>.java and
serialized SQLJ profiles <filename>_SJProfilen.ser (n=0,1,2,..., for each
connection context) for customization purposes.
DB2 SQLJ provides a batch file, embprep, to customize SQLJ profiles. The batch
file calls a Java application, sqlj.runtime.profile.util.DataCustomizer using
user-supplied parameters. To use the customizer, call embprep from the
command line:
embprep <filename> <database_name> <userid> <password> ...
This will create a customization class, <filename>_SJProfileKey.class, which
contains information about operations performed by embedded statements.
Practically, the embprep will bind the program into the database. The SQLJ
profiles contains the binding information. The embprep also verifies:
• SQL consistency against database schema
• User privilege for using database resources
Note that the binding process requires DB2 SQLJ programs file name <filename>
which should be fewer than eight characters.
To run embprep, you should have privileges to perform all operations in
embedded statements. Figure 344 summarizes the steps for compiling SQLJ
programs.
<filename>.sqlj
sqlj
<filename>.java
SQLJ Profiles
<filename>_SJProfilen.ser
javac
class files
embprep
DB/2
Customized Profile
<filename>_SJProfilen.ser
<filename>_SJProfileKeys.class
5460\546002
Figure 344. Preparing Programs Written in SQLJ Language
352
WebSphere Application Servers: Standard and Advanced Editions
6.2.2 Setting Up DB2 Java Support for the WebSphere Environment
The only requirement for using Oracle Java support in the WebSphere
environment is to set up the Java path information in the WebSphere Java Engine
setup.
6.2.2.1 Setting Up System CLASSPATH Variable
Setting Java library paths into system environment variables may be useful for
developing and debugging purposes. Add the following path into the CLASSPATH
variable:
<INSTHOME>/sqllib/java/db2java.zip
<INSTHOME>/sqllib/java/sqlj.zip
<INSTHOME>/sqllib/java/runtime.zip
where <INSTHOME> is your DB2 instance directory.
6.2.2.2 Setting Up WebSphere CLASSPATH and User LibPath
In the WebSphere Administration, you should also include Java paths in the
Application Server classpath and the user libpath.
• Log on to WebSphere Administration Tool using the administrator user ID.
• Select Setup > Java Engine to bring up the Java Engine setup form.
• On the Path tab, add the following Application Server Classpath entry field:
<INSTHOME>/sqllib/java/db2java.zip
<INSTHOME>/sqllib/java/sqlj.zip
<INSTHOME>/sqllib/java/runtime.zip
• You should also add application SQLJ profiles to the Application Server
Classpath entry field, so that they can be found by the SQLJ run-time
component.
• For the Windows NT platform, add <INSTHOME>\sqllib\bin in the user libpath
entry field. For the AIX platform, add <INSTHOME>/sqllib/lib in the user
libpath.
After changing this path information, restart both the Web server and
WebSphere. In AIX, you may have to kill the WebSphere processes before
restarting the Web server.
6.2.3 DB2 Java Examples
In this section, we give two examples of using DB2 Java support in the
WebSphere environment. These examples are deployed as Java Beans.
6.2.3.1 The XtremeTravel Inc.
We will develop our DB2 Java examples based on the XtremeTravel example,
which comes with WebSphere Application Server 2.0. We will add the following
functions in the original XtremeTravel:
• Customer registration
• Customer logon
Enterprise Access
353
6.2.3.2 DB2, JDBC, and SQLJ Example: CustBean.sqlj
The following example is a data bean. It contains both JDBC and SQLJ
statements in one program. The SQLJ statements make use of the JDBC
connection as SQLJ connection context.
The SQLJ static INSERT statement inserts customer registration data into a
customer table. The program uses the JDBCAccess utility class to create a
connection and perform a query. A query on the customer table does the logon
verification by checking the customer table for a particular user ID and password
combination.
The bean uses a property file, which is <ASROOT>
properties/connection.properties, to set up the JDBC connection property.
# WebSphere Application Server
# IBM Redbook SG245460
#
# Sample property file for JDBC and SQLJ
#
#Wed May 12 17:36:02 EDT 1999
jdbc.driver = COM.ibm.db2.jdbc.app.DB2Driver
jdbc.url = jdbc:db2:xtcust
jdbc.user = db2inst1
jdbc.password = SWA109R
...
...
...
Figure 345. JDBC Connection Properties in connection.properties File
Figure 346 and Figure 347 show the code listing of CustBean.sqlj:
354
WebSphere Application Servers: Standard and Advanced Editions
package com.ibm.sg245460.xtreme;
import
import
import
import
import
import
java.util.*;
java.io.*;
java.sql.*;
sqlj.runtime.*;
sqlj.runtime.ref.*;
com.ibm.redbook.sg245460.*;
#sql context ConnContext;
public class CustBean extends java.lang.Object implements java.io.Serializable {
protected
protected
protected
protected
protected
protected
protected
protected
protected
protected
protected
protected
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
int
String
String
String
String
String
String
String
String
String
String
String
custNo = 0;
title = null;
firstName = null;
lastName = null;
addrLine1 = null;
addrLine2 = null;
city = null;
state = null;
zip = null;
country = null;
userId = null;
password = null;
String getTitle() { return title; }
void setTitle(String value) { this.title = value; }
String getFirstName() { return firstName; }
void setFirstName(String value) { this.firstName = value; }
String getLastName() { return lastName; }
void setLastName(String value) { this.lastName = value; }
String getAddrLine1() { return addrLine1; }
void setAddrLine1(String value) { this.addrLine1 = value; }
String getAddrLine2() { return addrLine2; }
void setAddrLine2(String value) { this.addrLine2 = value; }
String getCity() { return city; }
void setCity(String value) { this.city = value; }
String getState() { return state; }
void setState(String value) { this.state = value; }
String getZip() { return zip; }
void setZip(String value) { this.zip = value; }
String getCountry() { return country; }
void setCountry(String value) { this.country = value; }
public void setUserId(String value) { this.userId = value; }
public void setPassword(String value) { this.password = value; }
private
private
private
private
private
Connection jdbcConn = null;
PreparedStatement stmt = null;
ResultSet rs = null;
JDBCAccess jdbc = null;
ConnContext sqljConn = null;
public void connectDB() {
try {
jdbc = new JDBCAccess();
jdbcConn = jdbc.open("properties/connection.properties");
sqljConn = new ConnContext(jdbcConn);
} catch(SQLException e) {
e.printStackTrace();
}
Figure 346. DB2, JDBC, and SQLJ Example: CustBean.sqlj (1/2)
Enterprise Access
355
public void registerCust() {
try {
#sql [sqljConn] { SELECT MAX(cust_no) INTO :custNo FROM customer };
custNo++;
#sql [sqljConn] { INSERT INTO customer (cust_no,title,first_name,last_name,
addr_line1,addr_line2,city,state,zip,country,
userid, password)
VALUES(:custNo,:title,:firstName,:lastName,
:addrLine1,:addrLine2,:city,:state,:zip,:country,
:userId,:password) };
#sql [sqljConn] { COMMIT };
} catch(SQLException e) {
e.printStackTrace();
}
}
public int logon() {
int rc = 0;
try {
String qSql = "SELECT cust_no FROM customer ";
qSql += "WHERE userid = '" + userId + "' AND password = '" + password + "'";
rs = jdbc.query(qSql);
if(rs.next()) rc = 0;
else rc = -1;
} catch (SQLException e) {
e.printStackTrace();
}
return rc;
}
public void closeDB() {
jdbc.close();
}
Figure 347. DB2 JDBC and SQLJ Example: CustBean.sqlj (2/2)
6.3 Using Oracle for WebSphere Applications
As Java is becoming a universal computing platform, Oracle is integrating Java
support in its products. Oracle comes with the Oracle 8i RDBMS server, the
JServer and the JDeveloper. Unlike other Oracle database products, the Oracle 8i
integrates Java support inside its database server. The JServer is the Oracle
Java engine that is fully integrated into Oracle 8i. Oracle also provides
JDeveloper for developing Java database applications. These Oracle products
allow you to implement EJB, CORBA, and general Web applications. For more
information about Oracle Java technology, see http://www.oracle.com.
6.3.1 Oracle Java Support
The JServer includes a JVM, JDBC drivers, SQLJ support, an EJB server, JSP
and CORBA support. The JVM, which is also known as the Aurora JVM, complies
with JDK 1.1.6 specifications. The JVM and other Java support components run
within the same address space as the database server. Oracle JDBC Server,
SQLJ run time, and EJB Server run on top of the JVM within the database server
address space. This mechanism ensures optimum performance for Java
database operations.
6.3.1.1 Oracle JDBC Drivers
Oracle provides three JDBC drivers: JDBC OCI driver, JDBC Server driver, and
JDBC Thin drivers. In Oracle 8i Version 8.1, all drivers comply with the JDBC 1.22
specifications. The JDBC OCI and JDBC Thin drivers are also available in
356
WebSphere Application Servers: Standard and Advanced Editions
previous Oracle database server products. The class name for all JDBC driver
types is oracle.jdbc.driver.OracleDriver. Oracle JDBC support libraries are in
<ORACLE_HOME>/jdbc/lib/classes111.zip.
The Oracle JDBC OCI driver is a client-side native API driver. It is intended for
Java applications or Java programs on an application server. The driver is written
in Java and C. It uses C calls to Oracle Call Interface (OCI), which is the native
API for accessing the Oracle database.
The Oracle JDBC Server driver is a server-side native API driver. It is intended for
Java programs that run inside Oracle JVM. This driver uses the same address
space as the database engine.
The Oracle JDBC Thin driver is a native protocol JDBC driver. It enables Java
applets to access the Oracle database. It is a 100% Java program. In the Java
applet model, the driver is downloaded along with the applet to the client Web
browser. When the applet starts, the driver creates a connection to the database
server by using the TCP socket protocol. The interaction between the driver and
the server uses the Oracle Net8 protocol as the native protocol. Unlike the
stateless HTTP protocol, the Thin driver connection is stateful. The Oracle server
manages these connections and their states.
Connection URL Syntax
To open a connection to a database, the program should supply a connection
URL, logon user ID and a password. For Oracle JDBC OCI and JDBC Server
drivers, the URL format is:
"jdbc:oracle:oci8:@<database_name>"
For the Oracle Thin driver, the URL format is:
"jdbc:oracle:thin:@<listener_hostname>:<listener_port>:<database_name>"
For example, the URL string for opening a connection to the SAMPLE database,
which has the system identifier sam, using JDBC OCI or JDBC Server driver, is
the following:
String urlString = "jdbc:oracle:oci8:@SAMPLE";
Or if you use the JDBC Thin driver with the TCP listener on mylocal.host.com port
9090, the URL string is:
String urlString = "jdbc:oracle:thin:@mylocal.host.com:9090:SAMPLE";
To open a connection, the program should also supply the logon user ID and
password. For example, using user ID "scott" with password "tiger":
Connection aConnection =
DriverManager.getConnection(urlString,"scott","tiger");
For accessing a database in a remote data server, you can specify the database
location by the Net8 name-value pair:
(description=(address=(host=<hostname>)(protocol=tcp)(port=<port>))(connect_da
ta=(sid=<sid>)))
where <sid> is database System Identifier (SID).
Enterprise Access
357
For example, to connect to the SAMPLE database which has the SID "sam" in a
remote data server, remote.host.com, that listens on port 9090, use the following:
String urlString = "jdbc:oracle:oci8:@
(description=(address=(host=remote.host.com)(protocol=tcp)(port=9090))
(connect_data=(sid=sam)))"
6.3.1.2 Oracle SQLJ Support
Oracle also delivers ANSI X3.135 SQLJ supports. Oracle SQLJ runs on top of
any Oracle JDBC driver type. The Oracle SQLJ is the Java equivalent of the
Oracle Pro*C embedded SQL environment. It enables developers to create
precompiled static SQL statements and Java stored procedures.
Oracle SQLJ support provides SQLJ Java classes, translator, run time, and
customization tools. To precompile SQLJ programs using the command line, you
should include the Java library path into session CLASSPATH (see 6.3.2.1,
“Setting Up System CLASSPATH Variable” on page 359).
To precompile the SQLJ translator:
sqlj <filename.sqlj>
This will generate a Java source program, filename.java, and SQLJ profiles for
each connection context in the program. It will also automatically call Java
compiler to create Java class files.
6.3.1.3 Oracle Java Stored Procedures
An Oracle Java stored procedure is the PL/SQL equivalent in the Java language.
The Java stored procedures are Java programs that are stored in the database,
similar to PL/SQL stored procedures. A Java stored procedure uses JDBC or
SQLJ to access the database. It has a call specification that is also kept in the
database. A PL/SQL program can call a Java procedure by using its call
specification. The called Java procedure will be loaded and executed in the
Oracle JVM. On the other hand, a Java stored procedure can call a PL/SQL
procedure by using a JDBC callable statement. Similarly, other Java programs
can also call a Java stored procedure by using a JDBC callable statement.
6.3.1.4 Oracle EJB Server
Oracle has its own EJB Server, which complies with EJB 1.0 specification. Now,
Oracle 8i EJB Server does not support entity beans, which is not mandatory in
the EJB 1.0 specification. It supports only session beans. A session bean is
inherently non-persistent and does not represent business data. Therefore, if
persistence is required, a session bean should store its state in the database or
access persistent data directly in the database by using JDBC, SQLJ or Java
stored procedures.
6.3.1.5 Oracle CORBA Support
As a good alternative, Jserver allows you to use CORBA applications to access
the Oracle database. Jserver provides Java classes to build Java CORBA objects
and runs them in the database server. Since CORBA has its own set of services,
Jserver provides interfaces to bridge Java services or database services into
CORBA services, such as:
• Interface from Java Transaction Service (JTS) to CORBA Transaction Service
358
WebSphere Application Servers: Standard and Advanced Editions
• JNDI interface into CORBA CosNaming services for storing and retrieving
objects to/from Oracle databases
6.3.2 Setting Up Oracle Java Support for the WebSphere Environment
The only requirement for using Oracle Java support in the WebSphere
environment is to set up Java path information in the WebSphere Java Engine
setup.
6.3.2.1 Setting Up System CLASSPATH Variable
Setting Java library paths into system environment variables may be useful for
developing and debugging purposes. Add the following path into the CLASSPATH
variable:
<ORACLE_HOME>/jdbc/lib/classes111.zip
<ORACLE_HOME>/sqlj/lib/translator.zip
<ORACLE_HOME>/sqlj/lib/runtime.zip
where <ORACLE_HOME> is your Oracle instance directory.
6.3.2.2 Setting Up WebSphere CLASSPATH and User LibPath
In the WebSphere Administration, you should also include Java paths into the
Application Server classpath and the user libpath.
• Log on to WebSphere Administration Tool using the administrator user ID.
• Select Setup > Java Engine to bring up the Java Engine setup form.
• On the Path tab, add the following Application Server Classpath entry field:
<ORACLE_HOME>/jdbc/lib/classes111.zip
<ORACLE_HOME>/sqlj/lib/translator.zip
<ORACLE_HOME>/sqlj/lib/runtime.zip
• You should also add application SQLJ profiles to the Application Server
Classpath entry field, so that they can be found by the SQLJ run-time
component.
• Add <ORACLE_HOME>/bin in the user libpath entry field.
After changing this path information, restart both the Web server and
WebSphere. In AIX, you may have to kill the WebSphere processes before
restarting the Web server.
6.3.3 Oracle Java Examples
In this section, we describe two examples of using Oracle Java support in the
WebSphere environment. These examples, one for JDBC and one for SQLJ, are
deployed as EJBs.
6.3.3.1 The TravelSupplier Inc.
For our example, assume that there is a fictitious travel company, The
TravelSupplier Inc., which supplies travel packages for other travel agencies or for
online travel sites, such as our XtremeTravel. The TravelSupplier Inc. has a
WebSphere Application server to provide travel data and reservation services for
external entities by using EJB. The company uses Oracle 8i Version 8.1.5 as its
enterprise database.
This company application on WebSphere delivers two services:
Enterprise Access
359
1. Retrieves a list of available travel packages. As the query will be dynamic by
nature, we use the JDBC technique to access the database.
2. Performs customer reservation. The reservation request comes from other
agencies such as XtremeTravel. In this case, a servlet in XtremeTravel calls
the reservation EJB in The TravelSupplier. As the transactions are the same
for all travel agencies, we use SQLJ to insert a reservation record into the
database.
As a matter of fact, the company has decided to concentrate on its core business,
as a wholesale supplier creating attractive travel packages. It does not have and
does not want to provide any Web site for individual customers to access.
Instead, it makes use of other online travel sites such as XtremeTravel to market
its travel packages.
6.3.3.2 Oracle JDBC Example: TravelPackageEJB
The TravelPackageEJB retrieves travel package records from the tsup_package
table in the SAMPLE1 database. To deploy this EJB, follow the instructions in
4.2.3, “Deploying an EJB” on page 192. The EJB can be called by an applet, a
servlet or other Java beans using the EJB calling mechanism (see 4.3, “Coding
WebSphere EJB Clients” on page 207).
Figure 349 shows the bean implementation for TravelPackageEJB. In this EJB,
we use the JDBCAccess class as described in 6.1.2.2, “Example: JDBCAccess
Utility Class” on page 337. The class will require a property file <ASROOT>
properties/connection.properties with the following contents:
# WebSphere Application Server
# IBM Redbook SG245460
#
# Sample property file for JDBC and SQLJ
#
#Wed May 12 17:36:02 EDT 1999
jdbc.driver = oracle.jdbc.driver.OracleDriver
jdbc.url = jdbc:oracle:oci8:@SAMPLE1
jdbc.user = tsup1
jdbc.password = SWA109R
...
... SQLJ parameters removed for clarity ...
...
Figure 348. JDBC Connection Properties in connection.properties File
360
WebSphere Application Servers: Standard and Advanced Editions
package com.ibm.redbook.sg245460.tsup;
import
import
import
import
import
import
import
import
java.rmi.RemoteException;
java.security.Identity;
java.util.Properties;
javax.ejb.*;
java.lang.*;
java.sql.*;
java.util.*;
com.ibm.redbook.sg245460.*;
public class TravelPackageEJBBean implements javax.ejb.SessionBean {
private javax.ejb.SessionContext mySessionCtx = null;
public Vector getPackage() {
Vector allPackage = null;
TravelPackage pkg = null;
ResultSet rs=null;
try {
allPackage = new Vector();
JDBCAccess jdbc = new JDBCAccess();
jdbc.open("properties/connection.properties");
rs = jdbc.query("SELECT package_id, package_name, destination, duration, price, start_date FROM tsup_package");
while(rs.next()) {
pkg = new TravelPackage();
pkg.setPackageId(rs.getString(1));
pkg.setPackageName(rs.getString(2));
pkg.setDestination(rs.getString(3));
pkg.setDuration(rs.getShort(4));
pkg.setPrice(rs.getFloat(5));
pkg.setStartDate(rs.getDate(6));
allPackage.addElement(pkg);
};
jdbc.close();
} catch (SQLException e) {
e.printStackTrace();
}
return allPackage;
} // end of getPackage
public void ejbActivate() throws java.rmi.RemoteException {
}
public void ejbCreate() {
}
public void ejbPassivate() throws java.rmi.RemoteException {
}
public void ejbRemove() throws java.rmi.RemoteException {
}
public void setSessionContext(javax.ejb.SessionContext ctx) throws java.rmi.RemoteException {
mySessionCtx = ctx;
}
}// end of TravelPackageEJBBean
Figure 349. Oracle JDBC: TravelPackageEJBBean Using JDBCAccess Utility Class
6.3.3.3 Oracle SQLJ Example: ReservationEJB
The ReservationEJB inserts a reservation record into the tsup_reservation table
in the SAMPLE1 database. To deploy this EJB, follow the instructions in 4.2.3,
“Deploying an EJB” on page 192. The EJB can be called by an applet, a servlet or
other Java beans using the EJB calling mechanism (see 4.3, “Coding WebSphere
EJB Clients” on page 207).
Enterprise Access
361
The ReservationEJB uses ReservationSQL.sqlj, as described in 6.1.4.2,
“Example: ReservationSQL” on page 347.
To configure SQLJ parameters, we use the same property file as used by
TravelPackageEJB. The property file is <ASROOT>
properties/connection.properties, with the following contents:
# WebSphere Application Server
# IBM Redbook SG245460
#
# Sample property file for JDBC and SQLJ
#
#Wed May 12 17:36:02 EDT 1999
...
... JDBC parameters removed for clarity ...
...
sqlj.driver = oracle.jdbc.driver.OracleDriver
sqlj.url = jdbc:oracle:oci8:@SAMPLE1
sqlj.user = tsup1
sqlj.password = SWA109R
Figure 350. SQLJ Connection Properties in connection.properties File
Figure 351 shows the bean implementation for ReservationEJB:
package com.ibm.redbook.sg245460.tsup;
import
import
import
import
import
import
java.rmi.RemoteException;
java.security.Identity;
java.util.Properties;
javax.ejb.*;
java.lang.*;
com.ibm.redbook.sg245460.*;
public class ReservationEJBBean implements javax.ejb.SessionBean {
private javax.ejb.SessionContext mySessionCtx = null;
public int createReservation(String agentId, int refId, String packageId) {
int rc=0;
ReservationSQL r;
r = new ReservationSQL();
rc = r.open("properties/connection.properties");
if( rc < 0 ) return rc;
rc = r.create(agentId,refId,packageId);
return rc;
}
public void ejbActivate() throws java.rmi.RemoteException {
}
public void ejbCreate() {
}
Figure 351. Oracle SQLJ Example: ReservationEJBBean
6.4 Using MQSeries for WebSphere Applications
IBM MQSeries is a message-oriented middleware that enables business
applications to exchange messages across various platforms. It provides an
easy- to-use common API, called Message Queue Interface (MQI), which
encapsulates all complexities in handling message integrity and security and
managing underlying communication protocol. The MQI ensures rapid application
integration across different platforms. MQSeries is available in all commercial
362
WebSphere Application Servers: Standard and Advanced Editions
operating systems. To find more information about IBM MQSeries, visit
http://www.software.ibm.com/ts/mqseries.
The best way to use MQSeries in the WebSphere Application Server environment
is by interfacing MQSeries with Java language. With this strategy, a Java program
can exchange messages with the back-end system using MQSeries. Indeed,
MQSeries has provided Java support in its MQSeries for Java component.This
extends the reach of MQSeries into the Internet. Typical usage of this component
in the WebSphere environment is in EJBs for encapsulating enterprise
transactions delivered via MQSeries.
In this section, we focus on implementing MQSeries applications with MQSeries
for Java. We start by providing a brief overview of MQSeries, before using it with
MQSeries for Java. For more information about developing application on
MQSeries, read MQSeries Application Programming Guide, SC33-0807 and
MQSeries using Java, SC34-5456. Both documents are also available as online
documentations from the MQSeries installation.
6.4.1 MQSeries Overview
MQSeries exchanges information in the form of messages. Applications put and
retrieve messages onto and from queues. A queue manager exists to manage
queue operations. Each queue manager owns a set of local queues. An
application sends a message by connecting to a queue manager and writing the
message into a remote queue. The queue manager is responsible for transferring
the message via channels to a remote queue manager that owns the remote
queue. A remote application retrieves the message from the remote queue. In
MQSeries, queue managers, queues, and channels are recoverable resources,
which are also known as MQSeries objects.
Messages
MQSeries messages consist of application data and message descriptors. The
application data format and application level protocol are defined by the
communicating parties. The message descriptor contains the message
identification, message type, priority, addressing information, and other control
information.
Queues
An MQSeries queue stores messages. A queue is owned by a queue manager. It
is implemented in main memory, disk or other auxiliary storage. It has the ability
to perform recovery in case of storage failure.
Queue Managers
An application that uses MQSeries facilities should connect to a queue manager,
which is also called the application local queue manager. A queue manager owns
a set of local queues. A local queue manager’s queue is also an application local
queue.
A remote queue manager is another application’s queue manager. A remote
queue is a remote queue manager’s queue. An application can put messages into
local queues or remote queues. An application can retrieve messages only from
local queues.
A queue manager has three types of local queues:
Enterprise Access
363
1. Transmission queues to store messages temporarily until they are transmitted
successfully to remote queues
2. A dead letter queue to store messages that can’t be delivered
3. Application queues to store received messages.
The queue manager keeps definitions for remote queues. This local definition will
represent the remote queue. Any operation placed into this definition will be
executed as an operation in the remote queue. Therefore, to write to a remote
queue, an application puts the message to the definition of the remote queue.
The queue manager will automatically transfer the message to the remote queue.
Channel
In MQSeries, a message channel is a communication path between two queue
managers. A message channel is a one-way link. Two-way communication needs
two message channels. At both ends of a channel, there is a Message Channel
Agent (MCA), which is a software component that handles the sending and
receiving of messages. Each channel has a sender channel definition and a
receiver channel definition. The two channel definitions have the same name.
Addressing Information
An application can exchange messages with another application in the same
queue manager. Both applications can access a local queue. In this case, the
addressing information is only the local queue name.
If an application sends messages to a remote queue, the application should
specify the local definition of the remote queue. MQSeries configuration maps
this definition into remote the queue manager, remote queue and transmission
queue. Any message put into this definition will be transferred to the remote
queue.
Application
A
PUT
Server A
Server B
Queue Manager
A
Queue Manager
B
M
Q
I
M
C
A
Definition Transmit
Queue
of
Remote
Queue
Dead Letter
Queue
CHANNEL
NETWORK
M
C
A
Application
B
M
Q
I
GET
Local
Application
Queue
Dead Letter
Queue
5460\546005
Figure 352. MQSeries Concept
364
WebSphere Application Servers: Standard and Advanced Editions
Message Queuing Interface (MQI)
MQI is a procedural API for accessing MQSeries facilities. MQI consists of a set
of procedures or functions, which are also known as calls. Table 32 lists
commonly used calls.
Table 32.
MQI Calls
Call Verb
Description
MQCONN
Connect an application to a queue manager
MQDISC
Disconnect an application from a queue manager
MQOPEN
Open an object, such as queue
MQCLOSE
Close an object
MQPUT
Put a message into queue
MQGET
Retrieve messages from queue
MQBEGIN
Start a global unit of work
MQCMIT
Commit changes and end a unit of work
MQBACK
Roll back changes and end a unit of work
6.4.2 MQSeries for Java
MQSeries for Java can deliver industrial-strength, message-oriented middleware
into an Internet/intranet environment. It consists of a set of Java classes and a
native class implementation library.
The minimum software level requirements to use MQSeries are JDK 1.1,
MQSeries Server 5.0 and MQSeries Client 2.0. You can obtain MQSeries for Java
from the MQSeries Server CD-ROM. You can also obtain MQSeries Client for
Java from MQSeries Client CD-ROM. When the installation program asks you to
choose MQSeries components, select MQSeries Client for Java (under MQSeries
Clients options) and MQSeries Bindings for Java.
In our examples, we use MQSeries Server for Windows NT 5.0, and MQSeries
Clients for Windows NT 2.0 and JDK 1.1.6.
6.4.2.1 Setting Up MQSeries for Java
For using MQSeries messaging facilities from the Java environment, you should
configure class paths and library paths both in the system environment and in the
WebSphere environment. After that, define and set up MQSeries objects that will
be used in the applications.
Setting Up System CLASSPATH and Library Path Variables
Placing Java library paths into system environment variables may be useful for
developing and debugging purposes. Add the following path into the CLASSPATH
variable:
<MQROOT>/java/lib
Add the following path into the library path variable:
<MQROOT>/java/lib
Enterprise Access
365
where <MQROOT> is the MQSeries root installation directory. For example, if you
install MQSeries under d:\mqm then the path will be d:\mqm\java\lib.
Setting Up WebSphere CLASSPATH and User LibPath
In the WebSphere Administration, you should also include this directory in the
application server classpath and user libpath.
• Log on to the WebSphere Administration Tool using the administrator user ID.
• Select Setup > Java Engine to bring up the Java Engine setup form.
• On the Path tab add <MQROOT>/java/lib to the application server classpath
entry field.
• Add <MQROOT>/java/lib to the user libpath entry field.
After changing this path information, restart both the Web server and
WebSphere. In AIX, you may have to kill the WebSphere processes before
restarting the Web server.
Setting Up Communications
MQSeries provides supports for TCP/IP, LU6.2, NetBIOS and SPX protocols.
Before configuring MQSeries, communication links should exist between the
server machines using one of the protocols. For TCP/IP, the configuration
requires host names and port numbers. Verify that the Domain Name Server
works properly and the port numbers are not used by other applications.
Configuring Queue Managers
You can configure MQSeries according to an application’s messaging
requirements. MQSeries provides two command sets for performing
administration tasks: the Control commands and the MQSC commands. In this
section, we use only some basic commands. You can see more commands and
their descriptions in the MQSeries Administration Manual, which is also available
in the MQSeries online documentation.
In our example, we will be connecting an EJB in the application server to a
back-end application in MQSeries server-to-server mode. Both the application
server machine and the back-end machine have their own MQSeries servers.
Table 33 on page 366 and Figure 353 summarize the configuration for both
servers:
Table 33. MQSeries Configuration at the Application Server and the Back-End System
Parameter
366
Application Server
Back-End Application
Hostname(port)
wsnt00(9101)
wtr05100(9102)
Queue Manager
bean.queue.manager
backend.queue.manager
Local Queue
BEAN.QUEUE
BACKEND.QUEUE
Remote Queue
Definition
DEF.OF.BACKEND.QUEUE
DEF.OF.BEAN.QUEUE
Transmission
Queue
BEAN.TRANSMIT.QUEUE
BACKEND.TRANSMIT.QUEUE
Channel (Sender)
BEAN.CHANNEL
BACKEND.CHANNEL
Channel (Receiver)
BACKEND.CHANNEL
BEAN.CHANNEL
WebSphere Application Servers: Standard and Advanced Editions
Enterprise Backend System
Application Server Machine
bean.queue.manager
DEF.OF.BACKEND.QUEUE
backend.queue.manager
BEAN.CHANNEL
BACKEND.QUEUE
BEAN.TRANSMIT.QUEUE
BACKEND.CHANNEL
BEAN.QUEUE
BACKEND.TRANSMIT.QUEUE
DEF.OF.BEAN.QUEUE
5460\546003
Figure 353. Connection between an Application Server and Back-End System
An MQSeries server contains several queue managers. To use MQSeries
messaging, applications must connect to a queue manager. You can create a new
queue manager or use the existing one. Before you configure a queue manager,
make sure that the queue manager is running.
For example, in the Application Server MQSeries:
• Create the queue manager by using crtmqm from the system console:
crtmqm bean.queue.manager
• Start the queue manager by using strmqm from the system console:
strmqm bean.queue.manager
• Configure the queue manager by using runmqsc from the system console:
runmqsc bean.queue.manager
This command will invoke a console for setting the queue manager parameter.
As the runmqsc has no prompt, issue the command at the next available line.
• Create the local queue by issuing the following command:
define qlocal(BEAN.QUEUE)
• Create the local queue for the transmission queue:
define qlocal(BEAN.TRANSMIT.QUEUE) usage(xmitq)
• Create a local definition of the remote queue. This local definition will
represent the remote queue. Any operation of this definition will be executed
as an operation in the remote queue. In this case the BACKEND.QUEUE is the
remote queue at the remote back-end queue manager. The message transfer
is done through the local transmission queue:
define qremote(DEF.OF.BACKEND.QUEUE) rname(BACKEND.QUEUE) +
rqmname(’backend.queue.manager’) xmitq(BEAN.TRANSMIT.QUEUE)
• Create a channel for sending messages using TCP/IP protocol to remote
machine wtr05100 on port 9102:
define channel(BEAN.CHANNEL) chltype(SDR) trptype(TCP) +
conname(’wtr05100(9102)’) xmitq(BEAN.TRANSMIT.QUEUE)
• Create a channel for receiving messages:
Enterprise Access
367
define channel(BACKEND.CHANNEL) chltype(RCVR) trptype(TCP)
• Exit from runmqsc session:
end
At the back-end MQSeries, do similar configuration steps:
• Create the queue manager by using crtmqm from the system console:
crtmqm backend.queue.manager
• Start the queue manager by using strmqm from the system console:
strmqm backend.queue.manager
• Configure the queue manager by using runmqsc from the system console:
runmqsc backend.queue.manager
• Create the local queue by issuing the following command:
define qlocal(BACKEND.QUEUE)
• Create the local queue for the transmission queue:
define qlocal(BACKEND.TRANSMIT.QUEUE) usage(xmitq)
• Create the local definition of the remote queue:
define qremote(DEF.OF.BEAN.QUEUE) rname(BEAN.QUEUE) +
rqmname(’bean.queue.manager’) xmitq(BACKEND.TRANSMIT.QUEUE)
• Create a channel for sending messages using TCP/IP protocol to remote
machine wsnt00 on port 9101:
define channel(BACKEND.CHANNEL) chltype(SDR) trptype(TCP) +
conname(’wsnt00(9101)’) xmitq(BACKEND.TRANSMIT.QUEUE)
• Create a channel for receiving messages:
define channel(BEAN.CHANNEL) chltype(RCVR) trptype(TCP)
• Exit from runmqsc session:
end
After configuring the queue managers, activate listeners on the queue managers,
and start the channels. At the Application Server MQSeries:
start runmqlsr -t tcp -m bean.queue.manager -p 9101
start runmqchl -c BEAN.CHANNEL -m bean.queue.manager
Similarly, at the back-end MQSeries:
start runmqlsr -t tcp -m backend.queue.manager -p 9102
start runmqchl -c BACKEND.CHANNEL -m backend.queue.manager
6.4.2.2 Programming Model
MQSeries for Java implements MQSeries API by using an object-oriented
programming model. This approach is different from other MQSeries
implementations that uses the procedural programming model. In the MQSeries
Java programming interface, an MQSeries object is represented by an object. As
an example, a queue is represented by an object of class MQQueue. Any call that
is related to a queue is implemented using a method in the MQQueue class.
368
WebSphere Application Servers: Standard and Advanced Editions
MQSeries for Java provides two mechanisms to support Java programs. The
MQSeries Client for Java is for client-side implementation. The MQSeries
Bindings for Java is for server-side implementation.
MQSeries Client for Java
MQSeries Client for Java is an MQSeries client written in Java language. It
follows the Java applet model. The Client for Java enables Java applets to access
the MQSeries server. When accessing the applet, the browser will also download
the corresponding MQSeries Client for Java classes. Thus, the end-user machine
does not need to install any MQSeries component.
The applet opens a server connection channel to MQSeries queue manager via a
socket protocol. Unlike ordinary MQSeries channels, this channel is a two-way
channel. To connect to a particular MQSeries host, the program should specify
the host name, port number and channel name in the MQSeries environment.
MQSeries Bindings for Java
The MQSeries Bindings for Java enables Java applications or servlets in the
application server to access MQSeries. This model does not use a channel, but
instead, it connects directly to MQSeries queue managers. It uses Java native
methods to call MQSeries queue manager API directly. Therefore, this model
brings much better performance than the MQSeries Client for Java. You should
choose this model for implementing MQSeries interfaces in your WebSphere
applications.
The Java component executes in the same machine as the MQSeries server. This
means that the MQSeries server should be in the same machine as the
application server. A connection to a back-end enterprise MQSeries will be in the
server-to-server mode. The application server MQSeries is linked to the back-end
enterprise MQSeries.
MQSeries Java Classes
The ibm.com.mq package implements MQSeries Client for Java, whereas the
ibm.com.mqbind package contains MQSeries Bindings for Java classes. Both
packages have the same programming interface. Therefore, a Java program can
be deployed easily in either environment.
The following are the main classes in the MQSeries for Java:
• MQQueueManager. This class represents a connection to a queue manager.
Using this connection, the program can access queues in the queue manager
by using its accessQueue method. The class also provides several utility
methods for controlling the connection.
• MQQueue. This class represents an MQSeries queue object. It provides
methods for inquiry, set, put, and get operations on the queue. The put method
puts a message into the queue. The get method retrieves a message from the
queue.
• MQEnvironment . This class holds MQSeries environment variables. For
example, host name, port number and channel name for server connection are
contained in this class. It is useful for setting MQSeries Client for Java channel
parameters.
Transaction Support
The MQSeries for Java provides some transactional control for queue operations:
Enterprise Access
369
• The MQQueueManager.begin() signals the queue manager for a new unit of
work.
• The MQQueueManager.commit() signals a sync point and a commit to the
queue manager. The queue manager will make permanent all get or put
operations that occurred since the last sync point.
• The MQQueueManager.backout() signals a sync point and a rollback to the
queue manager. The queue manager will discard all get or put operations that
occurred since the last sync point.
6.4.2.3 Application Flow
The basic structure of Java programs that implement MQSeries for Java is as
follows:
• Import MQSeries for Java classes. For MQSeries Client for Java, put the
following line of the top of your program:
import com.ibm.mq.*;
For MQSeries Bindings for Java, put:
import com.ibm.mqbind.*;
• For MQSeries Client for Java, specify host name, channel and port number of
the MQSeries Server:
MQEnvironment.hostname = "wsnt00.ral.itso.ibm.com";
MQEnvironment.channel = "JAVA.CHANNEL";
MQEnvironment.port = 1414;
• Create a connection to a query manager by creating an instance of
MQQueryManager class:
MQQueueManager qMgr;
...
qMgr = new MQQueueManager("wsnt00.queue.manager");
• Open a local queue for reading and writing:
String localQueueName = "WSNT00.LOCAL.QUEUE";
int openOptions = MQC.MQOO_INPUT_AS_QDEF | MQC.MQOO_OUTPUT;
...
MQQueue qLocal = qMgr.accessQueue(localQueueName,openOptions,
null,null,null);
• Open a remote queue for writing:
String remoteQueueName = "DEF.OF.REMOTE.QUEUE";
openOptions = MQC.MQOO_OUTPUT;
...
MQQueue qRemote = qMgr.accessQueue(remoteQueueName,openOptions,
null,null,null);
• Put a message into a queue:
String sendString = "A String from WSNT00...";
MQMessage sendMessage = new MQMessage();
sendMessage.writeUTF(sendString);
// Set put message options as default
MQPutMessageOptions putMessageOptions = new MQPutMessageOptions();
...
qRemote.put(sendMessage,putMessageOptions);
• Retrieve a message from a queue:
370
WebSphere Application Servers: Standard and Advanced Editions
MQMessage receivedMessage = new MQMessage();
// Set get message options: wait up to ten seconds before failed
MQGetMessageOptions getMessageOptions = new MQGetMessageOptions();
gmo.options = MQC.MQGMO_WAIT;
gmo.waitInterval = 10000;
...
qLocal.get(receivedMessage,getMessageOptions,MAX_MSG_SIZE);
String receivedString = receivedMessage.readUTF();
• Close the queue:
qLocal.close();
qRemote.close();
• Disconnect from the queue manager:
qMgr.disconnect();
6.4.3 MQSeries for Java Example
In this section, we describe an example of using MQSeries Java support in the
WebSphere environment. The example is deployed as an EJB.
6.4.3.1 The CardServices Inc.
The CardServices Inc. is providing credit card services to other companies. One
of its services is to provide credit card statuses and ratings as an online service.
Our XtremeTravel online site can use this service to verify customers’ credit cards
when they reserve or arrange travel packages.
The service is delivered through a CardInfoEJB. The EJB makes use of a utility
class MQConn that handles all operations with MQSeries. It uses MQSeries
Bindings for Java for better performance. The EJB runs on the WebSphere
Application Server.
For simulating the CardServices legacy system, we create a Java application,
CardHost.java. The connection from application server machine and simulated
CardServices host uses the configuration as we discussed in 6.4.2.1, “Setting Up
MQSeries for Java” on page 365.
6.4.3.2 Example: MQConn Utility Class
The following example is a Java class that implements the MQSeries connection.
The MQConn provides basic MQSeries services. The class is a server-side
implementation of MQSeries by using the com.ibm.mqbind package. A similar
class can be developed for client-side implementation by changing the package to
com.ibm.mq and setting host name, channel and port number fields into a
MQEnvironment static class. An EJB can use the class for accessing enterprise
applications via MQSeries.
Enterprise Access
371
package com.ibm.redbook.sg245460;
import java.io.*;
import java.util.*;
import com.ibm.mqbind.*;
// For MQSeries Bindings for Java
public class MQConn {
private
private
private
private
private
private
String queueManagerName = "mq.queue.manager";// Query Manager to connect
String localQueueName = "mq.local.queue";
// Queue name
String remoteQueueName = "mq.remote.queue";
// Queue name
MQQueueManager qMgr;// define a queue manager object
MQQueue
localQueue;
MQQueue
remoteQueue;
private final static int MAX_MSG_SIZE=256;
public int open() {
int rc=0;
int openOptions = 0;
try {
// Creating connection to queue manager
qMgr = new MQQueueManager(queueManagerName);
// Accessing local queue
openOptions = MQC.MQOO_INPUT_AS_Q_DEF | MQC.MQOO_OUTPUT ;
localQueue = qMgr.accessQueue(localQueueName,openOptions,null,null,null);
if( remoteQueueName.equals(localQueueName) )
remoteQueue = localQueue;
else {
// Accessing remote queue
openOptions = MQC.MQOO_OUTPUT;
remoteQueue = qMgr.accessQueue(remoteQueueName,openOptions,null,null,null);
}
} catch (MQException e) {
System.out.println("MQException: " + e.completionCode + ":" + e.reasonCode);
rc = e.reasonCode;
}
return rc;
} // end of open()
public int open(String queueManagerName, String localQueueName, String remoteQueueName) {
this.queueManagerName = queueManagerName;
this.localQueueName = localQueueName;
this.remoteQueueName = remoteQueueName;
return open();
}
public int open(String propertyFileName) {
try {
Properties p = new Properties();
p.load(new FileInputStream(propertyFileName));
queueManagerName = p.getProperty("mq.queue.manager");
localQueueName = p.getProperty("mq.local.queue");
remoteQueueName = p.getProperty("mq.remote.queue");
} catch (IOException e) {
System.out.println("IOException: " + e.getMessage());
}
return open();
}
Figure 354. MQConn Class (1/2)
372
WebSphere Application Servers: Standard and Advanced Editions
public void close() {
try {
localQueue.close();
remoteQueue.close();
qMgr.disconnect();
}
catch (MQException e) {
System.out.println("MQException: " + e.completionCode + ":" + e.reasonCode);
}
} // end of close()
public int send(String message) {
int rc=0;
try {
// Create an MQ message, fill it with the message
MQMessage msg = new MQMessage();
msg.writeUTF(message);
// Specify put message options
MQPutMessageOptions pmo = new MQPutMessageOptions();
// Put the message on the queue
remoteQueue.put(msg,pmo);
}
catch (MQException e) {
System.out.println("MQExcpetion: " + e.completionCode + ":" + e.reasonCode);
rc = -e.reason.code;
}
catch (java.io.IOException e) {
System.out.println("IOException: " + e.getMessage());
}
return rc;
} // end of send()
public int receive(StringBuffer message) {
int rc=0;
try {
MQMessage msg = new MQMessage();
// Specify get message options
MQGetMessageOptions gmo = new MQGetMessageOptions();
gmo.options = MQC.MQGMO_WAIT;
gmo.waitInterval = 10000;
// Wait 10 seconds before it failed
// Getting the message from the queue
localQueue.get(msg,gmo,MAX_MSG_SIZE);
message.setLength(0);
message.append(msg.readUTF());
}
catch (MQException e) {
rc = e.reasonCode;
if(rc != MQException.MQRC_NO_MSG_AVAILABLE) {
System.out.println("MQException: " + e.completionCode + ":" + e.reasonCode);
rc = -rc;
}
}
catch (java.io.IOException e) {
System.out.println("IOException: " + e.getMessage());
}
return rc;
} // endof receive()
} // end of MQConn
Figure 355. MQConn Class (2/2)
Enterprise Access
373
6.4.3.3 Example: CardInfoEJB
The CardInfoEJB queries credit card status and ratings from CreditServices Host.
To deploy this EJB, follow the instructions in 4.2.3, “Deploying an EJB” on page
192. The EJB can be called by an applet, a servlet or other Java beans using the
EJB calling mechanism (see 4.3, “Coding WebSphere EJB Clients” on page 207).
The CardInfoEJB uses the MQConn class as described in 6.4.3.2, “Example:
MQConn Utility Class” on page 371.
To set MQSeries object names, we use a property file that is put in <ASROOT>/
properties/mqconnn.properties, with the following contents:
# WebSphere Application Server
# IBM Redbook SG245460
#
# Sample property file for MQSeries Connection
#
#Wed May 17 11:02:12 EDT 1999
mq.queue.manager = bean.queue.manager
mq.local.queue = BEAN.QUEUE
mq.remote.queue = DEF.OF.BACKEND.QUEUE
Figure 356. MQSeries Connection Properties in mqconn.properties File
Figure 357 shows the bean implementation for CardInfoEJB:
374
WebSphere Application Servers: Standard and Advanced Editions
package com.ibm.redbook.sg245460.card;
import
import
import
import
import
import
java.rmi.RemoteException;
java.security.Identity;
java.util.Properties;
javax.ejb.*;
java.lang.*;
com.ibm.redbook.sg245460.*;
public class CardInfoEJBBean implements javax.ejb.SessionBean {
private javax.ejb.SessionContext mySessionCtx = null;
public CardInfo getCardInfo(String cardNo) {
int rc;
MQConn mqc = new MQConn();
mqc.open("properties/mqconn.properties");
// Send Card Number to Back End Host
mqc.send(cardNo);
// Wait and receive the response;
StringBuffer respbuff = new StringBuffer(256);
mqc.receive(respbuff);
// Parse the response and build the response object
CardInfo ci = new CardInfo();
String response = new String(respbuff);
ci.setCardNo(response.substring(0,16));
ci.setCardName(response.substring(17,19));
ci.setHolderName(response.substring(20,36));
ci.setCardStatus(Integer.valueOf(response.substring(37,39)).intValue());
ci.setCardRating(Integer.valueOf(response.substring(40,42)).intValue());
ci.setStatusDesc(response.substring(43,59));
mqc.close();
return ci;
}
public
}
public
}
public
}
public
}
void ejbActivate() throws java.rmi.RemoteException {
void ejbCreate() {
void ejbPassivate() throws java.rmi.RemoteException {
void ejbRemove() throws java.rmi.RemoteException {
public void setSessionContext(javax.ejb.SessionContext ctx) throws java.rmi.RemoteException {
mySessionCtx = ctx;
}
}
Figure 357. MQSeries Example: CardInfoEJBBean
6.5 Using TXSeries for WebSphere Application
IBM TXSeries is a transactional middleware solution for UNIX and Windows NT
platforms. The TXSeries provides:
• An advanced transaction processing server that combines the technology from
Customer Information Control System (CICS) and Transarc's Encina
transaction processing products.
• Connectivity suite for e-business such as:
• CICS Client and Encina Client
• CICS Gateway for Java
• CICS Internet Gateway
Enterprise Access
375
• CICS Gateway for Lotus Notes
You can find more information about IBM TXSeries and other IBM Transaction
System products at http://www.software.ibm.com/ts.
In relation to WebSphere applications, the TXSeries can provide:
• Back-end transaction processing system
• Connectivity to IBM Transaction Servers such as the well-known CICS
Since WebSphere applications use Java as their underlying platform, the CICS
GATEWAY for Java, which is in the TXSeries package, will be the only
connectivity tool to access Transaction Servers.
IBM also has several products that bring connectivity between Java programs and
Transaction Servers:
• CICS Connector, which is a set of Java classes for developing Java clients that
can access CICS servers
• CICS Transaction Gateway, which includes CICS GATEWAY for Java and
CICS Universal Clients in one product
These two products provide similar functions to CICS GATEWAY for Java.
Since we are discussing TXSeries, we will focus on CICS GATEWAY for Java.
Techniques discussed in this section should apply for all products mentioned
above.
6.5.1 IBM CICS Gateway for Java
The CICS GATEWAY for Java is a set of Java applications and class libraries that
enables Java programs to access CICS servers or TXSeries servers. It provides
secure access and a set of development class libraries. The product is available
as a separate package or as a part of IBM CICS Transaction Gateway.
The CICS GATEWAY for Java requires CICS Universal Clients or CICS Client to
access CICS servers. The CICS Universal Clients are available in IBM CICS
Transaction Gateway.
The CICS Gateway for Java has a server-side Java application that acts as the
gateway to the CICS Client. Any Java program (which can be a Java application,
applet, servlet, or EJB) communicates with the gateway by using a proprietary
socket-based protocol, or through HTTP, HTTPS or SSL protocols.
The CICS Client acts as the interface to CICS servers. It can communicate with
multiple CICS servers with various protocols, such as APPC and TCP/IP. It
handles communication complexities with CICS servers and routes client
requests to the intended CICS server.
A Java program can issue a CICS ECI or EPI request to the gateway. The
gateway translates the request into ECI or EPI calls and gives it to the CICS
Client, then passes them to the intended CICS server. After processing the
request, the CICS server returns the result back to the Java program via the CICS
client and the gateway.
376
WebSphere Application Servers: Standard and Advanced Editions
Figure 358 on page 377 summarizes various alternatives for accessing CICS
servers from a Java program. For security reasons, the gateway is usually in the
same machine as the application server. A servlet or EJB accesses the gateway
using a local TCP/IP connection. The servlet is for accessing CICS applications
from a client browser. The servlet can access the gateway directly or use EJBs.
The EJB can encapsulate CICS transactions to represent a particular business
object. In distributed component architecture, EJBs in other machines should
communicate with application server EJBs to access the CICS server.
Other Java applets or applications outside the application server can also access
the gateway. In this section, we focus on access from the Application Server
environment.
Application Server Machine
Application
Server
Servlet
Engine
CICS
Server
CICS
Gateway
Browser
CICS
Client
for
IIOP
EJB
ECS
EPI
Program
Transaction
Java
External
Enterprise
Systems
5460\546001
Figure 358. CICS Gateway for Java Architecture
6.5.1.1 Programming Model
The CICS Gateway for Java provides a set of classes for developing Java clients.
The classes are put in several packages:
• ibm.cics.jgate.client contains classes for creating connections and requests.
• ibm.cics.jgate.security contains security support classes.
• ibm.cics.jgate.epi contains EPI support classes.
The Gateway Server
The gateway server is implemented as a server-side Java application
ibm.cics.jgate.server.JGate. In CICS Gateway for Java, any Java program acts as
a client of JGate. Then, the JGate translates requests into ECI or EPI calls and
gives them to the CICS Client. To access the gateway servers, the Java program
creates a connection to JGate.
Enterprise Access
377
If the Java program and the CICS Client are in the same machine, you may
bypass the gateway server. In this case the Java program connects to the CICS
Client directly using a local protocol. You don’t need to run the gateway server.
Gateway Connection
An instance of the ibm.cics.jgate.client.JavaGateway class represents a logical
connection from a Java program to the gateway server. A Java program may
create logical connections to several gateway servers by creating several
JavaGateway objects.
To locate a gateway server, specify a URL connection parameter. A local
connection (Java Client and gateway server are in the same machine) uses the
following URL:
local://
A remote connection URL syntax is:
<protocol>://<gateway_server_address>:<port>/
where <protocol> is http or tcp; <gateway_server_address> is the fully qualified host
name or the IP address of the gateway server; and <port> is the TCP port on
which the gateway server is listening. The default protocol is tcp. The HTTP
protocol is preferred when the network uses an HTTP proxy firewall.
In WebSphere environments, normally the application server and the CICS Client
are in the same machine. Therefore, we recommend using a local protocol for
secure and better performance.
Interface Model
Any non-CICS application that accesses a CICS server requires an external
interface into the CICS system. CICS provides two ways for creating external
interfaces, ECI (External Call Interface) and EPI (External Presentation
Interface). These interface models define the construct of requests and
responses.
• In the ECI model, the client calls a CICS program in a CICS server. The call
format is application defined, which generally consists of program name and
program parameters. The client uses CICS COMMAREA to represent both the
request and the response to and from the CICS server. The client sends the
request in COMMAREA. The CICS server returns the responses and return
codes in COMMAREA.
• In the EPI model, the client acts as a 3270 terminal of a CICS server. The
client sends 3270 data streams to the CICS server to initiate a CICS
transaction or to update CICS resources. The server responds with 3270 data
streams.
A Java client sends CICS requests as GatewayRequest objects. Based on the
external interface model, there are two forms of requests:
• As an object of ibm.cics.jgate.client.ECIRequest class by using the ECI model.
The object contains a COMMAREA structure for both request and CICS server
response. The object is also used for CICS server responses.
• As an object of ibm.cics.jgate.cllient.EPIRequest class by using the EPI
model. The object contains 3270 data streams for both request and CICS
server response. The object is also used as a CICS server response.
378
WebSphere Application Servers: Standard and Advanced Editions
Both ECIRequest and EPIRequest extend ibm.cics.jgate.client.GatewayRequest
class.
JavaGateway Methods
The JavaGateway is the class for connection to the Gateway server. It provides
several constructor methods for performing operations on the connection:
• JavaGateway(String urlString) creates a connection as specified by
connection URL urlString.
• setURL(String urlString) sets a connection URL to urlString.
• open() opens the connection.
• flow(GatewayRequest) sends an ECIRequest or EPIRequest object. The
method will wait until the CICS server finishes processing. The CICS server
response is returned in the same ECIRequest or EPIRequest object.
• close() closes the connection.
6.5.1.2 Application Flow
The general structure of the CICS Gateway for Java programs is:
• Import CICS Gateway for Java classes. Insert the following lines at the top of
your Java program:
import ibm.cics.jgate.client.*;
• Create a connection to the Gateway server by creating an instance of
JavaGateway class and specifying the connection’s URL. For example, we use
a local connection:
urlSring connUrl = "local:";
...
JavaGateway conn = new JavaGateway();
conn.setURL(connURL);
...
As an alternative, you may remove the setURL statement and use another
JavaGateway constructor with a URL parameter:
JavaGateway conn = new JavaGateway(connURL);
• Open the connection:
conn.open();
• If you use the ECI model, create an ECI request object and fill its parameters:
String cicsServerName = "CICS001";
String cicsUserId = "USRDEV01";
String cicsPassword = "tryagain";
String cicsProgram = "ORDFOOD1";
byte[] cicsCommarea = String("01SANDWICH02DIETCOKE").getBytes();
...
ECIRequest eciRequest = new ECIRequest(cicsServerName,
cicsUserId,
cicsPassword,
cicsProgram,
cicsCommarea,
ECIRequest.ECI_NO_EXTEND,
ECIRequest.ECI_LUW_NEW);
Send the request and wait for the CICS server response:
Enterprise Access
379
conn.flow(eciRequest);
Retrieve server results in the COMMAREA, check the return code and the
abend code, if any:
String serverResponse = new String(eciRequest.Commarea);
int cicsRc = eciRequest.Cics_Rc;
String abendCode = eciRequest.Abend_Code;
• If you use the EPI model, create an EPI request object. Here, the process is
somewhat complicated, since in the EPI model, the client acts as a terminal.
We should make sure that the client follows the proper presentation sequence:
String sysName;
String netName;
STring devType;
EPIRequest epiRequest = null;
String tranId;
String cmdData;
int cicsRc;
String abendCode;
...
// Add a pseudo terminal to system sysName
epiRequest = EPIRequest.addTerminal(sysName,netName,devType);
conn.flow(epiRequest);
...
// Start Transaction
// For example, we will call CICS command level interpreter CECI.
tranId = "CECI";
// Send escape (0x27), then at row 1 (0x20) col 1 (0x20) put CECI
cmdData = "\x27 CECI"; // 0x27 0x20 0x20 ’C’ ’E’ ’C’ ’I’
epiRequest.startTran(tranId,cmdData.getBytes(),cmdData.length);
conn.flow(epiRequest);
...
// Loop, check for events,
// If the event is Converse, you can send a reply
// and wait until END_TRAN event.
while(true) {
...
// Wait for event ...
epiRequest.getEvent(EPIRequest.EPI_WAIT,1000);
conn.flow(epiRequest);
// Send command, only if the system is ready
// For example, send "F3" (0x33) ’Exit’ to CECI
cmdData = "3 "; // 0x33 0x20 0x20
if(epiRequest.event == EPIRequest.EPI_EVENT_CONVERSE) {
epiRequest.sendReply(cmdData.getBytes(),cmdData.length);
conn.flow(epiRequest);
}
if(epiRequest.event == EPIRequest.EPI_EVENT_END_TRAN) {
cicsRc = eciRequest.Cics_Rc;
abendCode = eciRequest.Abend_Code;
break; // exit from loop
}
...
}
...
380
WebSphere Application Servers: Standard and Advanced Editions
• After processing has finished, close the connection to release resources:
conn.close();
6.5.2 Setting Up CICS Gateway for Java for WebSphere
The requirement for using CICS Gateway for Java support in the WebSphere
environment is to set up Java path information in the WebSphere Java Engine
setup.
6.5.2.1 Setting Up System CLASSPATH Variable
Setting Java library paths in system environment variables may be useful for
developing and debugging purposes. Add the following path into the CLASSPATH
variable:
<JGATE_HOME>/classes
where <JGATE_HOME> is your CICS Gateway for Java installation directory.
Add the following path to the library path variable:
<JGATE_HOME>/bin/<platform>
where <platform> can be "nt", "aix", "mvs", "os2" or "solaris".
6.5.2.2 Setting Up WebSphere CLASSPATH and User LibPath
In the WebSphere Administration, you should also include Java paths into the
application server classpath and user libpath.
• Log on to the WebSphere Administration Tool using the administrator user ID.
• Select Setup > Java Engine to bring up the Java Engine setup form.
• On the Path tab add the following application server classpath entry field:
<JGATE_HOME>/classes
• Add <JGATE_HOME>/bin/<platform> to the user libpath entry field.
After changing this path information, restart both the Web server and
WebSphere. In AIX, you may have to kill the WebSphere processes before
restarting the Web server.
6.5.2.3 Configuring CICS Server Listener and CICS Client
CICS Clients access the CICS server by creating a connection to the CICS server
listener service.The link can use various protocols, such as TCP/IP and APPC.
To configure a listener service in the CICS server using the TCP/IP protocol:
• Add a service entry into the TCP/IP service file on the CICS server machine.
In Windows NT, the file is \winnt\system32\drivers\etc\services. In AIX, the file
is /etc/services. Add the following line into the file:
<service_name>
<port>
• Use an existing CICS region, or add a new region by using:
cicscp -v create dce -R
cicscp -v create region <region_name>
• Add a listener definition into the CICS server region:
cicsadd -c ld -r <region_name> -p <listener_name> Protocol=TCP
Enterprise Access
381
TCPService=<service_name>
where <listener_name> is any name for identifying the listener.
For example, if we create a new region CICSNT01, and set a listener CICSLS01
using CICSTCP01 as <service_name> and 1234 as <port>:
• Add this line into the TCP/IP service file:
CICSTCP01
1234
# CICS Listener
• Execute the following line in the command line:
cicscp -v create dce -R
cicscp -v create region CICSNT01
cicsadd -c ld -r CICSNT01 -P CICSLS01 Protocol=TCP TCPService=CICSTCP01
• Start the region by executing:
cicscp -v start region CICSNT01
To configure the CICS client to access this listener:
• Add into the CICS client configuration file, CICSCLI.INI, the following lines:
Server = <server_name>
Description = TCP/IP Server
Protocol = TCPIP
NetName = <server_host_name>
Port = <port>
where <server_name> is an arbitrary name that uniquely identifies the CICS
server.
• Start a connection to the CICS server:
cicscli /S=<server_name>
For example, if the previous CICS server example is in the host
wsnt00.itso.ral.ibm.com, add these lines into CICSCLI.INI:
Server = CICSSV01
Description = Connection to TCP/IP Server Example
Protocol = TCPIP
NetName = wsnt00.itso.ral.ibm.com
Port = 1234
Start the CICS client connection to the CICS server by using:
cicscli /S=CICSSV01
Verify that the connection is working:
cicscli /l
6.5.2.4 Setting Up and Running the Gateway
You need to set up and run the Java Gateway application only if you use Network
JavaGateway objects to connect to the CICS Client in a remote machine. If the
Java program and the CICS Client are in the same machine, you do not need to
run the JavaGateway application and use the local protocol. In this case, the
JavaGateway object in the Java program communicates directly to the CICS
Client.
382
WebSphere Application Servers: Standard and Advanced Editions
The Java Gateway application has a property file, Gateway.properties. You need
to set several parameters to connect the Gateway applications to the CICS Client.
• Open <JGATE_HOME>/bin/Gateway.properties file
• Specify the network protocol handler and its parameters:
[email protected]<protocol_name>.handler = <protocol_handler_name>
[email protected]<protocol_name>.parameters = <parm1=value1;parm2=value2 ...>
For example, if the JavaGateway application is listening on port 9090:
[email protected]=com.ibm.cics.jgate.server.TCPHandler
[email protected]= port=9090
This will correspond to connection URL tcp://<gateway_host_name>:9090/ for
the JavaGateway object in the Java program.
To start the gateway, enter the following command in the command line:
JGate
6.5.3 CICS Gateway for Java Example
In this section, we give an example using CICS Gateway for Java in the
WebSphere environment.
6.5.3.1 Example: CICSAccess Utility Class
The following example is a Java utility class that provides methods to access the
CICS server by using CICS Gateway for Java. The class uses the ECI model for
creating CICS requests.
To set CICS connection parameters, the class reads a property file in
<ASROOT>/ properties/cicsconn.properties. For example, the file might look like
this:
# WebSphere Application Server
# IBM Redbook SG245460
#
# Sample property file for CICS Connection
#
#Wed May 17 11:02:12 EDT 1999
cics.url = local:
cics.user = CICSUSER
cics.password = LETMEIN
cics.server = CICSSV01
Figure 359. CICS Connection Properties in cicsconn.properties File
Figure 360 and Figure 361 show the code for the CICSAccess class:
Enterprise Access
383
package com.ibm.redbook.sg245460;
import java.io.*;
import java.util.*;
import ibm.cics.jgate.client.*;
public class CICSAccess {
private
private
private
private
private
private
private
String
String
String
String
String
byte[]
int
urlString = "local:";
cicsUserId = "CICSUSER";
cicsPassword = "";
cicsServerName = "";
cicsProgram = "";
cicsCommarea = "";
cicsCommareaLength = 0;
private JavaGateway cicsConn = null;
private ECIRequest eciRequest = null;
public void open() {
try {
cicsConn = new JavaGateway(urlString);
cicsConn.open();
} catch(IOException) {
e.printStackTrace();
}
}
public int open(String propertyFilename) {
try {
Properties p = new Properties();
p.load(new FileInputStream("properties/cicsconn.properties"));
urlString
cicsUserId
cicsPassword
cicsServerName
=
=
=
=
p.getProperty("cics.url");
p.getProperty("cics.user");
p.getProperty("cics.password");
p.getProperty("cics.server");
} catch (IOException e)
e.printStackTrace();
}
open();
}
public int sendRequest(String cicsProgram, String cicsCommarea, int cicsCommareaLength) {
int rc=0;
try {
byte abCommarea = new byte[ iCommareaLength ];
System.arraycopy( cicsCommarea.getBytes(),0,abCommarea,0,
Math.min(abCommarea.length, cicsCommarea.length()));
Figure 360. CICSAccess Class (1/2
384
WebSphere Application Servers: Standard and Advanced Editions
public String getResponse() {
if( eciRequest.Cics_Rc = 0 ) {
return new String(eciRequest.Commarea);
} else {
return "ABEND:" + eciRequest.Abend_Code);
}
}
public void close() {
try {
jgaConection.close();
} catch(IOException e) {
e.printStackTrace();
}
Figure 361. CICSAccess Class (2/2)
Enterprise Access
385
386
WebSphere Application Servers: Standard and Advanced Editions
Chapter 7. WAS 3.0, Site Analyzer Technology Preview
This chapter provides a technology preview of a WebSphere product function that
will be available with WebSphere Application Server V3.0. It is currently available
in beta only. Some of the screens and functions will change before general
availability. The purpose of this chapter is to give you exposure to the product and
its functions.
As a Web site becomes more complex, the job of managing the site becomes
more critical. The Web site contents, links and user activities, and the tasks for
managing these resources, can grow too fast and too complicated to be managed
manually. Some examples of tasks that represent crucial site operations are:
• Checking that the content is the correct version
• Checking that the links to the contents and to other supporting sites are
working with sufficient bandwidth
• Monitoring the usage of particular content or a link
These tasks, which are normally what webmasters do, are becoming important
factors for building a successful Web site.
The WebSphere Site Analyzer is aimed at solving these problems. The Site
Analyzer is a set of software programs and tools used to manage Web site
operations. It provides:
• Web content analysis
• Usage analysis for monitoring resource usages
• Statistics using user-defined reports
This chapter focuses on using the WebSphere Site Analyzer to manage Web Site
operations. For information about software requirements, installation and setup
for the WebSphere Site Analyzer, see the following section.
7.1 Installing WebSphere Site Analyzer
The Site Analyzer is a tool for analyzing Web sites. It can check Web site
contents, analyze the usage of the content, and produce reports. In this section,
we work with the installation of Site Analyzer.
The Site Analyzer is a client/server application. The Site Analyzer server does not
have to run in the same machine as the Web Server and you should consider
running it on a separate machine, because the Site Analyzer server uses lots of
CPU processing time to perform its analysis. The client machine should have the
Site Analyzer client component. It can be in the same machine as the Site
Analyzer server.
The Site Analyzer uses IBM DB2 UDB V5.2 for its databases.
Before installing the Site Analyzer, there are several steps that need to be done:
• As a prerequisite, you should have installed JDK 1.1.7b (on Windows NT and
Solaris) or JDK 1.1.6 with fix pack 8 on AIX, a database such as DB2 UDB
Workgroup or Enterprise Edition, and a Web browser such as Netscape
© Copyright IBM Corp. 1999
387
Communicator 4.x or Internet Explorer 4.x. The database can be in the local
machine or in a remote machine.
Note: If you don’t want to install the JDK, then Site Analyzer will automatically
install the appropriate JRE for you.
• Create or use an existing database for Site Analyzer purposes. If you use a
remote database, you should configure your local machine for a remote
interface. When using DB2, you can use the Client Configuration Assistant, as
described in 2.1.7.3, “Configuring Remote Interface” on page 55.
• At this point, you are ready to install the Site Analyzer.
The installation package provides an installation program. In Windows NT, it is a
standard Windows installation using setup.exe. The installation program consists
of a sequence of dialogs as shown in Figure 362 on page 388 to Figure 365 on
page 390.
• After the first Welcome dialog box, enter a destination directory.
• The next dialog box asks you to select components. You can install both
server and client components in the same machine. In the client machine, you
should install only the client component.
• The subsequent dialog boxes set the program folder name, copy the files into
the destination directory, and finish the installation process.
Note: Site Analyzer packages and silently installs DB2 UDB and it can include
the DB2 UDB national language group1 support.
Figure 362. Site Analyzer Installation Welcome Dialog
388
WebSphere Application Servers: Standard and Advanced Editions
Figure 363. Site Analyzer Installation - Specifying Destination Directory
Figure 364. Site Analyzer Installation - Select Components
WAS 3.0, Site Analyzer Technology Preview
389
Figure 365. Site Analyzer Installation - Last Dialog Box
7.1.1 First Time Setup
In our Site Analyzer installation process, we did not configure the Site Analyzer to
use the database that we had created before. When you use the Site Analyzer for
the first time, it will automatically invoke a Startup Wizard (Figure 366 on page
391) to configure database connections and server addresses. To invoke the Site
Analyzer, click Start -> Programs IBM WebSphere -> Site Analyzer 3.0 -> Site
Analyzer.
The Startup Wizard consists of a sequence of tab dialog boxes. At this point, only
the Server tab and Database tab are important.
• In the Server tab (Figure 367 on page 391), specify the TCP/IP host name and
port number for the Site Analyzer server. If you have not installed a Site
Analyzer server, you won’t be able to test the connection. The test button is
applicable for the client only while the server is running. The test allows the
user to see if the client can in fact connect to the server with the specified
configuration.
• In the Database tab (Figure 368 on page 392), specify the database
connection parameters, which include the connection URL, database user ID
and password, and the JDBC driver. To make sure that the connection works,
click the Test Connection button.
390
WebSphere Application Servers: Standard and Advanced Editions
Figure 366. Site Analyzer Startup Wizard for First Time Setup
Figure 367. Site Analyzer Startup Wizard - Specifying Site Analyzer Server Parameter
WAS 3.0, Site Analyzer Technology Preview
391
Figure 368. Site Analyzer Startup Wizard - Specifying Database Connection
After you click Finish in the last Startup Wizard Tab dialog box, the wizard will
automatically start the Site Analyzer.
7.2 A First Look at the Site Analyzer
This section gives a brief tour of Site Analyzer. After you have installed and set up
the Site Analyzer, you can run it by clicking Start -> Program -> IBM WebSphere
-> Site Analyzer V3.0. This will bring up Site Analyzer Project Center (Figure
369), which in fact is a Site Analyzer client application. The Project Center
provides several navigation mechanisms:
• Menu bar.
• Tool bar. Some tools in the tool bar are contextual. They will operate on a
selected item on the Project tree or on the right-frame list.
• Project tree in the left frame. Each tree node has a contextual list in tabular
format in the right frame. When you select a tree node, the right frame will
display a table containing items or information of the node type.
• Contextual menu that is invoked when you right-click any object in the Project
tree or right-frame list.
392
WebSphere Application Servers: Standard and Advanced Editions
Figure 369. WebSphere Site Analyzer Project Center
7.2.1 Site Analyzer Users
The Site Analyzer has two user roles:
• Administrator, which can perform every available action including configuring
Site Analyzer, creating analysis, running analysis and viewing the results
• Client, which can view analysis results only
Table 34 summarizes actions that Site Analyzer user roles can perform. An "X"
under Administrator or Client column specifies that the user in that role is allowed
to do the actions:
Table 34. User Authorization
Action
Administrator
Client
Create, edit and delete projects
X
X
Create, edit and delete
Content/Usage Analysis
X
Run and Schedule
Content/Usage Analysis
X
Site Surveyor
X
X
Quick Find
X
X
Create, edit and delete Analysis
Report Element
X
X
Create report
X
X
The Site Analyzer user setup follows operating system user setup. However, user
privilege is defined and verified in the database. The Site Analyzer does not
WAS 3.0, Site Analyzer Technology Preview
393
provide its own user logon and setup tool. The database administrator grants the
corresponding privileges to the user.
7.2.2 Site Analyzer Analysis and Projects
In Site Analyzer, the analysis is a set of definitions for a particular site
management task. The definition includes:
• Analysis name and type
• Target site information
• Analysis parameters
The Site Analyzer has two forms of analysis:
• Content analysis
• Usage analysis
The Site Analyzer organizes analysis tasks into Site Analyzer projects. Each
project defines a set of content analysis tasks, a set of usage analysis tasks and
a set of reports.
The Site Analyzer stores project information into a file, with a .sap extension. The
project file resides in the client machine and contains links to various items in the
database.
7.2.3 Site Analyzer Architecture
The Site Analyzer is a Java client/server application. The Site Analyzer server
runs as a background process in a server machine. The Site Analyzer client is a
Java Swing user interface application. You can install the client component in the
same machine as the server. The connection between the client and the server
uses socket protocol on a specified port. The server host name and service port
number are set in Startup Wizard, which is invoked during the client’s first-time
run.
The Site Analyzer stores its data in a DB2 UDB database. The Site Analyzer
server and the database engine may be in different machines. In this case, you
can create either a remote database connection between them or use JDBC net
drivers.
The Site Analyzer performs the analysis by two main mechanisms:
1. Using a Web robot to explore the structure and the content of a site
2. Using Web server log files to retrieve client activity and resource usage
7.3 Content Analysis
The Site Analyzer Content Analysis function enables you to perform the following
site management functions:
• Check that the site content contains the correct information
This includes verifying that no part of the page is missing and the page is the
correct version.
• Imposing site policies
394
WebSphere Application Servers: Standard and Advanced Editions
This includes verifying that each page follows site standards such as metatags
and checking links to external sites.
• Forcing site security
Each secure page is properly secured.
• Creating site visualization to show content links and site structure
• Checking content size and its transfer rate
• Checking for broken links
• Ensuring that the content is accessible by checking its HTTP status
• Partitioning the site to provide sub-site views that may be useful for detailed
analysis
The hyperlink structure characterizes Web site documents. There are several
ways to specify a link in a Web document. The following list summarizes several
link types in a static HTML environment:
• <LINK>,<A> and <AREA> tags with an HREF attribute explicitly specify the
link to other documents.
• <IMG>, <APPLET>, <EMBED> and <FRAME> tags specify the location of the
Web resources.
• <SCRIPT> and <FORM> specify the location of procedures such as using
CGIs or servlets.
• FTP and MAILTO protocols specify a link to other resources using specific
protocols.
Currently the Site Analyzer can’t analyze dynamic links created using dynamic
contents techniques such as with servlets, ASP, and JSP.
In a hyperlink structure, a referenced document may in turn reference links to
other documents. The Content Analysis function can trace the links several layers
deep. The links may also go to external sites.
For a complex Web site, the amount of content and links can grow very fast.
Therefore, it is advisable to partition the site’s structure into several sub-sites and
analyze each one by one.
Content Analysis uses a Web robot to explore the site’s contents and structures.
A Web robot is a program that automatically travels down the hypertext structure.
Upon reading a Web document, the robot can perform specified tasks and check
rules, such as calculating file sizes. Then, it goes to every link in the document.
This process continues until a specified time limit or a maximum amount of
resources is exceeded.
There is a Robot Exclusion Protocol to indicate which part of the site should not
be visited by the robot. The Robot Exclusion Protocol is a standard that is well
documented on the robot mailing list
(http://info.webcrawler.com/mailing-lists/robots/info.html). It is implemented
using a file, robot.txt, which is located under the site URL. The file contains two
types of statements:
1. User-agent: * | <robot_name> to indicate for which robots the rule should
apply. An asterisk (*) indicates all robots.
WAS 3.0, Site Analyzer Technology Preview
395
2. Disallow: <disallowed_URL> to indicate which sites should not be visited by
the robot specified in the user-agent.
For example, the following lines in http://wsnt00.itso.ral.ibm.com/robot.txt ban
every robot from visiting http://wsnt00.itso.ral.ibm.com/web/classes:
# A comment beginning with *
User-agent: * # This rule applies to any robot
Disallow: /web/classes # Don’t detect my classes
You can specify a set of analysis tasks and rules for controlling Web robot
operations, which include:
• Starting URLs for analysis (Analysis Root URL).
• Analysis depth limit, either in maximum link depth or maximum number of
resources to analyze. If either one of the conditions is satisfied, the analysis
stops.
• Obey Robot Exclusion Protocol as specified in the site’s robot.txt.
• Specific actions, such as calculating resource size or checking metatags in
Web pages.
• Exclude or include URLs that are to be included in the analysis.
Content Analysis records the time required for accessing a specific resource. It is
possible that a Web resource is not accessible. In this case, you can specify a
time limit to continue accessing other resources. The analysis will keep trying to
access the inaccessible resource until a global time limit is reached. The global
time limit is the time when the whole analysis process will stop.
The analysis also records the transfer rate for loading a specific resource. Note
that the transfer rate is not a statistical average, but only the value recorded
during the analysis.
The Site Analyzer analyzes the following types of contents:
• Web pages
• Applets
• CGI Scripts
• Images
• Mail
• ftp
7.3.1 Using Content Analysis
To create, edit, delete, and run Content Analysis tasks you should be a Site
Analyzer Administrator. A client can view only the result using Site Surveyor or
Reports.
7.3.1.1 Creating a New Content Analysis
To create a Content Analysis task, perform the following steps:
• In the Site Analyzer Project Center window, select the project with which you
want to work.
396
WebSphere Application Servers: Standard and Advanced Editions
• Select File -> New -> Analysis to bring up the New Analysis wizard as shown
in Figure 370 on page 397.
• Select Create a Content Analysis and click Next .
• The next dialog box asks for the analysis task’s name and the analysis root
URL (Figure 371 on page 397). Supply a unique analysis name and the
starting analysis URL in your site.
• You can either click Finish or choose to configure advanced parameters by
clicking the Advanced button.
Figure 370. Create a New Content Analysis
Figure 371. Specifying the Name and the URL for Content Analysis Task
7.3.1.2 Setting Content Analysis Advanced Parameters
To set advanced parameters for a Content Analysis task, you can click either the
Advanced button during analysis creation or right-click the analysis row, followed
WAS 3.0, Site Analyzer Technology Preview
397
by Edit on the analysis contextual menu. This will bring up the Advanced Content
Analysis dialog box as shown in Figure 372.
Figure 372. Content Analysis Advanced Settings
In this dialog box you can navigate using a parameter tree in the left frame. Table
35 summarizes the Content Analysis advanced settings:
Table 35. Content Analysis Advanced Setting
Parameter Name
398
Description
Analysis Name
The name of the analysis.
Root URL
The URL where the analysis will start.
Analysis Depth
Limit how far the analysis will go. It is specified either by
maximum link depth or maximum number of resources.
If either one of these conditions is satisfied, the analysis
will stop.
File Size Calculations
Ask the Web robot to calculate Web resource size.
Specify to calculate either aggregate page size, image
size, applet size, or embedded object size.
Restrictions
Ask the Web robot to obey the Robot Exclusion Protocol
and verify external links. The external links are defined
in the site definition parameters.
Site Definitions
Specify which sites are to be analyzed by including the
site URL, host name, and domain in Included Lists, or
exclude host name and domain in the Excluded Lists.
Connections
Specify time limit to wait for each access before
accessing another resource.
Specify global time limit up to when the whole analysis
task should stop.
Passwords
Specify user ID and password for password-protected
pages. Add user IDs and passwords into User
passwords list. Specify any key ring file that contains
public keys, private keys, and certificates.
WebSphere Application Servers: Standard and Advanced Editions
Parameter Name
Description
Proxy Settings
If your site uses firewalls, enter proxy and SOCKS
settings for this analysis.
Language
Specify language settings to display language
information for multi-language sites.
Required Meta Tags
Specify metatags that should exist in HTML pages.
Agent Name
To identify which hit is from the Site Analyzer. A hit
(request) in a site is recorded by the Web browser in a
log file. This log file usually includes the source (agent)
of the hit. The agent name is used by Usage Analysis to
exclude Site Analyzer-owned hits.
7.3.1.3 Running Content Analysis
Now you can run the Content Analysis tasks that you have created. To run this
analysis task, right-click the analysis row in the right frame, and choose Run Now
on the selection menu.
As you can see, the status column indicates that the analysis is running. It will run
until it reaches a specified depth limit or maximum number of resources or global
time limit. If you specify the depth limit as too large, the analysis may run for a
very long time. Obviously, the analysis complexity will grow exponentially over the
depth limit.
As the analysis finishes, it shows only the completion status of the analysis. You
have to view the result using separate Site Analyzer functions.
7.3.1.4 Content Analysis Output
The result of Content Analysis is stored in the Site Analyzer database. There are
several ways to view this result:
• View the site map visually by using Site Surveyor (see 7.5, “Site Surveyor” on
page 404 for how to use the Site Surveyor).
• Query specific content information by using Quick Find.
• Create a user-defined report. See 7.6, “Reports and Details” on page 406 for
how to create report elements and reports.
7.4 Usage Analysis
Usage Analysis can be used for analyzing:
• The client environment, in terms of the client’s browser and platforms
• Client activity
The analysis records client activity in a session (a visit). A visit starts with the
first hit on the site up to the point that the client is idle for a pre-determined
amount of time. During a client visit, the analysis can gather a lot of valuable
information, such as hits per visit, entry or exit point, and duration per visit.
• Response
This can indicate the success rate of requests to a certain Web resource. The
analysis also can differentiate errors due to an invalid request by the client,
such as clicking the Stop button on the browser.
WAS 3.0, Site Analyzer Technology Preview
399
• Resource usage
The resource can be specified by a name or by category.
• Referral
Is the site from where the client makes the request. It is useful for counting
advertisement hits from a referring site.
• Entire site usage
The analysis measures this information in units: hits, page view, visit, duration,
and bytes transferred. The page view counts hits for the page itself. It does not
count hits for items on the page. The analysis also can calculate totals (sums) or
averages of a certain measurement.
7.4.1 Web Server Log Files
With each client request, the Web server logs the requests and its response
status. The Usage Analysis uses these log files for analyzing Web usage. The
Usage Analysis will try to mine any information that can be derived from the log
file.
Most Web servers can store log information into the Common Log Format as
originally defined by the NCSA. This log format distributes log information into
three log files: access, agent and referer files.
The access log file has the following syntax:
clienthost authuser [date] "request" status length
where:
• clienthost is the client IP address or host name
• authuser is the user ID as entered by the client
• [date] is the date, time and GMT; by default it is the client local time
• "request" specifies the request method and the Universal Resource Identifier
(URI) for corresponding Web resources
• status is the HTTP status code in the Web server response to the client
• Response length is in bytes
As an example, the access log file contained:
9.24.105.244 - - [03/May/1999:09:36:35 -0500] "GET /fountainpen3.jpg HTTP/1.0"
200 6357
9.24.104.68 - - [13/May/1999:09:37:36 -0500] "GET
/homepage?OpenElement&FieldElemFormat=gif HTTP/1.0" 404 282
The agent and referrer files capture HTTP header "user-agent" and "referrer"
respectively. The agent specifies client browser type. The referrer specifies from
where the request was made. As an example, the agent log file contains:
[03/May/1999:09:36:35 -0500] "Mozilla/4.0 (compatible; MSIE 4."
[03/May/1999:09:37:36 -0500] "Mozilla/4.51 [en] (WinNT; I)"
...
As an example, the referrer log file contains:
[03/May/1999:09:36:35 -0500] "http://wsnt00/"
400
WebSphere Application Servers: Standard and Advanced Editions
[03/May/1999:09:37:36 -0500] "http://wsnt00.itso.ral.ibm.com/"
...
Some Web servers can use other formats, such as the W3C extended log file
format (see http://www.w3.org/TR/WD-logfile) or a custom format.
In any case, the Usage Analysis will use Common Log Format fields, plus
user-agent and referrer as the minimum required fields. You should configure
your Web server log files to include these fields.
7.4.2 Using Usage Analysis
To create, edit, delete, and run Usage Analysis tasks, you should be the Site
Analyzer Administrator. A client can view only the results by using reports.
7.4.2.1 Creating a New Usage Analysis
To create a Usage Analysis task, perform the following steps:
• In the Site Analyzer Project Center window, select the project with which you
want to work.
• Select File -> New -> Analysis to bring up the New Analysis wizard as shown
in Figure 373 on page 401.
• Select Create a Usage Analysis and click Next .
• The next dialog box asks for the Usage Analysis task name. Supply a unique
analysis name, then click Next.
Figure 373. Create a New Usage Analysis
• Add Web server log files that you want analyzed (see Figure 374 on page
402). Click the Add button (the left-most button below the log file list). This will
bring up the Specify Log Files dialog box (see Figure 375 on page 402). On
the first tab select an appropriate log file format. On the second tab, specify
the log file name. Then click OK .
WAS 3.0, Site Analyzer Technology Preview
401
Figure 374. Specify Log Files Dialog Box 1/2)
• In the next dialog box, specify your site hostnames (see Figure 376 on page
403). This is useful to filter out requests from your own hosts.
• Click Finish to create a new Usage Analysis.
Figure 375. Specify Log Files Dialog Box (2/2)
402
WebSphere Application Servers: Standard and Advanced Editions
Figure 376. Site Host Names Dialog Box
7.4.2.2 Setting Usage Analysis Advanced Parameters
To set advanced parameters for a Usage Analysis task, you can click either the
Advanced button during analysis creation or right-click the analysis row followed
by selecting Edit on the analysis contextual menu. This will bring up the
Advanced Usage Analysis dialog box as shown in the following window:
Figure 377. Usage Analysis Advanced Settings
WAS 3.0, Site Analyzer Technology Preview
403
In this dialog box, you can navigate using a parameter tree in the left frame. Table
36 summarizes the Usage Analysis advanced settings:
Table 36. Content Analysis Advanced Setting
Parameter Name
Description
Analysis Name
The name of the analysis.
Log Files
Web server log files to be analyzed.
Site Hostnames
Your site host names. This is useful to identify
which requests are from internal sites and
which requests are from external sites.
Session Length
Time limit for a user session time.
Filters
Exclude artwork requests or requests from specified IP
addresses.
Web Application Patterns
Count only hits for a specified application and its
parameter pattern.
Time Zone
Convert time zone information in the requests into a
specified time zone.
7.4.2.3 Running Usage Analysis
Now you can run the Usage Analysis tasks that you have created. To run the
analysis task, right-click the analysis row in the right frame, and choose Run Now
on the selection menu.
As you should be able to see, the status column indicates that the analysis is
running. It may take some time to read the Web server log files and write the
results into the Site Analyzer database.
7.4.2.4 Usage Analysis Output
The result of the Usage Analysis is stored in the Site Analyzer database. To view
the result:
• Create a report element that contains only one measurement topic. It is useful
for a quick view for a specific measurement.
• Create several report elements and combine them into a report.
7.5 Site Surveyor
The Site Surveyor shows the result of a Content Analysis visually. It displays:
• Site structure in a tree view starting from the analysis root URL. You can
expand or collapse sub-trees to provide necessary details. Each tree leaf
corresponds to a resource (page, image, applet, etc.) or a link.
• Information about resource and link.
The Site Surveyor provides the following resource information:
• Resource type: HTML, applet, embedded object, CGI script, etc.
• Resource URL
• Resource Title, such as HTML <TITLE> page title
• HTTP Status returned when the analysis accesses the resource
404
WebSphere Application Servers: Standard and Advanced Editions
• Transfer rate when the analysis accesses the resource
• The size of the resource
• The aggregate size, which is the sum of the page size and all objects in it
• The last modified date that can indicate the version of the resource
• Expiration date as indicated in the "META" metatag.
The Site Surveyor provides the following link information:
• Link text
• Link type according to the way the link is put in the HTML; for example,
<LINK> specifies hyperlink, <IMG> specifies image, and so on
• Broken link, which can be a resource that does not exist when the analysis
tries to visit it, or a time-out hyperlink such as those caused by a busy server
To use Site Surveyor, run a Content Analysis. After the analysis has stopped,
right-click the Content Analysis and select View with Site Surveyor.
The Site Surveyor will read Content Analysis results from the database, and show
the content according to resource type and their links.
Figure 378. Site Surveyor Main Window
For example, Figure 378 on page 405 is the result of Content Analysis on the IBM
Software site with http://www.software.ibm.com as the analysis root URL. In the
Site Surveyor left frame, there is a site structure tree with IBM Software as the
root. In this case, the IBM Software is an HTML page. On the right frame there
are two tab sheets. The Site Resource Details tab shows all resources that can
WAS 3.0, Site Analyzer Technology Preview
405
be linked from the HTML page. The Resource Links tab (Figure 379 on page 406)
shows link information for each link. Notice that in this figure, in the left-most
column of Resource Link Tabs, the link to /cgi-bin/listbox-redirect.pl is broken.
Figure 379. Site Surveyor Indicates a Broken Link on IBM Software Site
7.6 Reports and Details
The Site Analyzer can present analysis results as reports. The report is built upon
several report elements. Each report element represents an analyzed item to be
included in the report.
Either the Site Analyzer Administrator or client user can create report elements
and reports. Site analyzer provides report element and report wizards that are
easy-to-use and self-explanatory.
7.6.1 Report Element
The report element setting consists of:
• Type, which is the measured item during analysis
• Measurement unit
• Filter, for creating a more specific result
• Presentation format, which can be in tabular format or in a graphical chart
In Content Analysis, analyzed item types are:
• Pages
• Links
In Usage Analysis, analyzed item types are:
406
WebSphere Application Servers: Standard and Advanced Editions
7.6.1.1 Content Analysis Report Element
A Content Analysis stores its results in the Site Analyzer database. To view the
result, you should use either Site Surveyor, or Quick Find, or create a report
element. You can create several report elements and include them in a single
report. You can specify the report element even before the analysis is run.
To create a report element on a Content Analysis complete the following steps:
• From the Menu Bar, Select File -> New -> Content Report Element to invoke
the Report Element Wizard for Content Analysis as shown in Figure 380:
Figure 380. Report Element Wizard for Content Analysis
• The Wizard consists of several tab sheets. Table 37 summarizes Content
Analysis report element settings:
Table 37. Content Analysis Report Element Settings
Setting
Description
Analysis
Select a Content Analysis to use for this report
element.
Type
Items that will be reported, which can be pages or
links.
Aggregates
How the item is measured or grouped.
Filter
Specify query condition in more detail by using item
parameters.
Result Format
Specify maximum rows returned in the report.
Specify sort key and sort order.
Preview
To view the sample of the report.
Chart
To create a chart based on the item data.
WAS 3.0, Site Analyzer Technology Preview
407
Setting
Name
Description
The name of this report element.
• After completing the Report Element Wizard page, you can click to create a
new Content Analysis report element.
You can always change report element settings by right-clicking the analysis in
the right frame and selecting Edit .
7.6.1.2 Usage Analysis Report Element
To view the result of a Usage Analysis, you should create several report elements
and combine them in a report. You can specify the report element even before the
analysis is run.
To create a report element on a Usage Analysis complete the following steps:
• From the Menu Bar, Select File -> New -> Usage Report Element to invoke
the Report Element Wizard for Usage Analysis.
• After completing the Report Element Wizard page, you can click to create a
new Usage Analysis report element.
You can always change report element settings by right-clicking the analysis in
the right frame and selecting Edit .
7.6.2 Report
After creating several report elements, you can create a report that combines the
report elements.
To create a report complete the following steps:
• From menu bar, select File -> New -> Report to invoke the Report Element
Wizard.
• The Wizard consists of several tab sheets. In the Report Elements tab select
report elements to be included in this report.
• In the Order tab sheet, you can set the order of report element appearance in
the report.
• You can add a glossary of terms specified in the report. To do this, click any
term on the left frame of the tab sheet.
• On the last tab, enter the name for this report. Then, click Finish to create the
report.
7.6.2.1 Generating the Report
The report generation extracts analysis data from the database, performs
calculations according to the report specification and creates an HTML document
as a report. This process also allows you to do the final cosmetic artwork for the
report, which includes adding a logo and selecting a table style.
In addition, you can specify the time range for the report and whether the report
should be dynamically generated.
408
WebSphere Application Servers: Standard and Advanced Editions
The dynamically generated option performs analysis data extraction when the
report is requested by a client. A report of this can be published to a Web server.
To generate a report, select the report item from the Project tree or from the
report list on the right frame. Right-click the item and select Generate Report .
This will bring up the Report Generator Wizard as shown in Figure 381:
Figure 381. Report Generator Wizard
As the report is in HTML format, you can view it using a browser. You can do it by
selecting the report item on the Project tree or on the report list in the right frame
and continue with the following:
• Right-click the item and select Show. This will automatically call a Web
browser to display the report. The report HTML documents will be kept locally
in the <SiteAnalyzerRoot> directory.
• Right-click the item and select Publish. The Site Analyzer will ask for a
publish destination (Figure 382). You can put the result in another Web server.
Figure 382. Specifying Publish Destination
WAS 3.0, Site Analyzer Technology Preview
409
410
WebSphere Application Servers: Standard and Advanced Editions
Chapter 8. Problem Determination
In this chapter we look at the functions that are available in WebSphere and other
products that help with the problem determination process.
8.1 WebSphere Log Files
This section shows you what logs are available in WebSphere, what you would
expect to see in them, what they are good for and how to enable them. There is
some overlap with other sections in this chapter as other functions can also
produce logs, so some sections simply contain references to sections later in the
chapter.
8.1.1 Overall Log Structure
Table 38 shows some general information on the logs available in WebSphere.
The Relative Directory column shows the directory relative to the root log
directory at <Server Root>/logs. Note that these file names are configurable if
desired; the table values represent the default values.
Table 38. Log File General Information
Log File Name
© Copyright IBM Corp. 1999
Relative
Directory
Description
Described in
jvm_stderr.log
/
Standard error
output from the
JVM.
8.1.2, “The JVM
Standard Error Log”
on page 412.
jvm_stdout.log
/
Standard output
from JVM.
8.1.3, “The JVM
Standard Output
Log” on page 413.
oop_native.log.ERROR
/
Error messages
from the native code
portion of the
out-of-process
engine. Seldom
used.
N/A
oop_native.log.INFORM
/
Informational
messages from the
native code portion
of the out-of-process
engine. Seldom
used.
N/A
apache.log.INFORM.*
/
IBM HTTP Server
informational
messages.
8.1.5, “The IBM
HTTP Server Error
Log” on page 414.
apache.log.ERROR.*
/
IBM HTTP Server
error messages.
8.1.5, “The IBM
HTTP Server Error
Log” on page 414.
apache.log.TRACE.*
/
Trace log for IBM
HTTP Server.
N/A
411
Log File Name
Relative
Directory
Description
Described in
websphere_trace.log
/
Trace information
generated by
WebSphere trace
monitors.
8.1.6, “The
WebSphere Trace
Log” on page 414.
error_log
/servlet
General error
messages for the
servlet engine.
Hardly ever used.
N/A
event_log
/servlet
General event
messages for the
servlet engine.
Hardly ever used.
N/A
error_log
/servlet/admi
nservice
Error messages
from the WebSphere
administration
application.
8.1.7, “The Servlet
Admin Service Error
Log” on page 415.
event_log
/servlet/admi
nservice
Informational
messages from the
WebSphere
administration
application.
8.1.8, “The Servlet
Admin Service
Event Log” on page
416.
access_log
/servlet/admi
nservice
Log of access
requests to the
WebSphere
administration
application.
8.1.9, “The Servlet
Admin Service
Access Log” on
page 416.
error_log
/servlet/servl
etservice
Error messages
from the servlet
service.
8.1.10, “The Servlet
Service Error Log”
on page 417.
event_log
/servlet/servl
etservice
Informational
messages from the
servlet service.
8.1.11, “The Servlet
Service Event Log”
on page 418.
access_log
/servlet/servl
etservice
Log of access
requests to the
servlet service.
8.1.12, “The Servlet
Service Access Log”
on page 418.
trace.*.log
/trace
Log of activity in the
WebSphere server
engine.
8.1.13, “The
WebSphere Engine
Tracing Log” on
page 418.
8.1.2 The JVM Standard Error Log
The JVM standard error log is probably the most useful log of all the WebSphere
logs. In this log the standard error output from the main WebSphere servlet Java
process appears. Standard output and standard error output from the EJS Java
processes are available using the EJS, PNS and LSD tracers (see 8.3.1,
“Tracers” on page 425). The format of the entries in this log depends on the
application writing them. However, stack traces from caught and uncaught Java
exceptions are common. To direct application output to this log, use the methods
412
WebSphere Application Servers: Standard and Advanced Editions
of the static java.lang.System.err object in your Java code. This log is always
enabled.
8.1.3 The JVM Standard Output Log
The JVM standard output log is the second most useful one in WebSphere. The
standard output log contains all of the output written by Java applications to
standard output using the methods of the static java.lang.System.out object. The
format of this log is application dependent. Use this log to inspect debugging and
informational messages from your Java applications writing to System.out. This
log is always enabled.
8.1.4 The IBM HTTP Server Information Log
The IBM HTTP Server information log contains informational and error messages
generated by the IBM HTTP Server included with WebSphere. Each time the
server is re-initialized a new log is generated with a different number used as the
last component of the file name. The major part of each of these logs is taken up
with messages showing the properties with which WebSphere is initialized. This
is useful in confirming the parameter values that a particular invocation of
WebSphere is actually working with.
Figure 383 on page 414 shows some sample output from the information log with
lines containing information on the property values. Each line contains the
following components:
• An ID number specific to the particular invocation of WebSphere. This is the
same number used as a suffix to the log file name.
• A timestamp.
• The word Property.
• The property name and value separated by an = sign.
For information on the property names and what the possible values are, see the
WebSphere documentation at:
http://<Your Server Name>:9527/doc/howto/itedit.html
Problem Determination
413
id 95 Mon May 24 08:04:52 1999 - Property java.classpath =
d:\JDK11~1.7\lib\classes.zip;d:\WEBSPH~1\APPSER~1\classes;d:\WEBSPH~1\APPS
ER~1\web\classes;d:\WEBSPH~1\APPSER~1\lib\jsdk.jar;d:\XMLTOO~1\XML4J_~1\xm
l4j.jar;d:\XMLTOO~1\LOTUSX~2\lotusxsl.jar;D:\SQLLIB\java\db2java.zip
id 95 Mon May 24 08:04:52 1999 - Property ose.server.library.msjvm =
asoutsm.dll
id 95 Mon May 24 08:04:52 1999 - Property ose.outofproc.transport.type =
local
id 95 Mon May 24 08:04:52 1999 - Property java.asyncgc = true
id 95 Mon May 24 08:04:52 1999 - Property ose.library.out.jni = asoutc.dll
id 95 Mon May 24 08:04:52 1999 - Property ose.outofproc.hostname =
localhost
id 95 Mon May 24 08:04:52 1999 - Property java.path = d:\JDK11~1.7\bin
id 95 Mon May 24 08:04:52 1999 - Property server.name = servlet
id 95 Mon May 24 08:04:52 1999 - Property ose.trace.file = trace.PID.log
Figure 383. Sample Output from apache.LOG.INFORM
8.1.5 The IBM HTTP Server Error Log
The IBM HTTP Server error log contains error messages generated by the IBM
HTTP server included with WebSphere. The format and content is similar to that
of the information log (see 8.1.4, “The IBM HTTP Server Information Log” on
page 413), but the messages are restricted to those describing error conditions.
These messages are also included in the information log.
The error log is useful for diagnosing problems where the Web server or the
WebSphere services fail to start for some reason. On Windows NT we frequently
encountered the situation where the NT service database was locked as the
system booted leading to the servlet service not starting and placing the following
message in the log:
id 95 Mon May 24 08:04:52 1999 - Error : nt service data base is locked,
can not start ose.
The solution was to stop and restart the Web server, which then started the
servlet service correctly.
8.1.6 The WebSphere Trace Log
The WebSphere trace log contains the output of the different tracing functions
described in 8.3, “Tracing” on page 424. Each log entry is the result of an event
picked up by one of the tracing monitors and can contain any of the following six
components:
414
WebSphere Application Servers: Standard and Advanced Editions
1.
2.
3.
4.
5.
6.
A timestamp
The name of the tracer that is the source of the event
The ID of the thread that caused the event
The severity level of the tracer message
Any exception generated by the event
The message text
The actual components of each message generated in the log are configured
using the trace output handler settings (see 8.3.4, “Setting Trace Properties
Using the Debug.properties File” on page 428). By default, each message
contains the timestamp, tracer name, severity and message in that order. The
trace log is useful for gathering detailed debugging information about different
WebSphere components in a selective manner. The settings that determine
which events generate messages in the log are configurable. See Table 42 on
page 428 and the following explanatory note number 3 on page 430 for details on
how to configure this using the levelThreshold setting.
8.1.7 The Servlet Admin Service Error Log
The servlet admin service error log contains messages that relate to errors that
occur during the execution of the WebSphere administration service. This
includes errors that may occur while running any tracing programs (see 8.3,
“Tracing” on page 424). Errors encountered by individual servlets are placed in
the servlet service error log (see 8.1.10, “The Servlet Service Error Log” on page
417). The format of each message is a timestamp followed by the error message.
Exceptions are handled slightly differently in that the entire exception stack trace
is included surrounded by message lines that delineate the start and end of the
exception block. Figure 384 on page 416 shows an exception generated during
tracing along with the enclosing exception block start and end lines.
The servlet admin service error log can be used to help diagnose errors
encountered while running the WebSphere administration application.
Problem Determination
415
[April 20, 1999 10:05:28 PM EDT] START EXCEPTION BLOCK
[April 20, 1999 10:05:28 PM EDT] java.net.SocketException: Socket write
failed: 10053
java.net.SocketException: Socket write failed: 10053
at java.net.SocketOutputStream.write(SocketOutputStream.java:91)
at sun.servlet.http.HttpOutputStream.writeOut(HttpOutputStream.java:485)
at
at sun.servlet.http.HttpOutputStream.flush(HttpOutputStream.java:345)
at java.io.OutputStreamWriter.flush(OutputStreamWriter.java:230)
at com.sun.server.http.FileServlet.copy(FileServlet.java:447)
at com.sun.server.http.FileServlet.writeResponse(FileServlet.java:338)
at com.sun.server.http.FileServlet.sendResponse(FileServlet.java:267)
at com.sun.server.http.FileServlet.service(FileServlet.java:192)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:588)
at
com.sun.server.ServletManager.callServletService(ServletManager.java:1317)
at
com.sun.server.ProcessingState.invokeTargetServlet(ProcessingState.java:43
4)
at
com.sun.server.http.HttpProcessingState.execute(HttpProcessingState.java:9
3)
at com.sun.server.http.stages.Runner.process(Runner.java:77)
at com.sun.server.ProcessingSupport.process(Compiled Code)
at com.sun.server.Service.process(Service.java:229)
at
com.sun.server.http.HttpServiceHandler.handleRequest(HttpServiceHandler.ja
va:350)
at
com.sun.server.http.HttpServiceHandler.handleRequest(HttpServiceHandler.ja
va:210)
at com.sun.server.HandlerThread.run(HandlerThread.java:154)
[April 20, 1999 10:05:29 PM EDT] END EXCEPTION BLOCK
Figure 384. An Exception Recorded in the Servlet Admin Service Error Log
8.1.8 The Servlet Admin Service Event Log
The servlet admin service event log contains informational messages concerned
with the running of the WebSphere administration service. The administration
service uses a number of servlets to perform WebSphere administration tasks. It
does not contain messages related to the running of individual servlets; these are
recorded in the servlet service event log (see 8.1.11, “The Servlet Service Event
Log” on page 418). The format of this log is the same as the format of the servlet
admin service error log described in 8.1.7, “The Servlet Admin Service Error Log”
on page 415.
The servlet admin service event log can be used to monitor the execution of the
WebSphere administration service during WebSphere administration.
8.1.9 The Servlet Admin Service Access Log
The servlet admin service access log contains a record for each HTTP request
made to the WebSphere administration application as well as any codes
returned. It includes requests for all files associated with the servlet
416
WebSphere Application Servers: Standard and Advanced Editions
administration service. The log follows the same format as a standard Web server
access log (see Figure 385 for an example):
9.24.104.154 - admin [13/Apr/1999:13:09:09 -0400] "POST /servlet/admin
HTTP/1.0" 200 1157
9.24.104.154 - admin [13/Apr/1999:13:09:09 -0400] "POST /servlet/admin
HTTP/1.0" 200 912
9.24.104.154 - admin [13/Apr/1999:13:09:10 -0400] "POST /servlet/admin
HTTP/1.0" 200 912
9.24.104.154 - - [13/Apr/1999:13:10:16 -0400] "GET
/doc/whatis/icusrprf.html HTTP/1.0" 200 5175
9.24.104.154 - - [13/Apr/1999:13:10:46 -0400] "GET /doc/howto/itxml4j.html
HTTP/1.0" 200 56626
9.24.104.154 - - [13/Apr/1999:13:10:46 -0400] "GET /doc/howto/asv2.css
HTTP/1.0" 200 2765
9.24.104.154 - - [13/Apr/1999:13:11:22 -0400] "GET /doc/whatis/icxml4j.html
HTTP/1.0" 200 28803
9.24.104.154 - - [13/Apr/1999:13:15:26 -0400] "GET /doc/howto/itxml4j.html
HTTP/1.0" 200 56626
9.24.104.154 - - [13/Apr/1999:13:15:26 -0400] "GET /doc/howto/asv2.css
HTTP/1.0" 200 2765
9.24.104.154 - - [13/Apr/1999:13:17:40 -0400] "GET
/doc/howto/itbullmsg.html HTTP/1.0" 200 6718
9.24.104.154 - - [13/Apr/1999:13:17:40 -0400] "GET /doc/howto/asv2.css
HTTP/1.0" 200 2765
9.24.104.154 - - [13/Apr/1999:13:27:12 -0400] "GET /doc/howto/itpubsv.html
HTTP/1.0" 200 8264
9.24.104.154 - - [13/Apr/1999:13:27:12 -0400] "GET /doc/howto/asv2.css
HTTP/1.0" 200 2765
9.24.104.154 - - [13/Apr/1999:13:27:42 -0400] "GET /doc/howto/itpubsv.html
HTTP/1.0" 200 8264
9.24.104.154 - - [13/Apr/1999:13:27:42 -0400] "GET /doc/howto/asv2.css
HTTP/1.0" 200 2765
Figure 385. Sample Output from the Administration Service Access Log
The servlet admin service access log can be used to monitor the access requests
that are sent to the WebSphere administration application.
8.1.10 The Servlet Service Error Log
The servlet service error log contains error information generated by the
WebSphere servlet service in attempting to run servlets. It includes both errors
pertaining to particular servlets and information pertaining to the servlet service
itself. System.out and System.err output that is produced by servlets is placed in
the JVM standard output (see 8.1.3, “The JVM Standard Output Log” on page
413) and standard error (see 8.1.2, “The JVM Standard Error Log” on page 412)
logs respectively.
The format of this log is identical to that used by the servlet admin service event
and error logs (see 8.1.7, “The Servlet Admin Service Error Log” on page 415).
This log can be used to help diagnose both the cause of servlet failures and
failures of the servlet service. This log will record any exceptions thrown by
WebSphere in trying to load or configure servlets (see 3.1, “How to Deploy and
Problem Determination
417
Configure a Servlet” on page 91) so it is a good place to start diagnosing these
sorts of problems. It will also contain information relevant to determining the
causes of servlet service start failures.
8.1.11 The Servlet Service Event Log
The servlet service event log parallels the format of the admin service event log
(see 8.1.8, “The Servlet Admin Service Event Log” on page 416) but the
information contained within it pertains to servlets executing in WebSphere and to
the servlet service itself. It lets you see when servlets are loaded, when they are
called, and with what parameters they are called. This is useful in trying to
diagnose why a particular servlet is failing under certain conditions but not others,
since it shows you how it is being called. You may want to add some debug writes
to your servlet that includes a timestamp so you can match the debug output that
your servlet is producing in standard output or standard error to the messages in
the event log which already have a timestamp.
8.1.12 The Servlet Service Access Log
The servlet service access log will generally be empty. See your Web server’s
access log for file access information, or use one of the servlet tracers described
in 8.3.1, “Tracers” on page 425.
8.1.13 The WebSphere Engine Tracing Log
The WebSphere engine tracing log shows detailed information about the activity
on the server. Each action that the server takes is recorded. The format of this log
is a timestamp and a message.
This log is good for diagnosing classpath problems, since it provides detailed
information on which directories and JAR files have been found and verified in the
classpath.
This log is not enabled by default. To enable it you need to edit the <Server
Root>/properties/bootstrap.properties file and set the ose.trace.enabled property
near the top of the file to true and then stop and restart WebSphere.
8.2 The Application Server Debug Console
The application server debug console provides a mechanism by which the
WebSphere Application Server can be monitored either on an ongoing basis or
for debugging purposes. It provides a similar set of tools to those provided under
Server Execution Analysis in the WebSphere administration interface with the
important inclusion of a console monitor (see 8.2.2, “The Server Console
Monitor” on page 419). In this section we look at how to enable the application
server debug console. Then we show the different functions provided and what
they are used for.
8.2.1 Enabling the Console
To enable the application server debug console you must edit the <Server
Root>/properties/server/servlet/debug.properties file and change the line:
debug.server.console.enabled=false
to
418
WebSphere Application Servers: Standard and Advanced Editions
debug.server.console.enabled=true
In the default file that ships with WebSphere 2.02 Advanced, this line occurs at
line 32 in the file. After making this change and saving the file, stop the
WebSphere Servlet Service and the HTTP server and then restart them to
activate the console. The window shown in Figure 386 on page 419 should
appear (minus the output) when the WebSphere Servlet Service starts. If there is
a problem then you should check the log files for any possible errors (see 8.1,
“WebSphere Log Files” on page 411).
8.2.2 The Server Console Monitor
The server console monitor (shown in Figure 386 on page 419) provides a facility
for the monitoring of the output from the different WebSphere tracers (see 8.3,
“Tracing” on page 424 for a description of the different tracers) as well as any
output sent to System.out or System.err by Java programs. The format of the
entries shown in the console depends on the source of the data. Entries from
System.out and System.err are in the format specified by the generating program.
Output from the WebSphere tracers is in the format specified in the
debug.properties file (see 8.3.4, “Setting Trace Properties Using the
Debug.properties File” on page 428 for details) but by default includes the name
of the tracer producing the message, a number indicating the severity, and the
message text.
Figure 386. The Debug Console Server Console Monitor Page
During execution the console monitor automatically displays output from the input
sources it monitors. If several of the tracers are enabled it can produce significant
quantities of output. To clear the current output, click the Clear button at the
bottom of the page.
Problem Determination
419
8.2.3 The Trace Enabler Page
The trace enabler page provides the ability to modify the settings for the
WebSphere tracers. These settings take precedence over the settings present in
the debug.properties file (see 8.3.4, “Setting Trace Properties Using the
Debug.properties File” on page 428). The trace enabler page is shown in Figure
387:
Figure 387. The Debug Console Trace Enabler Page
Each tracer can be turned on by selecting the check box in the Tracer Name
column or alternatively all of the tracers can be turned on or off by clicking the
Enable All or Disable All buttons below the column (not shown in the figure).
Once a tracer has been turned on, its output must be directed to one of the three
trace output destinations for it to be produced. More output destinations will be
available if user-defined output destinations have been defined (see 8.3.6,
“Creating Your Own Trace Output Handlers” on page 431). This can be
accomplished by selecting or deselecting the check boxes in one or more
columns to select the desired output destination(s), or by clicking the Direct All
or Direct None buttons below the columns. The LogFile output destination will
send output to the file defined in the trace.handler.LogFile.param.filename
property of the debug.properties file which is <Server
Root>/logs/websphere_trace.log by default. The console output destination will
route messages to the server debug console monitor page described in 8.2.2,
“The Server Console Monitor” on page 419. The SocketServer output destination
directs output to the console provided by the socket server application (see 8.3.3,
“Running the Socket Server Trace Console” on page 427). It is important to note
that unless both check boxes are enabled, one to enable the tracer and one to
direct output to the desired destination, no output will appear.
420
WebSphere Application Servers: Standard and Advanced Editions
8.2.4 The Exceptions Monitor
The exceptions monitor provides a facility for inspecting the stack traces of Java
exceptions thrown by WebSphere or by user applications running under
WebSphere. This method of monitoring exceptions may be preferable to some but
we found that monitoring exception data in the log files also worked well and
almost never referred to this page. The exceptions monitor is shown in Figure
388:
Figure 388. The Debug Console Exceptions Monitor Page
Each line in the upper box shows one exception that occurred giving the failing
class name, type of exception and the timestamp when the exception occurred.
To see the stack trace for a given exception, select it in the upper box. The lower
box displays the stack trace for the given exception.
The exception display is not dynamic by default. To update the display either click
the Reload button to refresh the list once or the Start button to automatically
update the display at an interval specified by the Specify Interval slider at the top
of the screen. Once automatic update has been selected, it can be stopped by
clicking the Stop button. The time to the next update is shown in the small pie
chart at the top right part of the screen.
Automatic update carries across the other monitors so that once it has been
enabled for one monitor page, it continues to update all other monitor pages even
when the current page is not showing. The stop button on any page will stop the
update for all pages.
Select the Clear button to remove all current exceptions from the display.
Problem Determination
421
8.2.5 The EJS Status Monitor
The EJS status monitor provides a basic check on the performance and status of
the three Java processes that make up WebSphere Enterprise Java Services
(see Figure 389). If any of these processes are down, then it may be worth
enabling one or both of the process-specific tracers using the debug.properties
file (see 8.3.4, “Setting Trace Properties Using the Debug.properties File” on
page 428) and attempting to restart the server to see what messages are
produced. The relevant tracer names are prefixed with LSD_ for the Location
Service Daemon, PNS_ for the Persistent Name Service and EJS_ for the EJS
runtime. Each process has two tracers, one for standard output suffixed with
stdout and one for standard error suffixed with stderr.
Figure 389. The Debug Console EJS Status Monitor Page
8.2.6 The Resource Usage Monitor
This monitor should be used as a basic performance monitoring tool instead of a
debugging aid. It lets you see what load the server is processing at any given
time. You may be able to detect memory leaks by watching the memory graph
over time.
422
WebSphere Application Servers: Standard and Advanced Editions
Figure 390. The Debug Console Resource Usage Monitor Page
8.2.7 The Loaded Servlets Monitor
The loaded servlets monitor allows you to see which servlets are loaded and
what they are doing at any given time. Figure 391 on page 424 shows this page
and a number of details for three loaded servlets. The fields and operations on
this page are identical to those described in 3.1.4, “Monitoring Servlets” on page
116.
Problem Determination
423
Figure 391. The Debug Console Loaded Servlet Monitor Page
8.2.8 The Sessions Monitor
The sessions monitor page provides the same information that is provided by the
WebSphere administration interface Server Execution Analysis tools. See 5.1.2.2,
“Monitoring HttpSession/IBMSessionData Object” on page 225 for an explanation
of the information contained on this page.
8.2.9 The Pooled Connections Monitor
The pooled connections monitor page provides the same information that is
provided by using the WebSphere administration interface Server Execution
Analysis tools. See 5.4.2.1, “Monitoring the Connection Manager” on page 308
for an explanation of the information contained on this page.
8.3 Tracing
The WebSphere trace subsystem is based on the idea of tracers and trace output
handlers. WebSphere defines a number of tracers that trace events for certain
processes in the WebSphere system. Each tracer can then be associated with
one or more trace output handlers that receive the tracer events and record or
display them.
WebSphere also allows you to define your own tracers and tracer output handlers
and link them to the WebSphere tracing subsystem. See 8.3.5, “Creating Your
Own Tracers” on page 430 and 8.3.6, “Creating Your Own Trace Output Handlers”
on page 431 for further details.
424
WebSphere Application Servers: Standard and Advanced Editions
8.3.1 Tracers
Table 39 lists the standard tracers that appear by default in the GUI list of tracers
provided by the WebSphere tracing subsystem:
Table 39. Default Tracers Available in WebSphere
Tracer Name
Message Content
ActiveDBConns
Messages from the database connection pooling
subsystem.
ActiveSessions
Messages from the session manger relating to
active sessions.
ClassLoader
Messages from the dynamic class loader for
servlets.
Controller
Messages from the EJS managing process.
DebugConsole
Messages relating to the debug console GUI.
DebugSupport
Messages relating to the activation and
deactivation of debug support.
EJS_stderr
Standard error output from the EJS container
process.
EJS_stdout
Standard out output from the EJS container
process.
EnableTrace
Messages relating to the Enable Trace page of the
debug console.
IBMSessionContextImpl
Messages from the session manager.
LSD_stderr
Standard error messages from the EJS location
service daemon process.
LSD_stdout
Standard output messages from the EJS location
service daemon.
LoadedServlets
Messages relating to the loaded servlets page of
the debug console.
MonEJSProcs
Messages relating to the EJS Status page of the
debug console.
MonExceptions
Messages relating to the Monitor Exceptions page
of the debug console.
PNS_stderr
Standard error output from the EJS persistent
naming service.
PNS_stdout
Standard output from the EJS persistent naming
service.
ResourceUsage
Messages relating to the resource usage page of
the debug console.
SEEngine
Request response data messages from the
servlet engine.
ServiceMonitoringAdmin
Messages relating to the Server Execution
Analysis portion of the WebSphere Administration
GUI.
Problem Determination
425
Tracer Name
Message Content
adminservice.servlets
Messages relating to the life cycle of servlets used
in the servlet administration GUI.
httpservice.servlets
This tracer seldom produces any output.
servletservice.servlets
Messages relating to the servlet lifecycle of user
servlets.
The tracers shown in Table 39 are generally available in the GUI interface at
WebSphere startup time. In addition to these there are a number of other tracers
that may appear in the list depending upon whether or not the code that registers
them has been executed. Table 40 lists these tracers:
Table 40. Other Tracers Provided by WebSphere
Tracer Name
NativeServerEntry
NativeServerConnection
AppServerConnection
IBMConnMgrServlet
IBMConnMgr
Message Content
These two tracers trace the low level
connections between the C native code part
of WebSphere and the Java engine.
These tracers are all associated with the
IBM connection manager. If you need to
trace connection manager interactions, we
suggest that you turn all of these on.
IBMConnPool
IBMConnection
IBMConnPoolSpec
IBMConnSpec
IBMJdbcConn
IBMJdbcConnPool
IBMJdbcConnSpec
IBMConnMgrUtil
IBMDirMgrAdmin
A rough guide to the usefulness of a particular tracer is given by whether or not
its name appears in the groups defined in the debug.properties file. If a tracer
name appears, then it will probably provide useful output.
Each tracer produces messages that may consist of up to six components:
1. A timestamp
2. The tracer name
3. The level of the message
4. The message
5. The thread ID of the thread creating the message
6. Any exception thrown that relates to the event
426
WebSphere Application Servers: Standard and Advanced Editions
The particular components for each message are determined by the format
property of the trace output handler used. See 8.3.4, “Setting Trace Properties
Using the Debug.properties File” on page 428 for more information.
Each message also has a level from 1 to 4. The levels are meant to reflect
increasing levels of detail to allow filtering of the messages. The output handlers
display messages less than or equal to their level Threshold parameter (see
8.3.4, “Setting Trace Properties Using the Debug.properties File” on page 428 for
more information). This means that messages that are generated for level 1 have
fewer details than ones that are set to level 4, and that there will be fewer level 1
messages generated. Another way of looking at this is that level 1 messages
represent more serious events that all trace output handlers will want to display,
whereas level 4 messages represent informational events that may or may not be
of interest.
8.3.2 Trace Output Handlers
Table 41 shows the three trace output handlers provided with WebSphere:
Table 41. Trace Output Handlers Provided With WebSphere
Trace Output Handler Name
Description
LogFile
Output handler that writes trace information
to a file specified in the debug.properties file.
Console
Output handler that writes trace output to the
console page of the debug console.
SocketServer
Output handler that writes output to a socket
server that may be running on a remote
machine.
8.3.3 Running the Socket Server Trace Console
In order to see the output from the SocketServer trace output handler you need to
run the socket server trace console on the machine that you wish to view or log
the trace output on. To accomplish this you need to run the Java class
com.ibm.servlet.debug.SETraceServer and perform the following steps:
1. The com.ibm.servlet.debug.SETraceServer class can be found in the <Server
Root>\lib\ibmwebas.jar file. You need to copy this file to the machine you wish
to trace from and make sure that the JAR file is included in the java classpath
from that system.
2. Set the trace.handler.SocketServer.param.server and
trace.handler.SocketServer.param.port parameters in the debug.properties file
to the address of the tracing machine and the port number you want to use for
tracing on the tracing machine respectively. The port number defaults to 9991
on the server, so use this value unless the tracing machine already has
something running on that port. See 8.3.4, “Setting Trace Properties Using the
Debug.properties File” on page 428 for more information on how to
accomplish this.
3. Stop and restart WebSphere.
4. On the tracing machine (as opposed to the traced machine) execute the
SETraceServer.class in the Java environment on that machine. On machines
with command lines, this can be accomplished by typing the following at a
command prompt:
Problem Determination
427
java com.ibm.servlet.debug.SETraceServer <port number> <file name>
where <port number> is the number of the port the server will listen to receive
trace messages that you specified in the
trace.handler.SocketServer.param.port parameter in step 2, and <file name> is
the name of a file to write trace output to in addition to writing it to the console.
Both of these parameters are optional. If they are omitted, then the port
number defaults to 9991 and no file output is produced. On machines without
a command line (such as the Apple Macintosh), use the functions on that
platform to set these command line parameters.
You should see messages like those shown in Figure 392, depending upon the
parameters you specified:
Starting the WebSphere Trace Server.
Creating server socket on port 8888.
Sending output to the screen and to the file d:\temp\trace.log.
Figure 392. Messages Output by the Socket Server
5. You should now be able to enable tracer output to the SocketServer and have
it appear as a message on the socket server console as well as logged to the
file that you specified in step 4.
8.3.4 Setting Trace Properties Using the Debug.properties File
The <Server Root>/properties/server/servlet/debug.properties file is the file that
WebSphere reads at startup to determine the configuration of the trace and
debug subsystems. Some of the trace subsystem options can only be set in this
file, while others take their defaults from here.
The debug.properties file allows more granular control over tracers by allowing
them to be assigned to trace groups. Each group can be turned on or off and
assigned one or more output handlers to receive output from the group. Tracers
can also be manipulated on a global basis by using the traceAll settings.
Table 42 lists the possible trace properties in the debug.properties file:
Table 42. Trace Properties Available in the debug.properties File
Property Name
428
Description
trace.traceAll.state
Set to on to enable all tracers by default.
trace.traceAll.handlers
Space separated list of trace output handlers to receive trace
events when global tracing is turned on.
trace.groups
Space separated list of trace group.
trace.group.<group
name>.tracers
Space separated list of tracers to be included in the tracer
group <group name>.
trace.group.<group
name>.state
Set to on to enable all tracers for the group <group name>.
trace.group.<group
name>.handlers
Space separated list of trace output handlers to receive trace
events when tracing for the group <group name> is turned
on.
trace.tracers
Space separated list of individual tracer names.
WebSphere Application Servers: Standard and Advanced Editions
Property Name
Description
trace.group.<tracer
name>.state
Set to on to enable tracing for the tracer <tracer name>.
trace.group.<tracer
name>.handlers
Space separated list of trace output handlers to receive trace
events when tracing for the tracer <tracer name> is turned
on.
trace.handlers
Space separated list of trace output handlers.
trace.handler.<handler
name>.class
Name of the Java class providing the handler functions for
output handler <handler name>.
trace.handler.<handler
name>.params
Space separated list of parameters that handler <handler
name> accepts.
trace.handler.<handler
name>.param.<parameter
name>
Value for the parameter <parameter name> for the handler
<handler name>.
trace.handler.<handler
name>.param.format
Integer value from 0 to 4 specifying which items are to be
placed in the trace message.
trace.handler.<handler
name>.param.levelThreshol
d
Integer value from 1 to 4 which specifies the maximum level
of messages to be displayed by handler <handler name>.
trace.handler.LogFile.param
.filename
Name of the file that the LogFile output handler uses to place
trace output in.
trace.handler.SocketServer.
param.server
Name or IP address of the host running the socket server for
the SocketServer output handler.
trace.handler.SocketServer.
param.port
Port address for the socket server on the host running the
socket server for the SocketServer output handler.
Notes:
1. Tracer names, group names, handler names and parameter names must all
contain no internal spaces, since the lists of these names are space delimited.
Use underscores instead.
2. The format setting for output handlers specifies the message format as shown
in Table 43:
Table 43. Trace Output Handler Format Settings
Format Setting
Resulting Message Components
0
Displays Timestamp, ThreadID, Tracer
Name, Message, Exception
1
Displays Timestamp, Tracer Name,
Message, Exception
2
Displays Timestamp, Tracer Name,
Message
3
Displays Tracer Name, Message
4
Displays Just the Message
User-defined output handlers may ignore or change these formats.
Problem Determination
429
3. The levelThreshold setting specifies the maximum level of trace messages
that are displayed by the output handler. If the threshold is 3, then only
messages of levels 1, 2 and 3 will be seen. User-created output handlers may
or may not respect this setting.
8.3.5 Creating Your Own Tracers
Note: This API will change in Version 3.0 of WebSphere. Code that you create
using these instructions will have to be rewritten to work correctly with Version
3.0. There is a new IBM strategic way of handling tracing that will be included in
WebSphere Version 3.0.
If the tracers available under WebSphere do not suit the needs of your application
debugging, it is possible to create your own tracers to produce debugging output
using the WebSphere tracing infrastructure. To create user-defined tracers in
V2.02 perform the following steps:
1. In your application code declare a variable of type
com.ibm.servlet.debug.SETracer. This type can be found in the file <Server
Root>\lib\ibmwebas.jar and in the IBM VisualAge for Java WebSphere test
environment. It makes sense to declare the variable as static unless you want
different tracer names for different instances of your class. If the class is a
servlet then by declaring the variable static the tracer will be available as soon
as the servlet is loaded.
2. Initialize the variable by calling the SETracer constructor with two string
arguments. The first argument is the name of the tracer that will appear in the
trace output. This name must not contain any spaces. The second argument is
the description of the tracer. For example, the following line both declares and
initializes a static tracer instance called testTracer:
private static com.ibm.servlet.debug.SETracer testTracer = new
com.ibm.servlet.debug.SETracer("My_Tracer","My Test Tracer");
If the variable is declared as static, put this code in the static section of your
class outside the methods.
3. In your code you can then call one of the trace methods on SETracer to write a
trace message. The following is a list of all of the different methods:
public
public
public
public
void
void
void
void
trace(String
trace(String
trace(String
trace(String
msg)
msg, int level)
msg, Exception exc)
msg, Exception exc, int level)
Table 44 lists the possible parameters. Parameters omitted from the parameter
list on a particular trace method invocation take the default value.
Table 44. Possible Parameters for the SETracer trace Method
Parameter Name
430
Description
Default Value
msg
The message that is to be associated with
this tracing event.
N/A
level
The level of this message. Level 4 messages
should represent more detail than level 1
messages.
1
exc
The exception associated with this event.
null
WebSphere Application Servers: Standard and Advanced Editions
4. When running your code you will need to register the tracer with the tracer
manager first before the tracer becomes visible on either the debug console
Enable Trace page or the Trace page of the WebSphere administration
interface. To do this, you must execute the code that calls the tracer
constructor. If the code to perform the initialization is static and your class is a
servlet, loading the servlet will achieve this. Otherwise, you may need to
execute the code once to register the tracer with the tracer manager before it
is visible in the interface.
Note: Once a tracer is registered with the tracer manager, you will not be able
to register a new instance of the tracer class with the same name and have it
work correctly. This is why it is better to have the tracer registration occur in
static code. If you need to have the piece of code that registers the tracer
executed a second time you have to stop and restart WebSphere before
tracing will work again. This is particularly relevant to servlet reloading.
5. After the tracer has been constructed, you should be able to click the Refresh
button on the tracer page of either the debug console or the WebSphere
administration interface and see your tracer added to the list. You can then
manipulate it as you would other tracers, with one important exception. As the
tracer class is not loaded at WebSphere startup time, it will not be available for
loading through the use of the debug.properties file.
8.3.6 Creating Your Own Trace Output Handlers
Note: This API will change in Version 3.0 of WebSphere. Code that you create
using these instructions will have to be rewritten to work correctly with Version
3.0. There is a new IBM strategic way of handling tracing that will be included in
WebSphere Version 3.0.
The WebSphere trace utilities makes use of three classes to provide output
handlers for the trace messages. These three handlers provide output to the
console, to a log file and to a socket server. If the behavior of these handlers is
not to your liking, it is possible to create user-defined output handlers to process
trace messages.
Figure 393 on page 432 shows the code for a simple trace output handler.
Problem Determination
431
import java.io.*;
import java.util.*;
import com.ibm.servlet.debug.*;
public class TestOutputHandler extends SETracerOutputHandler
{
private String myParameter;
public TestOutputHandler()
{
super();
}
/**
* This method was created in VisualAge.
* @return java.lang.String
*/
public String getMyParameter() {
return myParameter;
}
public void init(Hashtable params){
super.init(params);
setMyParameter((String)params.get("myParameter"));
}
/**
* This method was created in VisualAge.
* @param newValue java.lang.String
*/
public void setMyParameter(String newValue) {
this.myParameter = newValue;
}
/**
* This method was created in VisualAge.
* @param timestamp java.lang.String
* @param threadID java.lang.String
* @param tracerName java.lang.String
* @param message java.lang.String
* @param exc java.lang.Throwable
* @param severity int
*/
public void write(String timestamp, String threadID, String tracerName,
String message, Throwable exc, int severity) {
System.out.println(getMyParameter() + "\t" + timestamp + "\t" +
tracerName + "\t" + severity + "\t" + threadID + "\t" + message);
if (exc != null) {
System.out.println("exc: ");
exc.printStackTrace(System.out);
}
}
}
Figure 393. A Simple Trace Output Handler
The following points are worth noting:
432
WebSphere Application Servers: Standard and Advanced Editions
1. The class inherits from com.ibm.servlet.debugSETracerOutputHandler, which
is the base class for WebSphere output handlers. This class is contained in
the <Server Root>\lib\ibmwebas.jar file and also in the VisualAge for Java
WebSphere test environment. This is the type that WebSphere expects in its
list of output handlers so user-defined output handlers need to extend this
class.
2. The class declares a private String variable myParameter in order to illustrate
how tracer configuration information can be passed to a handler. Getter and
setter methods are defined for this variable. In a more complex output handler
there may be a number of parameters specified.
3. The class overrides the init(Hashtable) method to capture the new parameter
value from the hashtable of parameters passed to it by WebSphere. It also
calls the superclass init method to take care of the standard parameters. The
superclass init method should always be called by a subclass that overrides it.
Step 2 on page 434 discusses how to specify user-defined parameter values
in the debug.properties file so that they get included in the input hashtable.
4. The main method that needs to be overridden is the write method. This is the
method that is called by WebSphere to notify the output handler that a trace
event has occurred. The parameters for this method give information about the
trace event:
Table 45. Parameters to the Write Method for a Trace Output Handler
Name
Description
Example
timeStamp
The date and time that the trace event
occurred.
6/2/99 11:42:58 AM
EDT
threadID
The thread identifier of the thread that
caused the event.
Thread[main,5,main
]
tracerName
The name of the WebSphere tracer that
generated the event.
SEEngine
message
The actual message generated by the tracer.
SEEngine: created
successfully
exc
Any exception generated by this event. This
value may be null as not all events generate
exceptions.
N/A
severity
The level of this event. Event levels can
range from 1 to 4.
1
5. In the write method no attempt is made to handle the filtering and format
options specified in the input parameters. All messages are displayed and all
items are printed. If you need to get access to these parameters you can call
the getLevelThreshold() method which returns the int level threshold setting
and the getFormat() method which returns the int format setting. See the
comments in the debug.properties file for a description of what these numbers
are supposed to mean.
6. In the write method of this handler the trace information is simply written to
standard output, which means that it ends up in the standard output log as
well as appearing on the debug console if enabled. It is possible to redirect the
output to a remote socket server or to a systems management console, or to
process the output in other ways from this method. Note that the exception
information is only printed if it is not null.
Problem Determination
433
To enable the output handler it needs to be defined in <Server
Root>\properties\server\servlet\debug.properties. To add an output handler to
debug.properties perform the following steps:
1. Find the definition for trace.handlers near the bottom of the file and add the
name of the new output handler to the end. For example, to add a new output
handler called Test, the line would look like this:
# Enabled Output Handlers
trace.handlers=Console LogFile SocketServer Test
Note that the handler name should not contain any spaces.
2. Create a properties section for the new handler that looks something like the
following:
# Test Handler Properties
trace.handler.Test.class=TestOutputHandler
trace.handler.Test.params=myParameter format levelThreshold
trace.handler.Test.param.myParameter=Hello World
trace.handler.Test.param.format=2
trace.handler.Test.param.levelThreshold=4
Each property must be prefixed with trace.handler.<your handler name>.
where <your handler name> is the name of the handler that you defined in
step 1.The class parameter specifies the class name of the handler, which
must be in the application server classpath. The params parameter specifies
the names of the other parameters that WebSphere will look for to initialize
your class. These parameter names and the corresponding values will be
placed into a hashtable that will be passed to the init method of your output
handler code. The levelThreshold and format parameters must be present
(see the comments in the debug.properties file for the definitions of these
parameter values). User-defined parameter values can be added as needed.
Notice in this example that the myParameter value used in the sample code in
Figure 393 on page 432 is given the value "Hello World".
3. Stop and restart the WebSphere servlet service to make these changes
active.
After completing these steps you should be able to see the new trace output
handler in the Enable Trace page on the debug console and on the Trace page in
the Server Execution Analysis page of the WebSphere administration interface.
Figure 394 on page 435 shows the Enable Trace page from the debug console
showing the new Test output handler column.
434
WebSphere Application Servers: Standard and Advanced Editions
Figure 394. The Debug Console Showing a Custom Output Handler
8.4 The Server Execution Analysis Pages
The WebSphere administration GUI includes a number of pages dedicated to the
monitoring and debugging of the WebSphere system. These pages utilize the
same Java applets that the debug console utilizes and thus work the same way.
Table 46 lists the Server Execution Analysis pages that have corresponding
debug console pages and cross references to the sections that discuss them:
Table 46. Server Execution Analysis
Server Execution
Analysis Page Name
Debug Console Page
Name
References to Book Sections
Active Sessions
Sessions
8.2.8, “The Sessions Monitor” on
page 424.
DB Pool Connections
Pool Connections
8.2.9, “The Pooled Connections
Monitor” on page 424.
EJS Status
EJS Status
8.2.5, “The EJS Status Monitor” on
page 422.
Exceptions
Exceptions
8.2.4, “The Exceptions Monitor” on
page 421.
Loaded Servlets
Loaded Servlets
8.2.7, “The Loaded Servlets
Monitor” on page 423.
Problem Determination
435
Server Execution
Analysis Page Name
Debug Console Page
Name
References to Book Sections
Resource Usage
Resource Usage
(The Server Execution
Analysis Page adds a
tabular view of the data
not found in the debug
console)
8.2.6, “The Resource Usage
Monitor” on page 422.
Trace
Enable Trace
8.2.3, “The Trace Enabler Page” on
page 420.
The following sections describe the other pages in the Server Execution Analysis
pages.
8.4.1 The JVM Debug Page
The JVM debug page controls the settings relating to attaching a remote
debugger, such as the jdb debugger provided with the JDK, to the main
WebSphere JVM. This allows you to run WebSphere as if you had typed java
-debug to run the WebSphere main JVM. For more details, see:
http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/index.html
8.4.2 The Settings Pane
The settings pane (See Figure 395 on page 437) allows you to control the
settings for JVM remote debugging. For details on the fields on this page, see:
http://<Your Server Name>:9527/admin/webexec/WASHelp/monitor.htm#s
436
WebSphere Application Servers: Standard and Advanced Editions
Figure 395. The JVM Debug Settings Pane
8.4.2.1 The Output Pane
The output pane (see Figure 396 on page 438) allows you to control the contents
of the debug output from the WebSphere JVM as well as allowing you to enable
the debug console. For details on the fields on this page, see
http://<Your Server Name>:9527/admin/webexec/WASHelp/monitor.htm#o
Problem Determination
437
Figure 396. The JVM Debug Settings Output Pane
8.4.3 The Error Log Settings Page
The error log settings page (see Figure 397 on page 439) allows you to configure
the settings and disposition of the WebSphere servlet error logs (see 8.1.10, “The
Servlet Service Error Log” on page 417). The fields on this page are described at:
http://<Your Server Name>:9527/admin/webexec/WASHelp/monitor.htm#fe.
438
WebSphere Application Servers: Standard and Advanced Editions
Figure 397. The Error Log Page
8.4.4 The Event Log Settings Page
The event log settings page (see Figure 398 on page 440) allows you to configure
the settings and disposition of the WebSphere servlet event logs (see 8.1.11,
“The Servlet Service Event Log” on page 418). The fields on this page are
described at:
http://<Your Server Name>:9527/admin/webexec/WASHelp/monitor.htm#fv.
Problem Determination
439
Figure 398. The Event Log Settings Page
8.4.5 The Dump Panel Setup Page
The dump panel setup page allows you to create a snapshot of a WebSphere
system either immediately or automatically when certain conditions are met. The
automatic settings allow dumps to be taken if a servlet hangs or if JVM memory
reaches a certain threshold. This can be useful in helping to diagnose problems
where a servlet or JSP hangs intermittently or has a memory leak.
The dump, which can be logged to a file, includes the following information:
• A snapshot of the server properties in effect when the dump was taken
• A dump of the information for every thread executing in the WebSphere
system
• A snapshot of the state of the servlet runtime including a list of loaded servlets
• A snapshot of any database connections.
• A snapshot of recent exceptions
• Other WebSphere state data
Figure 399 on page 441 shows the Dump Panel Setup page. For more
information on the fields on this page, see:
http://<Your Server Name>:9527/admin/webexec/WASHelp/monitor.htm#mondu4.
440
WebSphere Application Servers: Standard and Advanced Editions
Figure 399. The Dump Panel Setup Page
8.4.6 The Log Output Monitor Page
The log output monitor page provides you with another view of either the JVM
standard error or standard output logs. This page allows you to view a snapshot
of the end of either the standard error or the standard output logs. The amount of
the log that you see is configurable. The snapshot can be set for automatic
update.
This page is useful when you want to monitor the logs on an ongoing basis
without necessarily looking at all of them.
Figure 400 on page 442 shows a section of the log output monitor page. For more
information on the fields on this page see:
http://<Your Server Name>:9527/admin/webexec/WASHelp/monitor.htm#flo
Problem Determination
441
Figure 400. The Log Output Monitor Page
8.5 Miscellaneous Debugging Tools
There are a few other non-WebSphere centric tools that can be used to assist in
debugging your environment.
8.5.1 DB2 CLI Tracing
One method for determining what is going on at a low level with DB2 is to use the
DB2 CLI Trace facility. This will allow you to see exactly what calls the JDBC
driver is or is not making to the database. This technique is more useful in
debugging problems loading DB2 drivers rather than problems with application
logic, since if the JDBC driver is talking to the database successfully the problems
are generally at a higher level. This technique is also useful if detailed debugging
information is required for EJB persistence problems.
To enable DB2 CLI tracing do the following:
1. Edit the file db2cli.ini (it is possible to perform this task using the GUI but the
GUI differs between platforms)
2. Look for a line similar to the following:
[common]
If it does not exist add it to the bottom of the file.
3. Add the following lines after the [common] line:
TRACEFLUSH=1
TRACEFILENAME=<trace file name>
TRACE=1
442
WebSphere Application Servers: Standard and Advanced Editions
4. If one does not already exist, add a section for each database you want to
trace using the following template as a guide:
[<database name>]
PWD=<password>
UID=<userid>
APPENDAPINAME=1
DBALIAS=<ODBC name>
Where the <ODBC name> should probably be the same as the <database name>.
The APPENDAPINAME parameter adds the name of the API being called to
the trace output which gives a much better idea of what is going on.
5. Restart DB2
Figure 401 shows an extract from an actual db2cli.ini file with two databases
defined for tracing, the sample database and the EJS samples database:
[EJS_SAMP]
PWD=swa109r
UID=peterk
APPENDAPINAME=1
DBALIAS=EJS_SAMP
[Common]
TRACEFLUSH=1
TRACEFILENAME=d:\traces\cli\trace.log
TRACE=1
[SAMPLE]
PWD=swa109r
UID=peterk
APPENDAPINAME=1
DBALIAS=SAMPLE
Figure 401. Extract From DB2CLI.INI Showing Tracing Parameters
Figure 402 on page 444 is an extract from a DB2 CLI trace log showing the
allocation of the DB2 environment and an initial connection to a database that
fails due to a missing user ID and password. Typically if you see the
SQLDriverConnect call being executed after the previous calls have succeeded,
then the driver has registered correctly.
Problem Determination
443
SQLAllocEnv( phEnv=&682cd80 )
SQLAllocEnv( phEnv=0:1 )
<--- SQL_SUCCESS
Time elapsed - +1.000000E-002 seconds
SQLSetEnvAttr( hEnv=0:1, fAttribute=SQL_ATTR_ODBC_VERSION, vParam=3,
cbParam=0 )
---> Time elapsed - +0.000000E+000 seconds
SQLSetEnvAttr( )
<--- SQL_SUCCESS
Time elapsed - +2.000000E-002 seconds
SQLGetEnvAttr( hEnv=0:1, fAttribute=Unknown value 1271, pParam=&5eef630,
cbParamMax=0, pcbParam=NULL )
---> Time elapsed - +0.000000E+000 seconds
SQLGetEnvAttr( pParam=0 )
<--- SQL_SUCCESS
Time elapsed - +0.000000E+000 seconds
SQLAllocConnect( hEnv=0:1, phDbc=&5eef7f8 )
---> Time elapsed - +1.823000E+000 seconds
SQLAllocConnect( phDbc=0:1 )
<--- SQL_SUCCESS
Time elapsed - +0.000000E+000 seconds
SQLDriverConnect( hDbc=0:1, hwnd=0:0, szConnStrIn="DSN=sample;UID=;PWD=",
cbConnStrIn=20, szConnStrOut=NULL, cbConnStrOutMax=0, pcbConnStrOut=NULL,
fDriverCompletion=SQL_DRIVER_NOPROMPT )
---> Time elapsed - +2.400000E-001 seconds
SQLDriverConnect( )
<--- SQL_ERROR
Time elapsed - +3.075000E+000 seconds
SQLError( hEnv=0:1, hDbc=0:1, hStmt=0:0, pszSqlState=&5eef724,
pfNativeError=&5eef738, pszErrorMsg=&5eef31c, cbErrorMsgMax=1024,
pcbErrorMsg=&5eef74a )
---> Time elapsed - +2.300000E-001 seconds
SQLError( pszSqlState="42602", pfNativeError=-567, pszErrorMsg="[IBM][CLI
Driver] SQL0567N "SYSTEM" is not a valid authorization ID. SQLSTATE=42602
Figure 402. Extract From a DB2 CLI Trace Log
Note: This trace produces a lot of output. Make sure that you have enough disk
space and consider turning it off after you have diagnosed the problem.
8.5.2 JDBC Output Redirection
Another useful database debugging tool is to redirect the JDBC log stream to
System.out so that it can be captured in the WebSphere standard output logs. To
enable this tracing put the following line in your Java code immediately before
driver registration:
java.sql.DriverManager.setLogStream(System.out);
444
WebSphere Application Servers: Standard and Advanced Editions
If the driver registration is successful you should see something like the output
shown in Figure 403 in the standard output log:
DriverManager.getConnection("jdbc:db2:sample")
trying
driver[className=COM.ibm.db2.jdbc.app.DB2Driver,context=null,COM.ibm.db2.j
[email protected]]
getConnection returning
driver[className=COM.ibm.db2.jdbc.app.DB2Driver,context=null,COM.ibm.db2.j
[email protected]]
Figure 403. Sample JDBC Log Output Showing a Successful DB2 Driver Connection
8.5.3 Running the EJS Processes Stand-alone
Readers familiar with the VisualAge for Java WebSphere test environment will
know that the three EJS server processes can produce large quantities of output
on their operation. Since it is likely that you would need a developer to help review
the output, how can a code developer get access to this output in WebSphere
proper? The answer is twofold.
The first way is to enable the WebSphere EJS tracers for each of the EJS
processes. This has the effect of directing the output produced by these
processes to the trace output destination selected. See 8.3.4, “Setting Trace
Properties Using the Debug.properties File” on page 428 or 8.2.3, “The Trace
Enabler Page” on page 420 for further details.
The second way is to run the EJS processes and the EJS client outside the
WebSphere environment and monitor their output. To accomplish this task
perform the following steps.
1. Create a script file that sets the classpath to include the following directories
and files:
•
•
•
•
•
•
•
•
•
•
<your EJB client JAR file>
<Server Root>\deployedEJBs\<your EJB server JAR file>
<Server Root>\properties\ejs\IBMNameServiceConfig.properties
<Server Root>\lib\ibmwebas.jar
<Server Root>\lib\jst.jar
<Server Root>\lib\jsdk.jar
<Server Root>\lib\xml4j.jar
<Server Root>\lib\databeans.jar
<Server Root>\lib\ejs.jar
<Database Home>\<JDBC driver files>
Call this file setcpath and make it an executable file (use a .bat extension for
Windows NT and set the appropriate execute permissions on AIX). Figure 404
on page 446 shows a sample setcpath.bat file for Windows NT.
Problem Determination
445
set WASL=D:\WebSphere\AppServer\lib
set DEPL=D:\WebSphere\AppServer\deployedEJBs
set CLASSPATH=%CLASSPATH%;D:\Data\MyHelloClient.jar;
set CLASSPATH=%CLASSPATH%;%DEPL%\MyHelloServer.jar;
set
CLASSPATH=%CLASSPATH%;D:\WebSphere\AppServer\properties\ejs\IBMNameService
Config.properties
set
CLASSPATH=%CLASSPATH%;%WASL%\ibmwebas.jar;%WASL%\jst.jar;%WASL%\jsdk.jar;%
WASL%\xml4j.jar
set CLASSPATH=%CLASSPATH%;%WASL%\databeans.jar;%WASL%\ejs.jar
set CLASSPATH=%CLASSPATH%;D:\sqllib\java\db2java.zip
Figure 404. Batch File to Set the Classpath for EJS Standalone Execution on NT
2. Create another file called startns1 (again with the appropriate attributes to
make it executable on your operating system) and place the following
executable command in the file all on one line:
java com.ibm.lsd.LocationServiceDaemon -ORBListenerPort 9029
3. Create another executable file called startns2 and put the following command
all on one line in the file:
java com.ibm.CosNaming.PersistentNameServer -ORBBootstrapPort 9019
-ORBPersIORHostName wtr05073 -ORBPersIORPort 9029 -InitialRoot <Name Space
Directory>
Where <Name Space Directory> is an empty directory on your machine that
must already exist.
4. Create a third executable file called startejs and place the following command
on one line in the file:
java com.ibm.ejs.server.EJServer -ORBPersIORPort 9029 -ORBBootstrapPort
9019 -file <Server Root>\properties\ejs\ejs.properties
5. Save all of the files in the <Server Root> directory.
6. Stop the WebSphere EJS processes.
On Windows NT you can do this by stopping the Web server, stopping the
WebSphere Servlet Service, performing steps 7 and 8 and then restarting the
Web server.
On AIX you can simply kill the EJS processes (see Figure 165 on page 187 for
details).
7. Start three command prompts, and in each of them change the directory to the
<Server Root> directory and run setcpath. You may want to increase the
number of lines in the command prompt windows to capture all of the output.
8. In the first command prompt window, run startns1 and wait for it to initialize.
Repeat this procedure for startns2 and startejs in the second and third
command prompt windows respectively.
9. Open a fourth command prompt window, run setcpath and then run your client
code.
446
WebSphere Application Servers: Standard and Advanced Editions
If all of the above has worked, then your code should be working properly. If any
of the above steps has failed then the output from the EJS processes will
hopefully give you some insight into why things are not working.
Problem Determination
447
448
WebSphere Application Servers: Standard and Advanced Editions
Appendix A. WebSphere Samples
1. Update the servlet files for the XtremeAdventures and WebBank samples with
the DB2 user ID and password information.
To update the servlet files go to each of the files shown below and update the
values shown in bold. Change myDB2user and myPasswd to the user ID and
password that you used to log on to DB2 respectively. Also change the name
of the database driver to COM.ibm.db2.jdbc.app.DB2Driver if not already set
to this value (this value is case sensitive).
<?xml version="1.0"?>
<servlet>
<page-list>
<default-page>
<uri>/IBMWebAS/samples/XtremeTravel/results.jsp</uri>
</default-page>
<error-page>
<uri>/IBMWebAS/samples/XtremeTravel/FakeResults.jsp</uri>
</error-page>
</page-list>
<code>XtremeTravel.FlightsServlet</code>
<description>Flilghts database access servlet for XtremeTravel
sample</description>
<init-parameter name="URL" value="jdbc:db2:wbsphere"/>
<init-parameter name="userID" value="myDB2user"/>
<init-parameter name="driver" value="COM.ibm.db2.jdbc.app.DB2Driver"/>
<init-parameter name="password" value="myPasswd"/>
</servlet>
Figure 405. Changes to <server root>\servlets\XtremeTravel\FlightsServlet.servlet
<?xml version="1.0"?>
<servlet>
<page-list>
<default-page>
<uri>/IBMWebAS/samples/WebBank/userpage.jsp</uri>
</default-page>
<error-page>
<uri>/IBMWebAS/samples/WebBank/CreateAccountErrorPage.jsp</uri>
</error-page>
</page-list>
<code>WebBank.CreateAccountServlet</code>
<description>Registered users can create a new account</description>
<init-parameter name="owner" value="myDB2user"/>
<init-parameter name="URL" value="jdbc:db2:webbank"/>
<init-parameter name="userID" value="myDB2user"/>
<init-parameter name="driver" value="COM.ibm.db2.jdbc.app.DB2Driver"/>
<init-parameter name="password" value="myPasswd"/>
</servlet>
Figure 406. Changes to <server root>\servlets\WebBank\CreateAccountServlet.servlet
© Copyright IBM Corp. 1999
449
<?xml version="1.0"?>
<servlet>
<page-list>
<default-page>
<uri>/IBMWebAS/samples/WebBank/RegistrationOutputPage.jsp</uri>
</default-page>
<error-page>
<uri>/IBMWebAS/samples/WebBank/RegistrationErrorPage.jsp</uri>
</error-page>
</page-list>
<code>WebBank.RegistrationServlet</code>
<description>Allows new users to register with WebBank - their personal
info will be stored in the database</description>
<init-parameter name="owner" value="myDB2user"/>
<init-parameter name="URL" value="jdbc:db2:webbank"/>
<init-parameter name="userID" value="myDB2user"/>
<init-parameter name="driver" value="COM.ibm.db2.jdbc.app.DB2Driver"/>
<init-parameter name="password" value="myPasswd"/>
</servlet>
Figure 407. Changes to <server root>\servlets\WebBank\RegistrationServlet.servlet
<?xml version="1.0"?>
<servlet>
<page-list>
<default-page>
<uri>/IBMWebAS/samples/WebBank/userpage.jsp</uri>
</default-page>
<error-page>
<uri>/IBMWebAS/samples/WebBank/SignonErrorPage.jsp</uri>
</error-page>
</page-list>
<code>WebBank.SignonServlet</code>
<description>Allows new users to signon to WebBank and access account
info</description>
<init-parameter name="owner" value="myDB2user"/>
<init-parameter name="URL" value="jdbc:db2:webbank"/>
<init-parameter name="userID" value="myDB2user"/>
<init-parameter name="driver" value="COM.ibm.db2.jdbc.app.DB2Driver"/>
<init-parameter name="password" value="myPasswd"/>
</servlet>
Figure 408. Changes to <server root>\servlets\WebBank\SignonServlet.servlet
450
WebSphere Application Servers: Standard and Advanced Editions
<?xml version="1.0"?>
<servlet>
<page-list>
<default-page>
<uri>/IBMWebAS/samples/WebBank/userpage.jsp</uri>
</default-page>
<error-page>
<uri>/IBMWebAS/samples/WebBank/TransactionErrorPage.jsp</uri>
</error-page>
</page-list>
<code>WebBank.TransactionServlet</code>
<description>TransactionServlet for WebBank</description>
<init-parameter name="owner" value="myDB2user"/>
<init-parameter name="URL" value="jdbc:db2:webbank"/>
<init-parameter name="userID" value="myDB2user"/>
<init-parameter name="driver" value="COM.ibm.db2.jdbc.app.DB2Driver"/>
<init-parameter name="password" value="myPasswd"/>
</servlet>
Figure 409. Changes to <server root>\servlets\WebBank\TransactionServlet.servlet
2. Edit the properties files for the XtremeXML and IBMConnMgrTest samples
using the DB2 user ID and password information.
• Copy the file <<ASRoot>>\samples\login.properties to <ASRoot>\servlets.
Edit the file and change the database owner and login parameters. Figure
410 shows an extract from the file with the values to change shown in bold.
Change DB2owner to the DB2 user ID that you used to create the sample
database in step one above. If you want to access DB2 with a user ID other
than the user ID and password that WebSphere uses, change the dbUserid
and dbPassword values appropriately otherwise leave them as null . On
Windows NT the WebSphere service does not run under any user ID by
default so you must change these values.If you have changed the name of
the sample database that you created in step one above to something other
than sample, then change the dbName parameter to this value.
XtremAdvXml.dbOwner=DB2owner
XtremAdvXml.dbUserid=YourDB2Userid
XtremAdvXml.dbPassword=YourDB2Password
...
JDBCServlet.dbOwner=DB2owner
JDBCServlet.dbUserid=YourDB2Userid
JDBCServlet.dbPassword=YourDB2Password
JDBCServlet.dbName=sample
Figure 410. Lines to Change in <server root>\servlets\login.properties
• Edit the file <ASRoot>\servlets\IBMConnMgrTestStrings.properties and
change the values shown in Figure 411.
WebSphere Samples
451
# UserProfileConfig
upc.db=SAMPLE
upc.owner=DBOwner
upc.userid=DBUser
upc.password=DBPassword
# HTML text
# LOCALIZE THIS
html.title=Test for IBMConnMgrTest Servlet
html.nobodyfound=Nobody named Parker
html.greeting=G'day
# END OF MATERIAL TO LOCALIZE
Figure 411. Values to Change in <server home>/servlets/IBMConnMgrTestStrings.properties
Change the upc.db parameter to the name of the sample database
(probably sample) and the upc.owner parameter to the owner of the sample
database. If you want to log in to DB2 with a user ID and password that is
different from the user ID and password that WebSphere runs under,
change the upc.userid and upc.password settings appropriately. Otherwise
change them to the word null. On Windows NT the WebSphere service
does not run under a userid and password by default so you must change
these values.
If you want to localize the servlet for your country change the html.*
parameters to something in your local language. html.title is used as the
title heading on the servlet. html.nobodyfound is the message displayed
when no results are returned from the database. html.greeting is the word
used to greet someone.
3. Populate the database tables used by the sample applications.
You will need to create data in the database tables used by the sample
applications. Perform the following steps:
• Open a DB2 command window.
On Windows NT select Start -> Programs -> DB2 for Windows NT ->
Command Window.
On AIX open a terminal window and type:
. /home/<instance>/sqllib/db2profile
where <instance> is the name of the DB2 instance you have created and
the space between the . and the rest of the command is significant.
• Change directory to <server root>\samples\XtremeTravel\database
• Run Createdb.bat (see Figure 412 on page 454). If all goes well you should
see the following message near the bottom of the output:
452
WebSphere Application Servers: Standard and Advanced Editions
SQL3149N "12" rows were processed from the input file. "12" rows were
successfully inserted into the table. "0" rows were rejected.
Number
Number
Number
Number
Number
Number
of
of
of
of
of
of
rows
rows
rows
rows
rows
rows
read
skipped
inserted
updated
rejected
committed
=
=
=
=
=
=
12
0
12
0
0
12
• Change directory to <server root>\samples\WebBank\database
• Run createdb.bat (See Figure 413 on page 454). On Windows NT if all
goes well you should see the following message near the bottom of the
output:
D:\WebSphere\AppServer\samples\WebBank\database>db2 "create table customer (user
name varchar(12) not null primary key, pass varchar(12) not null, firstname varc
har(40), lastname varchar(40), street varchar(100), city varchar(50), state varc
har(2), zip varchar(5), phone varchar(15), email varchar(50))"
DB20000I The SQL command completed successfully.
D:\WebSphere\AppServer\samples\WebBank\database>db2 "create table bankaccount (u
sername varchar(12) not null, pass varchar(12), accounttype varchar(32) not null
, balance Decimal (15,2), primary key (username, accounttype))"
DB20000I The SQL command completed successfully.
On AIX the same messages display this way:
DB20000I The SQL command completed successfully.
DB20000I The SQL command completed successfully.
You will see some error messages if this is the first time you have run these
programs as they try to delete databases and tables that are not there, in
preparation for creating the new ones. If you see the completion messages
shown above, then all has completed successfully.
WebSphere Samples
453
db2start
db2 "create database wbsphere"
db2 "force application all"
db2 "connect to wbsphere"
db2 "drop table flights"
db2 "create table flights (id CHAR(4) NOT NULL PRIMARY KEY, DepartFrom_1
CHAR(25), DepartTime_1 CHAR(25), ArriveIn_1 CHAR(25), ArriveTime_1
CHAR(25), Airline_1 CHAR(25), DepartFrom_2 CHAR(25),DepartTime_2 CHAR(25),
ArriveIn_2 CHAR(25), ArriveTime_2 CHAR(25), Airline_2 CHAR(25))"
db2 "import from flights.txt of del insert into flights (id, DepartFrom_1,
DepartTime_1, ArriveIn_1, ArriveTime_1, Airline_1, DepartFrom_2,
DepartTime_2, ArriveIn_2, ArriveTime_2, Airline_2)"
db2 "connect reset"
Figure 412. Xtreme Travel Createdb.bat
db2 drop database webbank
db2 create database webbank
db2 force application all
db2stop
db2start
db2 connect to webbank
db2 drop table customer
db2 drop table bankaccount
db2 "create table customer (username varchar(12) not null primary key, pass
varchar(12) not null, firstname varchar(40), lastname varchar(40), street
varchar(100), city varchar(50), state varchar(2), zip varchar(5), phone
varchar(15), email varchar(50))"
db2 "create table bankaccount (username varchar(12) not null, pass
varchar(12), accounttype varchar(32) not null, balance Decimal (15,2),
primary key (username, accounttype))"
Figure 413. Web Bank Createdb.bat
4. Create an alias schema for the flights table for the XtremeAdventures sample.
If you have created these databases from a user ID other than db2admin the
XtremeAdventures sample will not be able to find the flights table. This is
because it will be looking under the db2admin schema and your table was
created under a schema matching your user ID. To fix this you will need to
create an alias schema for db2admin.
On Windows NT use the DB2 Control Center to select the alias folder for the
WEBSPHERE database. Right click and select Add to enter the information
shown in Figure 414 on page 455.
On AIX you can use the Web control center in the same manner or type the
following commands at a command prompt after running the db2profile script:
db2 connect to wbsphere
db2 create alias db2admin.flights for <userid>.flights
454
WebSphere Application Servers: Standard and Advanced Editions
where <userid> is the user ID you used to run the <server
root>\samples\WebBank\database\createdb.bat script in step 3 on page 452.
Figure 414. Creating a Schema Alias
A.1 Other Configuration Steps
The following are some miscellaneous configuration steps that you will need to
perform in order to get the samples running:
• To enable the form processing servlet to find its seminar details you must copy
<server root>/samples/FormProcessingServlet/seminar.txt to the root
directory of your web server’s document hierarchy.
• To get the XML version of the Xtreme Adventures Web site working you will
need to add the xml4j.jar file to the Application Server Classpath. See 4.2.1,
“Setting Up the Environment” on page 188 for details on how to perform this
task.
After completing the configuration steps for the samples that you want to run, you
should now be able to run the various samples. We had some trouble getting a
number of the samples to work. All of the errors we managed to track down have
been included in the setup instructions, but there were a number of strange errors
that were not reproducible. If you are experiencing problems, try shutting
everything down and rebooting. Usually this will fix the problem. Also try
executing the samples from a different machine or a different browser. If you run
into a problem that is reproducible, try one of the debugging techniques from
Chapter 8, “Problem Determination” on page 411.
The samples can be divided into three groups:
1. Samples from the samples Web page
2. EJS samples
WebSphere Samples
455
3. Other samples
Read one of the following sections for tips on the sample you want to run:
A.1.1 Samples From the Samples Web Page
Go to the samples Web page at http://<your server>/IBMWebAS/samples/ (see
Figure 415 on page 456).
Figure 415. The WebSphere Samples Page
Click the links for the following samples and follow the instructions.
A.1.1.1 Xtreme Adventures
The Xtreme Adventures sample models a simple travel agent Web site. On each
of these pages you can click the explanation or code buttons to see more
information about what’s on the screen and how it works.
• Click the register now! link.
• Enter details on the form and click Submit . It doesn’t matter what you type,
there is no field validation of these details.
456
WebSphere Application Servers: Standard and Advanced Editions
• Click either the rock climbing or skiing pictures.
• Pick a holiday package and click the link.
• Go down to the bottom of the page and click Flight Schedule.
• Pick either Atlanta or Chicago from the drop down list box and click the Find
Flights button.
• Scroll down to the bottom of the page and click Book It.
• Experiment and click the explanation and code buttons to see how the site
works.
A.1.1.2 Xtreme XML
Xtreme XML is a variation on the Xtreme Travel Web site but it uses XML under
the covers to do the work. There are actually three samples contained here that
perform the flight lookup portion of the XtremeTravel Web site using XML to
format the result. Each sample uses a different method to process the XML. A
tutorial on methods of processing XML is beyond the scope of this book but more
reference information can be found at http://www.software.ibm.com/xml.
The sample can be accessed in the following way:
• From the samples page click XML: An Alternative.
• Click either XML for Java parser, SAXDriver parser or ElementHandler
parser.
• Enter a name in the Your name: field.
• Select a city from the drop down menu.
• Click the Submit button under the field to see the flight information.
• More information on what is going on can be found by clicking the Developing
XML-based applications link on the first page which links to http://<your web
server>/IBMWebAS/doc/howto/itxml4j.html.
A.1.1.3 WebBank
WebBank gives you a chance to feel like an instant virtual millionaire right at your
own computer! It implements a simple online banking service that allows
accounts to be added and deposits and withdrawals to be made. The account
information is maintained in the WebBank database created previously. As with
the Xtreme Adventures sample, the WebBank sample includes an extensive
commentary on how it is constructed and what is going on. Simply click the
explanation or code links to access the information.
The following are some suggestions for using the WebBank sample:
• Click the WebBank link on the samples page. The WebBank initial page
comes up in another window.
• Click the register link to register a new customer.
• Fill in all of the fields and enter a user ID and password and click the Submit
button.
• The Registration Successful page appears. Click the here link near the bottom
to go to the main banking page.
• Select an account type to create from the drop-down menu (Cheque, Savings
or Money Market). Click Submit to create the account.
WebSphere Samples
457
• Deposit a million dollars into your new account by entering data into the fields
in the Make a Transaction section.
• Create another account and deposit some money.
• Withdraw money from your accounts.
• Have a look at the documentation for the sample by clicking the explanation
and code links.
A.1.1.4 IBM Connection Manager Test Servlet
This servlet, while not terribly exciting visually, demonstrates the IBM Connection
Manager performing connection pooling. To run the servlet:
• Click the Database Servlet from the samples page. Another browser window
will come up.
• Click Run IBMConnMgrTest . Yet another browser window should come up
with a greeting for JOHN Parker. The form of the greeting derives from the text
you entered in the database setup for the html.greeting parameter.
• If something goes wrong you should get the error message that you entered
for the html.nobodyfound parameter in the database setup.
A.1.1.5 Request Info Servlet
The Request Info servlet can be accessed by clicking the Echo a Request link
near the bottom of the samples page and then clicking the Run the
RequestInfoServlet link on the other browser window that appears. The servlet
will display some information about the http request that was passed to it.
Documentation is available by clicking Review the logic and Look at the source
code links on the RequestInfoServlet browser window.
A.1.1.6 Form Display Servlet
The Form Display servlet can be accessed by clicking the Display form input
link near the bottom of the samples page and then clicking the Run the
FormDisplayServlet link on the other browser window that appears. The servlet
will display a form which allows you to enter some seminar booking details in the
fields and when you press Submit , will echo the parameter names and values
back. Documentation is available by clicking Review the logic and Look at the
source code links on the FormDisplayServlet browser windows.
A.1.1.7 Form Processing Servlet
The Form Processing servlet can be accessed by clicking the Process form
input link near the bottom of the samples page and then clicking the Run the
FormProcessingServlet link on the other browser window that appears. The
servlet will display a form which allows you to enter some seminar booking details
in the fields. When you press Submit it will display the results of your attempt to
book the seminar based on your preferences. Documentation is available by
clicking Review the logic and Look at the source code links on the
FormProcessingServlet browser windows.
458
WebSphere Application Servers: Standard and Advanced Editions
Appendix B. Special Notices
This publication is intended to help webmasters set up the WebSphere
infrastructure for their Web applications.The information in this publication is not
intended as the specification of any programming interfaces that are provided by
the WebSphere Application Server. See the PUBLICATIONS section of the IBM
Programming Announcement for WebSphere Application Server Standard Edition
and WebSphere Application Server Advanced Edition for more information about
what publications are considered to be product documentation.
References in this publication to IBM products, programs or services do not imply
that IBM intends to make these available in all countries in which IBM operates.
Any reference to an IBM product, program, or service is not intended to state or
imply that only IBM's product, program, or service may be used. Any functionally
equivalent program that does not infringe any of IBM's intellectual property rights
may be used instead of the IBM product, program or service.
Information in this book was developed in conjunction with use of the equipment
specified, and is limited in application to those specific hardware and software
products and levels.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director of
Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 USA.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact IBM Corporation, Dept.
600A, Mail Drop 1329, Somers, NY 10589 USA.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The information contained in this document has not been submitted to any formal
IBM test and is distributed AS IS. The information about non-IBM ("vendor")
products in this manual has been supplied by the vendor and IBM assumes no
responsibility for its accuracy or completeness. The use of this information or the
implementation of any of these techniques is a customer responsibility and
depends on the customer's ability to evaluate and integrate them into the
customer's operational environment. While each item may have been reviewed by
IBM for accuracy in a specific situation, there is no guarantee that the same or
similar results will be obtained elsewhere. Customers attempting to adapt these
techniques to their own environments do so at their own risk.
Any pointers in this publication to external Web sites are provided for
convenience only and do not in any manner serve as an endorsement of these
Web sites.
Any performance data contained in this document was determined in a controlled
environment, and therefore, the results that may be obtained in other operating
environments may vary significantly. Users of this document should verify the
applicable data for their specific environment.
© Copyright IBM Corp. 1999
459
Reference to PTF numbers that have not been released through the normal
distribution process does not imply general availability. The purpose of including
these reference numbers is to alert IBM customers to specific information relative
to the implementation of the PTF when it becomes available to each customer
according to the normal IBM PTF distribution process.
The following terms are trademarks of the International Business Machines
Corporation in the United States and/or other countries:
AIX
AT
CT
eNetwork
IBM
MQ
Netfinity
OS/390
RS/6000
SP
TXSeries
VM/ESA
XT
AS/400
CICS
DB2
Home Director
JCentral
MQSeries
OS/2
OS/400
S/390
System/390
VisualAge
WebSphere
400
The following terms are trademarks of other companies:
C-bus is a trademark of Corollary, Inc. in the United States and/or other countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and/or other countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States and/or other countries.
PC Direct is a trademark of Ziff Communications Company in the United States
and/or other countries and is used by IBM Corporation under license.
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel
Corporation in the United States and/or other countries.
SET and the SET logo are trademarks owned by SET Secure Electronic
Transaction LLC.
UNIX is a registered trademark in the United States and/or other countries
licensed exclusively through X/Open Company Limited.
Other company, product, and service names may be trademarks or service marks
of others.
460
WebSphere Application Servers: Standard and Advanced Editions
Appendix C. Related Publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
C.1 International Technical Support Organization Publications
For information on ordering these ITSO publications see “How to Get ITSO
Redbooks” on page 465.
• VisualAge for Java Enterprise Version 2: Data Access Beans - Servlets - CICS
Connector, SG24-5265
• Using VisualAge for Java Enterprise Edition Version 2 to Develop CORBA EJB
Applications, SG24-5276
• Programming with VisualAge for Java Version 2, SG24-5264
• IBM WebSphere Performance Pack Usage and Administration, SG24-5233
• Connecting the Enterprise to the Internet with MQSeries and Visual Age for
Java, SG24-2144
C.2 Redbooks on CD-ROMs
Redbooks are also available on the following CD-ROMs. Click the CD-ROMs
button at http://www.redbooks.ibm.com/ for information about all the CD-ROMs
offered, updates and formats.
CD-ROM Title
System/390 Redbooks Collection
Networking and Systems Management Redbooks Collection
Transaction Processing and Data Management Redbooks Collection
Lotus Redbooks Collection
Tivoli Redbooks Collection
AS/400 Redbooks Collection
Netfinity Hardware and Software Redbooks Collection
RS/6000 Redbooks Collection (BkMgr Format)
RS/6000 Redbooks Collection (PDF Format)
Application Development Redbooks Collection
Collection Kit
Number
SK2T-2177
SK2T-6022
SK2T-8038
SK2T-8039
SK2T-8044
SK2T-2849
SK2T-8046
SK2T-8040
SK2T-8043
SK2T-8037
C.3 Other Publications
These publications are also relevant as further information sources:
• Quick Beginnings for DB2 Extended Enterprise Edition , S99H-8314
• MQSeries Application Programming Guide, SC33-0807
• MQSeries using Java, SC34-5456
C.4 Web Sites Referenced in This Book
http://www.ibm.com/java/jdk/
http;//www.ibm.com/developer/xml/
http;//www.ibm.com/xml
http://www.redbooks.ibm.com
© Copyright IBM Corp. 1999
461
http://www.developer.ibm.com/java
http://www.alphaworks.ibm.com
http://www.software.ibm.com
http://www.software.ibm.com/ad/vajava
http://www.software.ibm.com/ts/mqseries
http://www.software.ibm.com/webservers
http://www.software.ibm.com/webservers/httpservers/download.html
http://www.software.ibm.com/webservers/analysis
http://www.software.ibm.com/webservers/studio/doc/wsguide.pdf
http://www.software.ibm.com/ebusiness/library.html
http://www.software.ibm.com/ebusiness/arch_overview.html
http://www.software.ibm.com/ebusiness/appsrvsw
http://www.software.ibm.com/ebusiness/pm.html#Servlets.
http://www.software.ibm.com/developer/library/tutorial-prog/writing.html#dtds
http://www.software.ibm.com/ad/cb.
http://www.software.ibm.com/ebusiness/pm.html#Java Server Pages
http://www.software.ibm.com/xmlhttp://www.software.ibm.com/ebusiness/connector
s.html
http://www.software.ibm.com/ebusiness/connectors.html
http://www7.software.ibm.com
http://www7.software.ibm.com/vad.nsf/Data/Document3172?OpenDocument&SubMast=1
http://java.sun.com
http://java.sun.com/products/ejb/
http://java.sun.com/products/ejb/developers-guide.pdf
http://java.sun.com/products/jsp/
http://java.sun.com/products/jdbc
http://java.sun.com/products/servlets/index.html
http://java.sun.com/products/servlet/2.1/api/javax.servlet.http.HttpSession.ht
ml#_top_
http://java.sun.com/products/jndi/tutorial/index.html
http://java.sun.com/products/jdk/rmi/index.htm
http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/index.html
http://developer.java.sun.com
http://www.javasoft.com
http://www.javasoft.com/beans/docs
http://www.javasoft.com/products/jsp/index.htm.
http://www.javasoft.com/products/jsp/JSP-1_0-public-draft-1.pdf
http://www.netscape.com/servers
http://www.netscape.com/newsref/std/cookie_spec.html
http://www.lotus.com
http://www.notes.net/notesua.nsf
http://www.w3c.org
http://www.w3.org
http://www.w3.org/TR/WD-xs.
http://www.w3.org/TR/WD-logfile
http://www.w3.org/TR/WD-xsl/
http://www.w3.org/TR/PR-DOM-Level-1/
http://www.w3.org/TR/PR-DOM-Level-1/java-language-binding.html
http://www.w3.org/TR/REC-xml_names/
http://www.w3.org/XSL/Transform/1.0
http://www.w3.org/TR/1999/WD-xslt-19990421.html
http://www.xml.com
462
WebSphere Application Servers: Standard and Advanced Editions
http://www.xml.com/xml/pub/Style
http://www.xml.com/xml/pub/1999/01/namespaces.html
http://www.xml.com/xml/pub/1999/01/walsh3.html
http://www.xml.com/axml/testaxml.htm
http://info.webcrawler.com
http://www.webtechniques.com
http://www.sqlj.org
http://www.oracle.com
http://www.whatis.com/iiop.htm
http://www.omg.org/corba/beginners.html
http://www.microstar.com
http://www.microstar.com/sax.html
http://www.megginson.com/SAX/
http://www.otp.org
http://www.apache.org
http://www.netobjects.com
http://www.netobjects.com/products/html/nbb1.html
http://www.netobjects.com/products/html/nsb3.html.
http://www.netobjects.com/products/html/nf3i.html
Related Publications
463
464
WebSphere Application Servers: Standard and Advanced Editions
How to Get ITSO Redbooks
This section explains how both customers and IBM employees can find out about ITSO redbooks, redpieces, and
CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided.
• Redbooks Web Site http://www.redbooks.ibm.com/
Search for, view, download or order hardcopy/CD-ROM redbooks from the redbooks web site. Also read
redpieces and download additional materials (code samples or diskette/CD-ROM images) from this redbooks site.
Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just a few chapters will
be published this way. The intent is to get the information out much quicker than the formal publishing process
allows.
• E-mail Orders
Send orders via e-mail including information from the redbooks fax order form to:
In United States
Outside North America
e-mail address
[email protected]
Contact information is in the “How to Order” section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl/
• Telephone Orders
United States (toll free)
Canada (toll free)
Outside North America
1-800-879-2755
1-800-IBM-4YOU
Country coordinator phone number is in the “How to Order” section at
this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl/
• Fax Orders
United States (toll free)
Canada
Outside North America
1-800-445-9269
1-403-267-4455
Fax phone number is in the “How to Order” section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl/
This information was current at the time of publication, but is continually subject to change. The latest information for
customer may be found at http://www.redbooks.ibm.com/ and for IBM employees at http://w3.itso.ibm.com/.
IBM Intranet for Employees
IBM employees may register for information on workshops, residencies, and redbooks by accessing the IBM
Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materials
repository for workshops, presentations, papers, and Web pages developed and written by the ITSO technical
professionals; click the Additional Materials button. Employees may also view redbook. residency, and workshop
announcements at http://inews.ibm.com/.
© Copyright IBM Corp. 1999
465
IBM Redbook Fax Order Form
Please send me the following:
Title
Order Number
First name
Last name
Company
Address
City
Postal code
Country
Telephone number
Telefax number
VAT number
Card issued to
Signature
Invoice to customer number
Credit card number
Credit card expiration date
We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not
available in all countries. Signature mandatory for credit card payment.
466
WebSphere Application Servers: Standard and Advanced Editions
Quantity
Index
A
Administration interface 3
analyzing links 1
Apache Web server 2, 34
apachectl 71
Enterprise Java Services 3
Entity Beans 20
entity beans 216
event driven parsing 155
explicit indexing 139
F
B
bulletins
286
C
CAE 52, 53
callPage 140
chaining 14, 17, 108
CLASSPATH 31, 32, 54, 70, 89, 365, 381
classpath 106, 278, 351, 353, 359, 427, 434
clustering 248, 251
connection handle 317
Connection Manager 263 , 265
connection manager 306, 307, 310, 311, 315, 318, 323
connection URL 350, 351, 357
container 192, 195
Content Analysis 395, 396
Cookies 221, 239
cookies 247
CORBA 3, 7, 86, 197, 207, 209, 210, 212, 356, 358
filtering 14, 17, 110, 427, 433
firewall 219, 378
G
go46.dll
41, 62
H
helper class 210, 211, 212
HTML document root 94
HTTP document root 125, 235, 259, 269, 284, 286, 291,
300
HTTP protocol 2
HTTP requests 2
httpd.cnf 38, 40, 62, 64, 78, 80
httpd.conf 36, 64, 71, 80
httpd.properties 110
HttpRequest 15
HttpResponse 15
HttpServletRequest 129, 141
HttpServletResponse 129
D
Data Type Definition 166
databases 5
DB2 UDB V5.2 2
debug.properties file 419, 420, 422, 427, 428, 434
declaration 341
deployment 2, 187, 190, 197, 200, 204, 207, 216
directive 34, 140
Directory paths 1
document root 140
Document Structure Services 153, 154, 158, 165
domino.cnf 62, 78
DriverManager 335
dynamic content 13
dynamic HTML 5, 18
dynamic XML 153
E
EJB 2, 6, 19, 86, 199, 331, 356, 361
EJB Container 19
EJB container 189, 190
EJB containers 187
EJB deployment 209
EJS 90, 187, 412, 445
EJS process monitor 213
element handler 159
element handlers 158
Enterprise Edition 2
© Copyright IBM Corp. 1999
I
IBM HTTP Server 2, 32, 70
IBM jCentral 30
IBM VisualAge for Java 4
ibm_app_server_module 71
IIOP 7
IIS 47
iis20.dll 51
introspected 131
invoker servlet 103
J
JAR 6, 96, 103, 125, 154, 199
Java Foundation Classes 198
JDBC 8, 32, 52, 84, 175, 314, 326, 332, 337, 390, 442
JDBC result set 336
JDBCAccess 354
JDK 29, 30, 32, 64, 67, 68, 387, 436
Jet 197, 198, 207
JNDI 3, 7, 208, 213, 359
JSP 2, 18, 86, 91, 120, 140, 356, 440
JSP directives 127, 128
L
Linux 349
listener definition 381
467
listener service 381
Loaded Servlets Monitor 126
log files 394, 400, 401, 421
logs 411
LSD 187, 412
M
management 2, 187
MIME type 17
MIME-Type 112
MIME-type 113
MMC 48
MQSeries 362, 364
N
ns35.dll
O
obj.conf
44
standard error log 412
standard output log 413
stateful 20
stateless 20, 221
static 153
static HTML 12
style sheet 153, 165, 169, 179
System.err 417, 419
System.out 417, 419
T
three-tier 5
token 155
trace log 414
tracer 420, 428, 431
tracers 422, 424, 425, 430, 445
transaction systems 5
Type 2 driver 337, 346, 350
Type 3 driver 350
64, 80
U
P
PATH 54
path 353, 359, 381
Persistence 8
persistence 20, 231, 331, 358
plug-in 34, 40, 43, 51, 62, 64, 70, 71, 73, 78
PNS 187, 412
Project Center 392, 396
Project tree 392, 409
property file 360
property values 101
R
Redeployment Selection 194
reloadable servlet directory 106
remote loading 124
RMI 7
Robot Exclusion Protocol 395
S
SAX parser 158
SAX parsing 156
SER 96
servlet 91, 374, 414
Servlet Service 419
Servlets 5, 13
servlets 145, 369
session bean 358
Session Beans 20
session tracking 225
SHTML 92
Site Analyzer 29
site policies 394
SQL 272, 315, 335
SQLJ 32, 52, 89, 332, 338, 340, 349
SSL 2, 376
468
URL rewriting 239, 246, 247
Usage Analysis 400, 401, 404, 408
utility class 210
V
VA Java 29
Virtual servers 45
VisualAge for Java 3, 433, 445
W
Web robot 394, 395, 396
WebSphere Performance Pack 1
WebSphere Servlet Service 192, 195, 196
WebSphere Site Analysis 1
WebSphere Studio 1, 4, 86
X
XML 2, 6, 91, 152, 207
xml4j 154
XSL 164, 177
XSL stylesheets 6
WebSphere Application Servers: Standard and Advanced Editions
ITSO Redbook Evaluation
WebSphere Application Servers: Standard and Advanced Editions
SG24-5460-00
Your feedback is very important to help us maintain the quality of ITSO redbooks. Please complete this
questionnaire and return it using one of the following methods:
• Use the online evaluation form found at http://www.redbooks.ibm.com
• Fax this form to: USA International Access Code + 1 914 432 8264
• Send your comments in an Internet note to [email protected]
Which of the following best describes you?
_ Customer _ Business Partner
_ Solution Developer
_ None of the above
_ IBM employee
Please rate your overall satisfaction with this book using the scale:
(1 = very good, 2 = good, 3 = average, 4 = poor, 5 = very poor)
Overall Satisfaction
__________
Please answer the following questions:
Was this redbook published in time for your needs?
Yes___ No___
If no, please explain:
What other redbooks would you like to see published?
Comments/Suggestions:
© Copyright IBM Corp. 1999
(THANK YOU FOR YOUR FEEDBACK!)
469
Printed in the U.S.A.
WebSphere Application Servers: Standard and Advanced Editions
SG24-5460-00
SG24-5460-00
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement