WebSphere Application Server - IBM Redbooks
WebSphere Application Server - IBM Redbooks
WebSphere Application Server - IBM Redbooks
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
<strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express V5.0.2<br />
Developer Handbook<br />
Use <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express to develop applications<br />
Test and deploy applications<br />
Learn by example<br />
ibm.com/redbooks<br />
Front cover<br />
Carla Sadtler<br />
Justin Bogers<br />
Shailen Borkar<br />
Andri Firtiyan
International Technical Support Organization<br />
<strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2<br />
Developer Handbook<br />
September 2003<br />
SG24-6555-01
Take Note! Before using this information and the product it supports, be sure to read the<br />
general information in “Notices” on page xiii.<br />
Second Edition (September 2003)<br />
This edition applies to <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 for use with the Windows<br />
2000 and Linux Operating Systems.<br />
© Copyright International Business Machines Corporation 2003. All rights reserved.<br />
Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is subject to<br />
restrictions set forth in GSA ADP Schedule Contract with <strong>IBM</strong> Corp.
Contents<br />
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii<br />
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv<br />
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv<br />
The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv<br />
Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii<br />
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii<br />
Chapter 1. Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1<br />
1.1 What is <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5 . . . . . . . . . . . . . 2<br />
1.1.1 <strong>WebSphere</strong> Studio Site Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . 3<br />
1.1.2 Express <strong>Application</strong> <strong>Server</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3<br />
1.1.3 Database support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4<br />
1.1.4 CVS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4<br />
1.1.5 Web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5<br />
1.1.6 Testing and deploying applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 5<br />
1.1.7 Roles and responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6<br />
1.2 Information road map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6<br />
1.3 Bringing up Studio Site Developer for the first time. . . . . . . . . . . . . . . . . . 10<br />
1.3.1 <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express examples . . . . . . . . . . . . 11<br />
1.3.2 Installing an example application . . . . . . . . . . . . . . . . . . . . . . . . . . . 12<br />
1.3.3 Using application templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14<br />
1.4 The Online Catalog sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15<br />
1.4.1 Sample application overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15<br />
1.4.2 Sample database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16<br />
Chapter 2. <strong>Application</strong> design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17<br />
2.1 Design considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18<br />
2.1.1 System model for e-business applications . . . . . . . . . . . . . . . . . . . . 18<br />
2.1.2 <strong>IBM</strong> Patterns for e-business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21<br />
2.2 Modeling an application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22<br />
2.2.1 Use-case analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23<br />
2.3 Determine the application-flow architecture . . . . . . . . . . . . . . . . . . . . . . . 26<br />
2.3.1 Model 1 architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26<br />
2.3.2 Model 2 architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27<br />
2.3.3 MVC architectural pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28<br />
2.4 Reviewing the supporting technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . 32<br />
2.4.1 JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32<br />
2.4.2 Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33<br />
© Copyright <strong>IBM</strong> Corp. 2003 iii
2.4.3 Java<strong>Server</strong> Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33<br />
2.4.4 Tag libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34<br />
2.4.5 XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35<br />
2.4.6 Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35<br />
2.4.7 Struts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36<br />
2.5 Designing the database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37<br />
2.5.1 Normalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37<br />
2.5.2 Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38<br />
2.5.3 Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39<br />
2.5.4 Deriving the data model from the use-case model . . . . . . . . . . . . . . 39<br />
2.6 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40<br />
Chapter 3. Using Studio Site Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . 43<br />
3.1 The workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44<br />
3.1.1 Recovering files from their local history . . . . . . . . . . . . . . . . . . . . . . 45<br />
3.2 Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47<br />
3.2.1 Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49<br />
3.2.2 Using fast views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50<br />
3.2.3 Customizing perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52<br />
3.2.4 Setting perspective preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53<br />
3.3 Finding help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54<br />
Chapter 4. Working with Web applications . . . . . . . . . . . . . . . . . . . . . . . . . 57<br />
4.1 Enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58<br />
4.1.1 Enterprise application deployment descriptor . . . . . . . . . . . . . . . . . . 58<br />
4.2 Web application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59<br />
4.2.1 A Web application in an application server . . . . . . . . . . . . . . . . . . . . 64<br />
4.3 Working with Web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65<br />
4.3.1 Creating an enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . 65<br />
4.3.2 Creating a Web project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66<br />
4.3.3 Web project directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72<br />
4.3.4 <strong>Application</strong> templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75<br />
Chapter 5. Working with HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77<br />
5.1 HTML support in Studio Site Developer . . . . . . . . . . . . . . . . . . . . . . . . . . 78<br />
5.1.1 Using the Web perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78<br />
5.1.2 Editing with the Page Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90<br />
5.1.3 Building applications with Web Site Designer . . . . . . . . . . . . . . . . . . 93<br />
5.1.4 HTML/XHTML wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108<br />
5.1.5 Using Page templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109<br />
5.1.6 Working with framesets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112<br />
5.1.7 Adding tables, links, text, and images. . . . . . . . . . . . . . . . . . . . . . . 116<br />
5.1.8 Working with forms, input fields, and buttons . . . . . . . . . . . . . . . . . 119<br />
5.1.9 Working with style sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120<br />
iv <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
5.1.10 Working with WebArt Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . 122<br />
5.1.11 Working with animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128<br />
5.2 Adding HTML pages to the Online Catalog sample . . . . . . . . . . . . . . . . 135<br />
5.2.1 Creating HTML pages using Web Site Designer . . . . . . . . . . . . . . 135<br />
5.2.2 Customizing a page template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135<br />
5.2.3 Creating HTML pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143<br />
Chapter 6. Accessing databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153<br />
6.1 Java Database Connectivity (JDBC) overview . . . . . . . . . . . . . . . . . . . . 154<br />
6.1.1 Data source versus direct connection . . . . . . . . . . . . . . . . . . . . . . . 154<br />
6.2 Working with databases in Studio Site Developer. . . . . . . . . . . . . . . . . . 155<br />
6.2.1 Using the Data perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156<br />
6.2.2 Creating the database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158<br />
6.2.3 Connecting Studio Site Developer to the database . . . . . . . . . . . . 159<br />
6.2.4 Importing and working with the database design . . . . . . . . . . . . . . 162<br />
6.2.5 DB output view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173<br />
6.2.6 Creating Web pages to access the database . . . . . . . . . . . . . . . . . 174<br />
6.2.7 Database connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194<br />
6.2.8 Defining a resource reference for the data source (optional) . . . . . 197<br />
6.2.9 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200<br />
6.2.10 Building SQL statements using the SQL Query Builder . . . . . . . . 211<br />
Chapter 7. Working with servlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215<br />
7.1 Servlet overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216<br />
7.1.1 A servlet’s life cycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216<br />
7.1.2 The servlet’s environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218<br />
7.1.3 Servlets in an enterprise application . . . . . . . . . . . . . . . . . . . . . . . . 220<br />
7.2 Studio Site Developer and servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221<br />
7.2.1 Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221<br />
7.2.2 Web perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224<br />
7.2.3 Deployment descriptor editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229<br />
7.3 Using servlets in the Online Catalog sample. . . . . . . . . . . . . . . . . . . . . . 232<br />
7.3.1 Creating a servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233<br />
7.4 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240<br />
Chapter 8. Working with JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241<br />
8.1 JSP overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242<br />
8.1.1 JSP execution model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242<br />
8.1.2 Syntax for coding Java<strong>Server</strong> Pages . . . . . . . . . . . . . . . . . . . . . . . 244<br />
8.1.3 JSP 1.2 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246<br />
8.2 Building JSP pages with Studio Site Developer . . . . . . . . . . . . . . . . . . . 256<br />
8.2.1 Preferences and properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257<br />
8.2.2 Web perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257<br />
8.2.3 JSP wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263<br />
Contents v
8.3 Using JSPs in the Online Catalog sample. . . . . . . . . . . . . . . . . . . . . . . . 265<br />
Chapter 9. Using tag libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275<br />
9.1 Custom tag library (taglibs) concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . 276<br />
9.1.1 Motivation for custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276<br />
9.1.2 When to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278<br />
9.1.3 Common custom tag usages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279<br />
9.1.4 How they work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279<br />
9.1.5 An inside look at a taglib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280<br />
9.1.6 Using tag libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285<br />
9.2 Studio Site Developer and tag libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 288<br />
9.2.1 JSP wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288<br />
9.2.2 Using the Insert custom tag dialog . . . . . . . . . . . . . . . . . . . . . . . . . 295<br />
9.2.3 Snippets view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296<br />
9.2.4 Tag libraries included with Studio Site Developer. . . . . . . . . . . . . . 296<br />
9.2.5 Tag libraries used in the example sample applications. . . . . . . . . . 299<br />
9.3 Using a tag library in the Online Catalog sample . . . . . . . . . . . . . . . . . . 301<br />
9.3.1 Step 1: Creating a JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303<br />
9.3.2 Step 2: Adding a taglib directive . . . . . . . . . . . . . . . . . . . . . . . . . . . 304<br />
9.3.3 Step 3: Adding the taglib tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305<br />
9.3.4 Step 4: Inserting the final code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307<br />
9.4 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308<br />
Chapter 10. Working with XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309<br />
10.1 XML overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310<br />
10.1.1 XML markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310<br />
10.1.2 Well-formed XML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313<br />
10.1.3 Document type definitions (DTDs) . . . . . . . . . . . . . . . . . . . . . . . . 313<br />
10.1.4 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314<br />
10.1.5 XML namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314<br />
10.1.6 XML schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315<br />
10.1.7 Schema and style using XSLT and XSL . . . . . . . . . . . . . . . . . . . . 318<br />
10.1.8 XPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319<br />
10.2 Working with XML in Studio Site Developer . . . . . . . . . . . . . . . . . . . . . 319<br />
10.2.1 The XML perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321<br />
10.2.2 Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322<br />
10.2.3 Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325<br />
10.2.4 XML sample applications in Studio Site Developer. . . . . . . . . . . . 331<br />
10.3 Using XML in the Online Catalog sample . . . . . . . . . . . . . . . . . . . . . . . 332<br />
10.4 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353<br />
Chapter 11. Working with Web services . . . . . . . . . . . . . . . . . . . . . . . . . . 355<br />
11.1 Web services overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356<br />
11.1.1 The concept of a service-oriented architecture (SOA) . . . . . . . . . 357<br />
vi <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
11.1.2 Web services approach for an SOA architecture . . . . . . . . . . . . . 359<br />
11.1.3 An introduction to SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360<br />
11.1.4 An introduction to WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362<br />
11.1.5 Web Services Invocation Framework (WSIF) . . . . . . . . . . . . . . . . 363<br />
11.2 Studio Site Developer support for Web services. . . . . . . . . . . . . . . . . . 366<br />
11.2.1 Web service preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367<br />
11.2.2 Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369<br />
11.2.3 WSDL editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369<br />
11.2.4 Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370<br />
11.3 Using Web services in the Online Catalog sample . . . . . . . . . . . . . . . . 372<br />
11.3.1 Locating and consuming a Web service . . . . . . . . . . . . . . . . . . . . 372<br />
11.3.2 Integrating the client into your application. . . . . . . . . . . . . . . . . . . 380<br />
11.3.3 For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381<br />
Chapter 12. Using Struts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383<br />
12.1 Struts overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384<br />
12.1.1 Why we use Struts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384<br />
12.1.2 Struts framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385<br />
12.2 Studio Site Developer and Struts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388<br />
12.2.1 Struts development process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389<br />
12.2.2 Struts support in a Web project. . . . . . . . . . . . . . . . . . . . . . . . . . . 389<br />
12.2.3 Setting Struts preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393<br />
12.2.4 Web diagram editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398<br />
12.2.5 Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405<br />
12.2.6 Struts configuration file editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422<br />
12.2.7 Struts explorer view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423<br />
12.2.8 Data Mappings view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424<br />
12.2.9 Struts validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424<br />
12.3 Using Struts in a sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425<br />
12.3.1 Adding Struts support to the OnlineCatalog project . . . . . . . . . . . 427<br />
12.3.2 Creating a Web diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427<br />
12.3.3 Creating the Web page nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . 429<br />
12.3.4 Creating the action mapping nodes . . . . . . . . . . . . . . . . . . . . . . . 430<br />
12.3.5 Creating connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431<br />
12.3.6 Editing the <strong>Application</strong>Resources.properties file. . . . . . . . . . . . . . 432<br />
12.3.7 Realizing and editing the Web pages . . . . . . . . . . . . . . . . . . . . . . 433<br />
12.3.8 Creating the form bean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440<br />
12.3.9 Realizing and editing the action classes . . . . . . . . . . . . . . . . . . . . 444<br />
12.3.10 Integrating with the Online Catalog sample template . . . . . . . . . 451<br />
12.3.11 Understanding the Struts configuration file . . . . . . . . . . . . . . . . . 452<br />
Chapter 13. Deploying applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455<br />
13.1 <strong>Application</strong> server overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456<br />
Contents vii
13.1.1 Configuration and management . . . . . . . . . . . . . . . . . . . . . . . . . . 456<br />
13.1.2 Managing test application servers. . . . . . . . . . . . . . . . . . . . . . . . . 457<br />
13.2 Using the <strong>Server</strong> tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459<br />
13.2.1 Setting preferences for the <strong>Server</strong> perspective. . . . . . . . . . . . . . . 460<br />
13.3 Defining servers and server configurations . . . . . . . . . . . . . . . . . . . . . . 462<br />
13.3.1 <strong>Server</strong> types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465<br />
13.4 Using the Express test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 465<br />
13.4.1 Creating a server and server configuration . . . . . . . . . . . . . . . . . . 466<br />
13.4.2 Publishing an application to the test environment. . . . . . . . . . . . . 468<br />
13.4.3 Updating the server configuration for the application . . . . . . . . . . 470<br />
13.4.4 Starting the test environment server . . . . . . . . . . . . . . . . . . . . . . . 471<br />
13.4.5 Running the application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472<br />
13.5 Working with an Express server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475<br />
13.5.1 Defining the server to Studio Site Developer . . . . . . . . . . . . . . . . 476<br />
13.5.2 Publishing the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481<br />
13.5.3 Updating the server configuration for the application . . . . . . . . . . 482<br />
13.5.4 Starting the Express server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482<br />
13.5.5 Running the application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483<br />
13.6 Working with server configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483<br />
13.6.1 Classloaders and file location . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486<br />
13.7 <strong>Server</strong> operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487<br />
13.7.1 Starting the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487<br />
13.7.2 Stopping the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488<br />
13.7.3 Restarting the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488<br />
13.8 Deploying applications for production . . . . . . . . . . . . . . . . . . . . . . . . . . 489<br />
13.8.1 Exporting an enterprise application to a file location. . . . . . . . . . . 489<br />
13.8.2 Exporting an enterprise application using FTP . . . . . . . . . . . . . . . 490<br />
13.9 <strong>IBM</strong> Agent Controller settings and status . . . . . . . . . . . . . . . . . . . . . . . 491<br />
13.10 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492<br />
Chapter 14. Testing and debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493<br />
14.1 Debugging in the Web perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494<br />
14.1.1 Page errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494<br />
14.1.2 Project navigator view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496<br />
14.1.3 Tasks view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497<br />
14.1.4 Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498<br />
14.1.5 Console view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499<br />
14.2 Debugging using the Debug perspective . . . . . . . . . . . . . . . . . . . . . . . 500<br />
14.2.1 Debug perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501<br />
14.3 Stepping through code using the Online Catalog sample . . . . . . . . . . . 507<br />
14.3.1 Setting breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507<br />
14.3.2 Running the application in debug mode . . . . . . . . . . . . . . . . . . . . 508<br />
14.3.3 Verifying the variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512<br />
viii <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 15. Development in a team environment . . . . . . . . . . . . . . . . . . 515<br />
15.1 Team development with CVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516<br />
15.1.1 Non-exclusive checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516<br />
15.1.2 Access to resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516<br />
15.1.3 Working with resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516<br />
15.1.4 Change history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517<br />
15.1.5 Making changes available to the team . . . . . . . . . . . . . . . . . . . . . 517<br />
15.1.6 Conflict resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517<br />
15.2 Team environment using Studio Site Developer . . . . . . . . . . . . . . . . . . 518<br />
15.2.1 Typical flow for team development . . . . . . . . . . . . . . . . . . . . . . . . 518<br />
15.3 Connecting to a repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519<br />
15.4 Adding a new application to the repository . . . . . . . . . . . . . . . . . . . . . . 521<br />
15.4.1 Sharing the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521<br />
15.4.2 Copy (commit) the project to the repository . . . . . . . . . . . . . . . . . 524<br />
15.4.3 Creating a version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525<br />
15.4.4 (Optional) changing the sharing information for a Web project. . . 528<br />
15.5 Adding an existing application to your workspace. . . . . . . . . . . . . . . . . 529<br />
15.6 Working with the team using the repository . . . . . . . . . . . . . . . . . . . . . 530<br />
15.6.1 Synchronizing with the repository . . . . . . . . . . . . . . . . . . . . . . . . . 530<br />
15.6.2 Dealing with conflicting changes . . . . . . . . . . . . . . . . . . . . . . . . . . 531<br />
15.6.3 Updating from the repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535<br />
15.6.4 Committing changes to the repository. . . . . . . . . . . . . . . . . . . . . . 536<br />
15.7 Using multiple branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537<br />
15.7.1 Creating a new branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537<br />
15.7.2 Accessing the branch from another workbench . . . . . . . . . . . . . . 539<br />
15.7.3 Merging branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541<br />
15.8 Viewing resource history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542<br />
15.9 Comparing resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544<br />
15.9.1 Comparing a resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545<br />
15.9.2 Comparing two selected files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545<br />
15.9.3 Three-way compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545<br />
15.9.4 Working with the comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547<br />
15.10 Determining which files are managed . . . . . . . . . . . . . . . . . . . . . . . . . 549<br />
Chapter 16. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551<br />
16.1 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552<br />
16.2 Securing applications in <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express . . . 552<br />
16.3 Authenticating users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553<br />
16.3.1 Form-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554<br />
16.4 Securing applications with role-based security . . . . . . . . . . . . . . . . . . . 556<br />
16.4.1 Declarative security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557<br />
16.4.2 Programmatic security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568<br />
16.5 JAAS security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570<br />
Contents ix
16.5.1 Adding JAAS authentication to a server . . . . . . . . . . . . . . . . . . . . 571<br />
16.5.2 Setting up a datasource using JAAS. . . . . . . . . . . . . . . . . . . . . . . 572<br />
16.6 Securing the <strong>IBM</strong> Agent Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573<br />
16.6.1 Implementing SSL for <strong>IBM</strong> Agent Controller communications . . . 574<br />
16.6.2 Importing a security certificate into the Workbench . . . . . . . . . . . 576<br />
16.7 Using SSL with applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578<br />
16.8 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580<br />
Appendix A. <strong>Application</strong> templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581<br />
Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582<br />
Using the Template application wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584<br />
Appendix B. Updating Studio Site Developer. . . . . . . . . . . . . . . . . . . . . . 597<br />
Using the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597<br />
Updating features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601<br />
Appendix C. Online Catalog application . . . . . . . . . . . . . . . . . . . . . . . . . . 611<br />
Online Catalog sample application overview . . . . . . . . . . . . . . . . . . . . . . . . . 612<br />
Database architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612<br />
<strong>Application</strong> components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614<br />
<strong>Application</strong> root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614<br />
Featured item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615<br />
Site administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617<br />
Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620<br />
Wishlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621<br />
Information request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625<br />
Currency conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625<br />
Template and images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627<br />
Deployment descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628<br />
Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629<br />
Servlet login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629<br />
Struts login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631<br />
Appendix D. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633<br />
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633<br />
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634<br />
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634<br />
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641<br />
<strong>IBM</strong> <strong>Redbooks</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641<br />
Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642<br />
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642<br />
How to get <strong>IBM</strong> <strong>Redbooks</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645<br />
<strong>IBM</strong> <strong>Redbooks</strong> collections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645<br />
x <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647<br />
Contents xi
xii <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Notices<br />
This information was developed for products and services offered in the U.S.A.<br />
<strong>IBM</strong> may not offer the products, services, or features discussed in this document in other countries. Consult<br />
your local <strong>IBM</strong> representative for information on the products and services currently available in your area.<br />
Any reference to an <strong>IBM</strong> product, program, or service is not intended to state or imply that only that <strong>IBM</strong><br />
product, program, or service may be used. Any functionally equivalent product, program, or service that<br />
does not infringe any <strong>IBM</strong> intellectual property right may be used instead. However, it is the user's<br />
responsibility to evaluate and verify the operation of any non-<strong>IBM</strong> product, program, or service.<br />
<strong>IBM</strong> may have patents or pending patent applications covering subject matter described in this document.<br />
The furnishing of this document does not give you any license to these patents. You can send license<br />
inquiries, in writing, to:<br />
<strong>IBM</strong> Director of Licensing, <strong>IBM</strong> Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.<br />
The following paragraph does not apply to the United Kingdom or any other country where such provisions<br />
are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES<br />
THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,<br />
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,<br />
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer<br />
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.<br />
This information could include technical inaccuracies or typographical errors. Changes are periodically made<br />
to the information herein; these changes will be incorporated in new editions of the publication. <strong>IBM</strong> may<br />
make improvements and/or changes in the product(s) and/or the program(s) described in this publication at<br />
any time without notice.<br />
Any references in this information to non-<strong>IBM</strong> Web sites are provided for convenience only and do not in any<br />
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the<br />
materials for this <strong>IBM</strong> product and use of those Web sites is at your own risk.<br />
<strong>IBM</strong> may use or distribute any of the information you supply in any way it believes appropriate without<br />
incurring any obligation to you.<br />
Information concerning non-<strong>IBM</strong> products was obtained from the suppliers of those products, their published<br />
announcements or other publicly available sources. <strong>IBM</strong> has not tested those products and cannot confirm<br />
the accuracy of performance, compatibility or any other claims related to non-<strong>IBM</strong> products. Questions on<br />
the capabilities of non-<strong>IBM</strong> products should be addressed to the suppliers of those products.<br />
This information contains examples of data and reports used in daily business operations. To illustrate them<br />
as completely as possible, the examples include the names of individuals, companies, brands, and products.<br />
All of these names are fictitious and any similarity to the names and addresses used by an actual business<br />
enterprise is entirely coincidental.<br />
COPYRIGHT LICENSE:<br />
This information contains sample application programs in source language, which illustrates programming<br />
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in<br />
any form without payment to <strong>IBM</strong>, for the purposes of developing, using, marketing or distributing application<br />
programs conforming to the application programming interface for the operating platform for which the<br />
sample programs are written. These examples have not been thoroughly tested under all conditions. <strong>IBM</strong>,<br />
therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy,<br />
modify, and distribute these sample programs in any form without payment to <strong>IBM</strong> for the purposes of<br />
developing, using, marketing, or distributing application programs conforming to <strong>IBM</strong>'s application<br />
programming interfaces.<br />
© Copyright <strong>IBM</strong> Corp. 2003 xiii
Trademarks<br />
The following terms are trademarks of the International Business Machines Corporation in the United States,<br />
other countries, or both:<br />
<br />
^<br />
<strong>Redbooks</strong> (logo) <br />
developerWorks®<br />
ibm.com®<br />
iSeries<br />
AIX®<br />
Cloudscape<br />
CICS®<br />
DB2®<br />
Informix®<br />
<strong>IBM</strong>®<br />
MQSeries®<br />
OS/400®<br />
The following terms are trademarks of other companies:<br />
Perform<br />
Rational Rose®<br />
Rational®<br />
<strong>Redbooks</strong><br />
VisualAge®<br />
<strong>WebSphere</strong>®<br />
Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States, other<br />
countries, or both.<br />
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the<br />
United States, other countries, or both.<br />
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun<br />
Microsystems, Inc. in the United States, other countries, or both.<br />
UNIX is a registered trademark of The Open Group in the United States and other countries.<br />
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure<br />
Electronic Transaction LLC.<br />
Other company, product, and service names may be trademarks or service marks of others.<br />
xiv <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Preface<br />
This <strong>IBM</strong> Redbook introduces <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5,<br />
an <strong>IBM</strong> offering that provides a comprehensive development tool and a<br />
single-server application server environment designed for the small and medium<br />
business customers who want to have a Web presence for their business. It<br />
provides development tools and application server capability in a single offering.<br />
<strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5 users can develop and test<br />
applications using <strong>WebSphere</strong> Studio Site Developer, then test and deploy<br />
applications on a lightweight version of <strong>IBM</strong>’s <strong>WebSphere</strong>® <strong>Application</strong> <strong>Server</strong>.<br />
We refer to this lightweight server as the Express <strong>Application</strong> <strong>Server</strong>.<br />
This redbook guides you through the process of developing and testing<br />
applications. It gives you an overview of Studio Site Developer and how it<br />
supports the technology required to build effective Web applications. It provides<br />
information on how to use the tools and takes you through the process of building<br />
and testing Web applications.<br />
The focus of this book is on the development process. For information about<br />
server administration, see <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.1<br />
Administrator Handbook, SG24-6976.<br />
The team that wrote this redbook<br />
This redbook was produced by a team of specialists from around the world<br />
working at the International Technical Support Organization, Raleigh Center.<br />
Carla Sadtler is a <strong>WebSphere</strong> Specialist at the International Technical<br />
Support Organization, Raleigh Center. She writes extensively in the<br />
<strong>WebSphere</strong> and Patterns for e-business areas. Before joining the ITSO in<br />
1985, Carla worked in the Raleigh branch office as a Program Support<br />
Representative. She holds a degree in mathematics from the University of<br />
North Carolina at Greensboro.<br />
Justin Bogers is a Web Development Specialist for ASTECH Solutions Inc., a<br />
Toronto-based consulting firm and <strong>IBM</strong> Business Partner. He has seven years of<br />
experience in the field of information technology, and five years of experience in<br />
analysis, design and development of Web and J2EE applications. He is a<br />
graduate of Ryerson University with a Bachelor of Commerce degree in Business<br />
© Copyright <strong>IBM</strong> Corp. 2003 xv
Information Systems. His areas of expertise include new media development,<br />
application development using the Eclipse platform, <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> administration, and Web-enabling existing 5250 applications using the<br />
<strong>IBM</strong> WebFacing Tool.<br />
Shailen Borkar is a Senior Consultant for The Software Company, a consulting<br />
firm in Chicago, IL. He holds a degree in electronics engineering and has 12<br />
years of experience in the software application development field. His areas of<br />
expertise include data warehousing and Web application development.<br />
Andri Firtiyan is an IT Specialist with the <strong>IBM</strong> Software Group based in Jakarta,<br />
Indonesia. He has seven years of experience in the entire application<br />
development life cycle and for the last two years has been involved in presenting<br />
and demonstrating various <strong>WebSphere</strong> technology to <strong>IBM</strong> customers. He holds a<br />
Masters degree in Computer Science from the University of Indonesia. His areas<br />
of expertise include <strong>WebSphere</strong> and MQSeries® family products.<br />
Thanks to the following people for their contributions to this project:<br />
Peter Kovari<br />
International Technical Support Organization, Raleigh Center<br />
Mark Edwards<br />
<strong>IBM</strong> Raleigh<br />
Kevin Postreich<br />
<strong>IBM</strong> Raleigh<br />
Moji Trasti<br />
<strong>IBM</strong> Raleigh<br />
Tim DeBoer<br />
<strong>IBM</strong> Toronto<br />
Ian Brown<br />
ASTECH Solutions Inc.<br />
xvi <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Notice<br />
This publication is intended to help customers build and deploy Web applications<br />
using <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5. The information in this<br />
publication is not intended as the specification of any programming interfaces<br />
that are provided by <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5. See the<br />
PUBLICATIONS section of the <strong>IBM</strong> Programming Announcement for <strong>IBM</strong><br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5 for more information about what<br />
publications are considered to be product documentation.<br />
Comments welcome<br />
Your comments are important to us!<br />
We want our <strong>Redbooks</strong> to be as helpful as possible. Send us your comments<br />
about this or other <strong>Redbooks</strong> in one of the following ways:<br />
► Use the online Contact us review redbook form found at:<br />
ibm.com/redbooks<br />
► Send your comments in an Internet note to:<br />
redbook@us.ibm.com<br />
► Mail your comments to:<br />
<strong>IBM</strong>® Corporation, International Technical Support Organization<br />
Dept. HZ8 Building 662<br />
P.O. Box 12195<br />
Research Triangle Park, NC 27709-2195<br />
Preface xvii
xviii <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 1. Getting started<br />
1<br />
<strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5 provides a combination of<br />
development tool and application server that provides a single integrated<br />
package geared towards Web page centric applications. This chapter provides<br />
an introduction to the development tool, <strong>WebSphere</strong> Studio Site Developer,<br />
including:<br />
► An overview of <strong>WebSphere</strong> Studio Site Developer<br />
► Starting Studio Site Developer<br />
► Loading the samples<br />
© Copyright <strong>IBM</strong> Corp. 2003 1
1.1 What is <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express V5<br />
Develop<br />
<strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5 (referred to in this document as<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express) is an offering that contains the<br />
following in one installable package:<br />
► Express <strong>Application</strong> <strong>Server</strong><br />
► <strong>WebSphere</strong> Studio Site Developer<br />
► <strong>IBM</strong> Agent Controller<br />
► Pre-loaded samples<br />
CVS<br />
Repository<br />
<strong>WebSphere</strong> Studio<br />
Site Developer<br />
Web<br />
projects<br />
Team<br />
Help<br />
XML<br />
Database<br />
Access<br />
<strong>Server</strong><br />
projects<br />
Express<br />
Test<br />
Environment<br />
DB2<br />
Oracle<br />
Web<br />
Services<br />
Web Service access<br />
Configure<br />
and deploy to<br />
test servers<br />
Data Access<br />
Cloudscape<br />
Figure 1-1 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5<br />
SQL<br />
<strong>Server</strong><br />
2 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Express <strong>Application</strong><br />
<strong>Server</strong><br />
Production server<br />
<strong>Application</strong><br />
<strong>Application</strong><br />
Test server<br />
<strong>Application</strong><br />
Web client<br />
Configure<br />
and deploy to<br />
production<br />
servers<br />
Administratiion
1.1.1 <strong>WebSphere</strong> Studio Site Developer<br />
<strong>WebSphere</strong> Studio Site Developer provides a rich development environment<br />
tailored for Web applications using JavaScript, HTML, JSP, XML, servlet, and<br />
Web services technology. Java Database Connectivity (JDBC) support is<br />
provided to access DB2®, Microsoft® SQL <strong>Server</strong>, and Oracle databases.<br />
Java programming knowledge is optional. Fully functional Web applications can<br />
be built without Java skills using HTML, graphics, tag libraries, Java<strong>Server</strong><br />
Pages, and JDBC database access. For Java programmers, support for servlets<br />
and Java scriptlets has been included.<br />
Web applications can be tested in the Studio Site Developer test environment<br />
and then deployed to the Express <strong>Application</strong> <strong>Server</strong>.<br />
Studio Site Developer support includes:<br />
► JSP 1.2 specification<br />
► Servlet 2.3 specification<br />
► HTML<br />
► JavaScript (client-side and server-side)<br />
► DHTML<br />
► XML and XHTML<br />
► Web services use and creation<br />
► Team development using CVS<br />
► JDBC 2.0<br />
► An embedded server test environment<br />
► Support for remote server configuration and operation<br />
► Custom tag libraries<br />
► Struts<br />
Studio Site Developer is supported on Windows® 2000 Professional, Windows<br />
XP Professional, Windows NT®, Red Hat, and SuSE. For specific operating<br />
system support information, see:<br />
http://www.ibm.com/software/webservers/appserv/express/requirements/<br />
1.1.2 Express <strong>Application</strong> <strong>Server</strong><br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express includes a Web application server<br />
component. We will refer to this as the Express <strong>Application</strong> <strong>Server</strong>. Each<br />
installation of Express <strong>Application</strong> <strong>Server</strong> provides a single server environment<br />
that includes the following:<br />
► J2EE 1.3 compliance including Servlet 2.3 and JSP 1.2 support<br />
► An embedded Web server<br />
Chapter 1. Getting started 3
► A Web container<br />
► Web services support including SOAP 2.3, WSIF, WSDL, and UDDI client<br />
► XML and XSL support<br />
► JDBC 1.0 support<br />
► Connection pooling<br />
► Simple <strong>WebSphere</strong> Authentication Method (SWAM) with local OS<br />
authorization<br />
Express <strong>Application</strong> <strong>Server</strong> can be installed on the same system as Studio Site<br />
Developer or on a separate system. A Web-based administrative console is<br />
provided to configure the server environment. Administration and operation can<br />
also be performed using the server tools in Studio Site Developer, but this is<br />
primarily for development testing purposes.<br />
The Express <strong>Application</strong> <strong>Server</strong> is supported on Windows NT, Windows 2000,<br />
Windows 2003, Windows XP, Red Hat, SuSe, United Linux, AIX®, Solaris,<br />
HP-UX, and OS/400®.<br />
For specific operating system support information, see:<br />
http://www.ibm.com/software/webservers/appserv/express/requirements/<br />
1.1.3 Database support<br />
1.1.4 CVS server<br />
Most applications built for <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express will feature<br />
Web access to data stored in a database. <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express supports Cloudscape, DB2, SQL, SQL <strong>Server</strong>, Informix®, Sybase,<br />
MySLQ, InstantDB, and Oracle.<br />
A development-use only version of DB2 is included with <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express on a separate CD. The DB2 database serves as a testing<br />
environment if you wish to test your applications on DB2.<br />
For specific database support information, see the <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express v5.0 Installation Guide (which is shipped with the project).<br />
Studio Site Developer provides tools that allow you to use a CVS server to<br />
manage team development. This allows multiple developers to work on the same<br />
application. The CVS server is not included with <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express but can be downloaded from the CVS site. Information about installing a<br />
CVS server can be found in <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.1<br />
Administrator Handbook, SG24-6976.<br />
4 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
1.1.5 Web server<br />
A Web server to act as an application front end is not required, but can be<br />
implemented for added security. Express <strong>Application</strong> <strong>Server</strong> provides a built-in<br />
HTTP server, but it does not contain the type of comprehensive support you<br />
would find in a full Web server product.<br />
A Web server plugin is provided with Express <strong>Application</strong> <strong>Server</strong> that can be<br />
installed with supported Web servers. The plugin allows you to use an external<br />
Web server that serves the HTML content of an application and directs requests<br />
for servlets and JSPs to the Express <strong>Application</strong> <strong>Server</strong>. The Express <strong>Application</strong><br />
<strong>Server</strong> administrative console is used to generate and maintain the HTTP plugin<br />
configuration file needed to route incoming requests.<br />
1.1.6 Testing and deploying applications<br />
Developers install the Studio Site Developer component on a development<br />
machine. An Express <strong>Application</strong> <strong>Server</strong> test environment is embedded in Studio<br />
Site Developer so a stand-alone Express <strong>Application</strong> <strong>Server</strong> for testing is not<br />
required. However, it never hurts to perform a test run of new applications in a<br />
stand-alone Express <strong>Application</strong> <strong>Server</strong> test environment before publishing to a<br />
production server. If this is the case, you can install a stand-alone server on the<br />
development machine or use a test system set up for that purpose.<br />
Although administration of production servers is usually done using the<br />
Web-based administrative console shipped with the Express <strong>Application</strong> <strong>Server</strong>,<br />
in a test environment, developers may perform administration using the Studio<br />
Site Developer server tools.<br />
This book will discuss testing and deploying applications from a developer’s point<br />
of view. This means that we will cover using the server tools of Studio Site<br />
Developer. This is a perfectly acceptable way of configuring and managing both<br />
the embedded test environment and remote servers. As you move into the<br />
production environment, it is more likely that you will want to use the<br />
administrative console for managing the production server. The administrative<br />
console exposes more configuration options and is browser-based, meaning you<br />
don’t have to have Studio Site Developer installed on the machine in order to<br />
manage an Express <strong>Application</strong> <strong>Server</strong>.<br />
Chapter 1. Getting started 5
1.1.7 Roles and responsibilities<br />
In this book, you will see references to people that perform specific functions<br />
(roles).<br />
► <strong>Application</strong> developer. The application developer will build and test<br />
applications using Studio Site Developer. The application developer will need<br />
to have basic Web development skills.<br />
► Express <strong>Application</strong> <strong>Server</strong> administrator: The administrator will install and<br />
maintain the Express <strong>Application</strong> <strong>Server</strong> sites. This includes obtaining and<br />
installing hardware, making the appropriate arrangements for security and<br />
Internet access, and for deploying applications.<br />
► Database administrator. The applications will more than likely require access<br />
to one or more databases. The database administrator is responsible for<br />
obtaining, installing, and implementing a database server. This includes<br />
creating and maintaining databases.<br />
► CVS administrator. A CVS server is required for the team development<br />
environment. The CVS administrator is responsible for obtaining, installing,<br />
and implementing the CVS environment.<br />
Important: This doesn’t mean that you need this many people. All of these<br />
roles can easily be performed by one person. It is simply easier for us to<br />
distinguish which “hat” that person is wearing at the time.<br />
1.2 Information road map<br />
You can find an information roadmap for <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express on the <strong>IBM</strong> <strong>WebSphere</strong> Developer Domain Web site. The URL for the<br />
roadmap is:<br />
http://www7b.boulder.ibm.com/wsdd/zones/was/roadmaps/express/.<br />
You will find the following Web sites, books, and articles useful as you develop<br />
and deploy applications for <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express.<br />
General information<br />
To find information on <strong>IBM</strong> products, see the following sites:<br />
► The <strong>IBM</strong> <strong>Redbooks</strong> site at the following URL:<br />
http://www.ibm.com/redbooks<br />
► The <strong>WebSphere</strong> Developer Domain Web site at the following URL:<br />
http://www.ibm.com/websphere/developer<br />
6 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► The product home page for <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express at the<br />
following URL:<br />
http://www.ibm.com/software/webservers/appserv/express/<br />
Installation<br />
Installation information can be found in the following locations:<br />
► <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.1 Administrator Handbook,<br />
SG24-6976<br />
– Location: The <strong>IBM</strong> <strong>Redbooks</strong> site at the following URL:<br />
http://www.ibm.com/redbooks<br />
– Content: An overview of the different ways to set up a <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express, planning information, and installation<br />
scenarios.<br />
► Express readme file<br />
– Location before installation: launchpad.exe on the installation CD-ROM.<br />
– Location after installation: Start -> Programs -> <strong>IBM</strong> <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> -> Express v5.0.2 -> README or<br />
/readme.html.<br />
– Content: The main readme contains information about the product, known<br />
problems and limitations, and links to installation information and release<br />
notes.<br />
► <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express v5.0 Installation Guide (which<br />
is shipped with the project)<br />
– Location before installation: launchpad.exe on the installation CDROM.<br />
– Location after installation: Link from the Express Readme or<br />
/install.htm.<br />
– Content: The install guide contains information to help you install the<br />
product, including hardware requirements, software requirements, and<br />
install instructions.<br />
Migration<br />
For information on migration issues, see:<br />
► <strong>IBM</strong> <strong>WebSphere</strong> Studio Site Developer Version 5.0 Migration Guide (which is<br />
shipped with the project)<br />
– Location before installation: launchpad.exe on the installation CDROM.<br />
– Location: /migrate.html.<br />
– Content: Information on migrating from previous versions of <strong>WebSphere</strong><br />
Studio or VisualAge® for Java.<br />
Chapter 1. Getting started 7
► Migrating <strong>Application</strong>s from <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> Standard<br />
Edition to <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5, REDP3618<br />
– Location: http://www.ibm.com/redbooks<br />
– Content: Migration process and a sample migration of a simple<br />
application.<br />
<strong>Application</strong> development information:<br />
For information on developing applications with <strong>WebSphere</strong> Studio, see:<br />
► Getting Started (provided with the Studio Site Developer documentation)<br />
– Location before installation: launchpad.exe on the installation CDROM.<br />
– Location: Start -> Programs -> <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express v5.0.2 -> Getting Started or<br />
/gettingstarted.html<br />
– Content: Information to get you started with application programming<br />
using Studio Site Developer, setting up a server environment.<br />
► <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express Handbook, SG24-6555 (this<br />
publication)<br />
– Location: http://www.ibm.com/redbooks<br />
– Contains information on the technology supported by <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express, how to use Site Developer to create<br />
applications, and how to test applications.<br />
► <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express: A Development Example for New<br />
Developers, SG24-6301<br />
– Location: http://www.ibm.com/redbooks<br />
– Contains an example of designing and building an application suitable for<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express.<br />
► Performance tips for <strong>WebSphere</strong> Studio<br />
– Location: /readme/ws/tips.html.<br />
– Content: Contains tips for improving the performance of the Studio Site<br />
Developer.<br />
► <strong>Application</strong> examples<br />
Sample applications are available in Studio Site Developer to illustrate<br />
programming techniques. For more information about these samples see<br />
1.3.1, “<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express examples” on page 11, and<br />
the Getting Started documentation provided with the Studio Site Developer.<br />
8 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► Online help and infopops<br />
The Studio Site Developer provides a complete online help system with<br />
information on creating applications, using the features of Studio Site<br />
Developer, developing Studio Site Developer plug-ins, and JDK reference<br />
information. The online help is accessible from the workbench toolbar.<br />
Infopops are also available for providing help information. To use an infopop,<br />
place the cursor in the field you want information for and press F1.<br />
Express <strong>Application</strong> <strong>Server</strong> administration<br />
In V5.0.1, the administrative console was introduced for system administrators<br />
that are configuring and maintaining a production Express <strong>Application</strong> <strong>Server</strong><br />
environment. Information on using the administrative console can be found in<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.1 Administrator Handbook,<br />
SG24-6976.<br />
► Location: http://www.ibm.com/redbooks<br />
► Contains information on designing and managing an Express <strong>Application</strong><br />
<strong>Server</strong> environment.<br />
Problem determination<br />
For problem determination information see the support site at:<br />
http://www.ibm.com/software/webservers/appserv/express/support.html<br />
There is also a good problem determination chapter on <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> in the <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> V5.0 System Management and<br />
Configuration Handbook, SG24-6195.<br />
Chapter 1. Getting started 9
1.3 Bringing up Studio Site Developer for the first time<br />
Note: Throughout this publication there are references to specific file locations<br />
within <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express. We will use the following<br />
terminology:<br />
► : Refers to the high-level installation directory, for<br />
example, C:\<strong>WebSphere</strong>\Express502 on Windows or<br />
/opt/<strong>IBM</strong>/<strong>WebSphere</strong>/Express502 on Linux<br />
► : Refers to the installation directory for Express<br />
<strong>Application</strong> <strong>Server</strong>, for example, C:\<strong>WebSphere</strong>\Express502\App<strong>Server</strong> on<br />
Windows or /opt/<strong>IBM</strong>/<strong>WebSphere</strong>/Express502/App<strong>Server</strong> on Linux<br />
► : Refers to the installation directory for Studio Site<br />
Developer, for example, C:\<strong>WebSphere</strong>\Express502\SiteDeveloper on<br />
Windows or /opt/<strong>IBM</strong>/<strong>WebSphere</strong>Studio on Linux<br />
► : Refers to the installation directory for the <strong>IBM</strong> Agent<br />
Controller, for example, C:\<strong>WebSphere</strong>\Express502\RAC on Windows or<br />
/opt/<strong>IBM</strong>RAC on Linux<br />
When using this notation, we will use a generic indicator for the directory<br />
structure (forward slashes for all operating systems, versus using a backslash<br />
for Windows.)<br />
If you haven’t installed <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express yet, you should<br />
see <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.1 Administrator Handbook,<br />
SG24-6976 for planning and installation approach information.<br />
The first place to start when getting familiar with <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express is with Studio Site Developer.<br />
1. To get started, bring up Studio Site Developer:<br />
– Windows: Select Start -> Programs -> <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong>-Express V5.0.2 -> Studio Site Developer.<br />
– Linux: /opt/<strong>IBM</strong>/<strong>WebSphere</strong>Studio/wasexpress.<br />
2. The first time you open Studio Site Developer you will be asked to select a<br />
location for the workspace. You can take the default or choose a folder name.<br />
10 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 1-2 Selecting a workspace<br />
3. Load one or more of the <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express examples<br />
included with the product (optional). Continue with the next section to learn<br />
about the sample applications and how to load them.<br />
1.3.1 <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express examples<br />
Studio Site Developer comes with examples designed to illustrate development<br />
and application techniques useful when developing applications with <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express. If you have not used Studio Site Developer before,<br />
or if you are new to J2EE 1.3, looking at the examples is a good way to become<br />
familiar with the process of application development in this environment.<br />
You can use these sample applications as a basis for your own application or as<br />
a reference when coding new applications. You can also use these as a learning<br />
tool. Each sample has a readme file that will describe how to do the base setup<br />
for the application and will point you to instructions for modifying the sample to<br />
add new features.<br />
Among the examples included are five that were specifically developed to<br />
illustrate the capabilities of <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express:<br />
► Document management application: the application allows you to store and<br />
retrieve documents from the server’s file system. Users of the system fall into<br />
one of the following categories: administrator, publisher, or consumer. The<br />
sample illustrates techniques for a simple login and user role scheme, storing<br />
and retrieving files from the server, database searches (both new and “search<br />
on previous search results”). Modification scenarios included are:<br />
– Using SSL<br />
– Adding e-mail<br />
– Encoding stored passwords<br />
► Survey application: this application has two parts. The first provides a voting<br />
booth. Web users can vote on an issue and the votes are tallied for display.<br />
Second, the user can fill out a survey. The user can customize the application<br />
by selecting a language for the interface to be displayed in. The sample<br />
Chapter 1. Getting started 11
illustrates techniques for internationalization, multi-media, and site usage<br />
tracking through logging. Modification scenarios included are:<br />
– Adding a language<br />
– Logging new statistics<br />
► Customer service application: the sample uses an insurance scenario to<br />
illustrate login to a private, SSL-protected user account. Users can see their<br />
claims and update personal information. This sample features<br />
personalization.<br />
► Custom home page application: this sample features a per-employee,<br />
self-customized home page with links to existing Web-based resources. The<br />
home page also has company bulletin, news, stock quotes, and other<br />
informational pages. The sample illustrates personalization based on cookies,<br />
search capability, sorting, and Web service access.<br />
► Your company application: this sample illustrates using HTML pages, style<br />
sheets, tag libraries, and JSPs to build a complete application. It features<br />
personalization, search capability, and a simple conference room reservation<br />
system. The modification scenario included is:<br />
– Adding a user role for personalization<br />
1.3.2 Installing an example application<br />
Loading a sample is easy:<br />
1. Select File -> New -> Other -> Examples -> Web -> sample.<br />
2. Click Next.<br />
3. Most, if not all, of the fields in the next panel are filled out for you. The project<br />
name and context will default to the example name. You will be prompted to<br />
select an enterprise application to add it to or to create a new enterprise<br />
application. More than likely, this is your first project, so you will elect to add a<br />
new enterprise application (see Figure 1-3 on page 13). You can name this<br />
anything you want.<br />
12 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 1-3 Adding an example application<br />
4. Click Finish.<br />
The application will be brought into your workspace where you can begin<br />
exploring its features. The first thing you will see is an introduction to the<br />
application. The introduction is presented in a Web browser window within<br />
Studio Site Developer.<br />
Chapter 1. Getting started 13
Figure 1-4 Customer service example<br />
5. Read the introduction. It will describe the function of the application and tell<br />
you how to deploy the sample to the <strong>WebSphere</strong> test environment.<br />
6. Deploy the sample (the instructions are in the introduction) and try it out. If<br />
you like what you see, explore the application elements. The best way to get<br />
started with this is to first become familiar with the Studio Site Developer<br />
environment by browsing through Chapter 3, “Using Studio Site Developer”<br />
on page 43.<br />
1.3.3 Using application templates<br />
Another way to get started quickly with <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express<br />
is to create an application based on a template. The end result is a<br />
ready-for-deployment application. For example, you could select among the<br />
following templates:<br />
► White pages<br />
► Self-service insurance<br />
14 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► Resource reservation<br />
► Address book<br />
To begin, select File -> New->Template <strong>Application</strong>. You will see a list of<br />
available templates. Click each one to see a description of the template. There<br />
are also additional templates available from a Web site. You can see these by<br />
clicking the Download button.<br />
1.4 The Online Catalog sample<br />
Throughout this publication, we use the Online Catalog sample to illustrate the<br />
various features of <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express. The application is a<br />
simple one that provides a means of publishing an inventory of goods on the<br />
Web and allowing customers to place orders via e-mail or by phone. This is by no<br />
means a replacement for <strong>WebSphere</strong> Commerce applications, but simply a way<br />
for small businesses to make their products known to potential customers.<br />
The application will provide a simple interface for non-programmers to enter<br />
information. Certain items can be identified as feature items. Customers can<br />
browse the information and e-mail the company for information.<br />
The application will be generic enough to apply to a variety of businesses. For<br />
example:<br />
► A business that sells RVs can publish a current inventory of the campers on<br />
its lot.<br />
► A restaurant can publish a takeout menu and provide a call-in number or fax<br />
number.<br />
► A cleaning service can provide a list of services and prices.<br />
For information about downloading the application, see Appendix D, “Additional<br />
material” on page 633.<br />
1.4.1 Sample application overview<br />
The Online Catalog application is a simplified shopping-cart application.<br />
Navigating through the application with a Web browser, users can view the<br />
catalog, search for products, request information, create and manage a wishlist,<br />
and submit the wishlist.<br />
Chapter 1. Getting started 15
From a lower-level perspective, we can outline the list of components that provide<br />
the aforementioned functionality:<br />
► A main application menu, which lists the options available to the user<br />
► A registration process where new users enter their details<br />
► A search mechanism, which provides shoppers with a fast means to find<br />
items of interest, based on a keyword description<br />
► A shopping cart, which lists the items currently selected by the user, and also<br />
provides editing functionality for the user to modify his choices<br />
► An order completion mechanism<br />
1.4.2 Sample database<br />
Data used by our sample application is maintained in database tables. In keeping<br />
with our intent to keep things simple, the tables were designed with a basic<br />
approach in mind, with columns clearly labeled and constraints kept to a<br />
minimum. One may notice that, in some places, the use of constraints and<br />
triggers might have been justified. However, in cases where implementing these<br />
features might have complicated the issue and distracted us from our initial<br />
purpose, we made a conscious decision to do away with them.<br />
User information was not stored directly in our application database. Since<br />
<strong>WebSphere</strong> provides functionality to store user profiles in a predesigned<br />
SALESAPP database, we decided to make use of this feature to simplify the<br />
implementation of an authentication mechanism and storage of user-related<br />
data.<br />
Other types of data are stored in the following tables in a custom-designed<br />
database: CUSTOMERS, SHIPPING_ORDER, USERS, and ITEM.<br />
16 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 2. <strong>Application</strong> design<br />
This chapter provides information on the application design process, geared<br />
toward the development of applications in <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express.<br />
In this chapter, the following topics are discussed:<br />
► <strong>Application</strong> design considerations<br />
► <strong>Application</strong> modeling<br />
► <strong>Application</strong> architecture<br />
► Supporting technologies<br />
► Database design<br />
2<br />
© Copyright <strong>IBM</strong> Corp. 2003 17
2.1 Design considerations<br />
e-business application design presents some unique challenges compared to<br />
traditional application design and development. The majority of these challenges<br />
are related to the fact that traditional applications were primarily used by a<br />
defined set of internal users, whereas e-business applications are used by a<br />
broad set of internal and external users such as employees, customers, and<br />
partners. Web applications must be developed to meet the varied needs of these<br />
end users. The challenges the Web application developer faces include the<br />
following:<br />
► The user experience, look, and feel of the site need to be constantly<br />
enhanced to leverage emerging technologies, and attract and retain site<br />
users.<br />
► New features have to be constantly added to the site to meet customer<br />
demands.<br />
► Such changes and enhancements will have to be delivered at record speed to<br />
avoid losing customers to the competition.<br />
► e-business applications in essence represent the corporate brand online.<br />
Developers have to ensure that the Web site effectively represents the<br />
company image.<br />
► Security requirements are significantly higher for e-business applications<br />
compared to traditional applications. In order to execute traditional<br />
applications from the Web, a special set of security-related software may be<br />
needed to access private networks.<br />
2.1.1 System model for e-business applications<br />
A common model for e-business solution development is based on an n-tier<br />
distributed environment where any number of tiers of application logic and<br />
business services are separated into components that communicate with each<br />
other across a network. In its most basic form, the model can be depicted as a<br />
“logical” three-tier computing model. This means that there is a logical, but not<br />
necessarily physical, separation of processes. This model is designed to support<br />
clients with high-function Web applications and servers for small and large<br />
enterprises. Figure 2-1 on page 19 shows a high-level system model for running<br />
an e-business application.<br />
18 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
First Tier Middle Tier<br />
Third Tier<br />
Thin client,<br />
Browser<br />
Netscape/IE,<br />
PDA,<br />
Mobile phones,<br />
HTML pages,<br />
Web TV<br />
HTTP(S)<br />
Figure 2-1 e-business system model<br />
Web server,<br />
<strong>Application</strong> server,<br />
Transaction server,<br />
Servlets, JSP,<br />
Business Logic<br />
Beans, Data Access<br />
Beans, Connectors<br />
320<br />
TCP/IP<br />
Enterprise<br />
Information<br />
Systems<br />
First tier<br />
The main function of the client in this model is to present information and results<br />
produced by an application to the user. In this system model, the clients are<br />
sometimes referred to as thin clients. This means that little or no application logic<br />
is executed on the client and, therefore, relatively little software is required to be<br />
installed on the client.<br />
Clients are implemented with industry-standard technologies, interact with the<br />
user, communicate with a middle tier via standard protocols, and send and<br />
receive standard data formats. Using the thin client in the model improves<br />
manageability, flexibility, and time to market. This is contrary to the fat client,<br />
which provides higher computing power and storage capacity at the expense of<br />
increased management requirements. Clients can range from pervasive devices,<br />
such as PDAs, smartcards, and digital wireless telephones, to network<br />
computers and PCs.<br />
Chapter 2. <strong>Application</strong> design 19
Note: <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express clients are presumed to be<br />
primarily Web browser clients.<br />
Second tier<br />
Middle-tier servers include a standards-based Web server to interact with the<br />
client tier and define user interaction, and a Web application server to execute<br />
business logic independently of the client type and user interface style. The Web<br />
application server is the platform that provides the runtime environment for the<br />
application's business logic. It is implemented using various Internet and Java<br />
technologies, including the HTTP server and the Enterprise Java services that<br />
enable rapid development and deployment of applications in a distributed<br />
network environment.<br />
Java servlets, Java<strong>Server</strong> Pages, and Enterprise JavaBeans are examples of the<br />
components deployed in the Web application server. These server-side<br />
components communicate with their clients and other application components<br />
via Hypertext Transfer Protocol (HTTP) or IIOP, and use the directory and<br />
security services provided by the network infrastructure. They can also leverage<br />
database, transaction, and groupware facilities.<br />
The middle-tier servers incorporate several application integration technologies<br />
for communicating with applications, data, and services in other tiers. The middle<br />
tier is the core tier in Web enabling an application. The middle tier hosts many<br />
servers and services, including:<br />
► Web servers<br />
► Web application servers<br />
► Transaction servers<br />
► Servlets<br />
► JavaBeans<br />
► Java<strong>Server</strong> Pages<br />
► Connectors<br />
Note: <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express provides a Web application<br />
server that provides support for servlets, JavaBeans, and Java<strong>Server</strong> Pages.<br />
The Web application server includes an internal Web server that supports the<br />
HTML elements of the application. <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express<br />
does not provide support for Enterprise JavaBeans.<br />
Third tier<br />
The Enterprise Information System (EIS) tier includes new and existing internal<br />
applications, services, data, and external applications.<br />
20 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
A significant amount of data resides on the Enterprise Information System.<br />
Examples of EIS include:<br />
► Customer Information Control System (CICS®) server<br />
► Legacy applications developed on mainframes or legacy systems<br />
► Relational databases such as DB2<br />
Connectors provide the link between the new business logic in the middle tier to<br />
the vast accumulated assets in a company's existing applications and data<br />
systems.<br />
Note: <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express provides JDBC connectivity to<br />
back-end relational databases. <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express also<br />
supports the creation and use of Web services.<br />
2.1.2 <strong>IBM</strong> Patterns for e-business<br />
The job of an IT architect is to evaluate business problems and to design a<br />
solution. The architect begins by gathering input on the problem, the desired<br />
solution, and any special considerations or requirements that need to be factored<br />
in. The architect takes this input and designs a solution that includes one or more<br />
applications that provide the necessary functions.<br />
It is to our advantage to capture the experience of these IT architects in such a<br />
way that future engagements are made simpler. By taking this experience and<br />
crafting a repository we provide a way for architects to use this experience to<br />
build future solutions. Using proven scenarios saves time and money for both<br />
sides and helps ensure a solid solution that will stand the test of time.<br />
The <strong>IBM</strong> Patterns for e-business effort does just this. Its purpose is to capture<br />
e-business approaches that have been tested and proven. The information<br />
captured is thought to fit the majority of situations. By making these approaches<br />
available and classifying them into useful categories, we save the e-business<br />
planners, architects, and developers both time and money.<br />
These approaches are further refined into useful, tangible guidelines. The<br />
patterns and their associated guidelines allow the architect to start with a<br />
problem and a vision, find a conceptual pattern that fits this vision, define the<br />
necessary functional pieces that the application will need to succeed, and then<br />
actually build the application using coding techniques outlined in the guidelines.<br />
The <strong>IBM</strong> Patterns for e-business Web site (below) contains the information and<br />
references you need to design and build a solution from beginning to end.<br />
http://www.ibm.com/developerworks/patterns/<br />
Chapter 2. <strong>Application</strong> design 21
Note: <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express applications will largely fall<br />
into the Self-service pattern. This pattern describes situations where users are<br />
interacting with a business application to view or update data.<br />
2.2 Modeling an application<br />
The best way to begin an application design is by laying out the function of the<br />
application in a model. The model is used to illustrate the way the application is<br />
seen by the end users, and shows how the components of the application work<br />
together to provide the results required by the user.<br />
The Unified Modeling Language (UML) is the industry standard language for<br />
modeling software systems, providing practice for modelling large complex<br />
systems. Although <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express is geared toward<br />
simpler applications, it is a good idea to become familiar with UML and to use it<br />
as a basis for designing your applications. More information about UML can be<br />
found at:<br />
http://www.omg.org<br />
In UML, diagrams are used to model a solution. The most basic is the use-case<br />
diagram. Use cases are a way to illustrate to the user/developer functionality of a<br />
system. The two main components of a use-case model are actors that represent<br />
external elements and use cases that represent functions provided by the<br />
system.<br />
This discussion is an over-simplification of the process geared toward the more<br />
basic applications. For a more in-depth study of application design and modeling,<br />
see <strong>WebSphere</strong> Version 4 <strong>Application</strong> Development Handbook, SG24-6134.<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express does not provide a modelling function,<br />
but there are many tools available for this; see the following Web sites:<br />
► Rational® Rose® from Rational<br />
http://www.rational.com<br />
► ArgoUML<br />
http://argouml.tigris.org<br />
► Magicdraw<br />
http://magicdraw.com<br />
22 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
2.2.1 Use-case analysis<br />
The use-case analysis describes the functional requirements of the application<br />
under development. It defines how users in specific roles will use the system<br />
through use cases. The use case is from the user’s point of view and does not<br />
describe how tasks within the application are accomplished.<br />
Note: Throughout this publication, we will use a sample called the Online<br />
Catalog to illustrate the various features of <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express. The application will be a simple one that provides a means of<br />
publishing an inventory of goods on the Web and allowing customers to place<br />
orders via e-mail or by phone.<br />
Details about the sample application can be found in Appendix C, “Online<br />
Catalog application” on page 611.<br />
A use-case analysis basically includes the following elements:<br />
► Actor<br />
► Use case<br />
► Communication associations between actors and use cases<br />
► Relationships between use cases<br />
► Flow of events and system sequence diagrams<br />
Together these items provide an overview of the functional requirements and<br />
document the expected usage, user interactions, and behavior of the system in<br />
different styles and depth. The level of detail you go into is determined by the size<br />
and complexity of the application. In the case of our simple application, we will<br />
define the use cases and actors, but will not be building any detailed diagrams.<br />
Actors<br />
The first step in designing the application flow is to determine who will be<br />
interacting with the application and what types of activities they will perform. The<br />
people that interact with the application are known as actors in UML and are<br />
represented by a stick figure in the following figures, as shown in Figure 2-2.<br />
Actor<br />
Figure 2-2 UML notation of an actor<br />
Chapter 2. <strong>Application</strong> design 23
Actors can be identified by asking users questions such as who uses the system<br />
and who manages the system. In our Online Catalog sample the answers to<br />
these questions are:<br />
► Buyer<br />
► Business owner<br />
As you can see, in our example these actors are fairly simple and distinct. The<br />
function of each within the application appears to be different, based on the<br />
names. If the distinction is not as clear in your application, consider things such<br />
as security levels or training required for the user.<br />
Use cases<br />
Use cases depict interaction between the actor and the system. They represent<br />
functionality available to an actor. A collection of transactions that can be<br />
identified as a unit of work is a good candidate for a use case. Use cases are<br />
depicted by a ellipse in UML notation, as shown in Figure 2-3.<br />
Use Case<br />
Figure 2-3 UML notation of a use case<br />
Use-case model analysis usually starts with an overall main use-case diagram<br />
with actors and major use cases. In the case of our sample application, we see<br />
two main interaction types with the application. These two interactions are<br />
identified as:<br />
► Maintain inventory<br />
► Buys item<br />
Figure 2-4 on page 25 shows the main use-case diagram for our sample. You<br />
can see the major use cases and the relationship with the actors.<br />
24 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Business O wner<br />
Buyer<br />
Figure 2-4 Main use-case diagram<br />
The model can then be decomposed into more detailed use cases, as shown in<br />
Figure 2-5.<br />
Update Inventory<br />
Buy Item<br />
Register<br />
Business Owner<br />
Create Shipping<br />
Order<br />
Validate Buyer<br />
Login<br />
Buyer<br />
Figure 2-5 More detailed use-case diagram<br />
M ain tain In ve n to ry<br />
Buys Item<br />
Update Prices<br />
View Items<br />
Request Info<br />
Set Featured Item<br />
Chapter 2. <strong>Application</strong> design 25
The maintain inventory use case has been furthered detailed to show the<br />
activities that are necessary to keep a current inventory:<br />
► Update inventory<br />
► Update prices<br />
► Set featured item<br />
The buys item use case has been broken down into the possible activities the<br />
customer can perform, including:<br />
► View items<br />
► Buy item<br />
► Register<br />
► Requests info<br />
2.3 Determine the application-flow architecture<br />
Web application developers in the Java and J2EE environment employ<br />
technologies such as servlets, Java<strong>Server</strong> Pages (JSPs), JavaBeans, and tag<br />
libraries to build dynamic interactive Web applications.<br />
Using these technologies, applications can range in complexity from very simple<br />
applications that return simple data from local resources, to very complex<br />
applications that perform many tasks, including interacting with other<br />
applications.<br />
Over time, two programming models have emerged that are often referred to as<br />
Model 1 and Model 2 architecture. Model 1 architecture is more suited to small<br />
applications where separation of presentation from business logic activities<br />
seems to introduce more complexity than is needed. Model 2 architecture<br />
addresses the more complex applications where separation of tasks becomes<br />
the best method of building efficient, maintainable applications.<br />
2.3.1 Model 1 architecture<br />
The Model 1 architecture is focused on page-centric applications. That is, the<br />
browser navigates through a series of JSP pages where the JSPs process their<br />
own input. The user will proceed from the first page to the next based on the<br />
input provided to the JSP.<br />
The sample applications supplied in <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express<br />
were developed using the Model 1 architecture to demonstrate the simplicity of<br />
building dynamic, interactive applications to an audience that may have a<br />
background with HTML and JavaScript, but only a limited background with Java.<br />
26 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 2-6 shows the typical flow of a Model 1 application.<br />
Browser<br />
Figure 2-6 Model 1 architecture application flow<br />
For small projects, prototyping, and to quickly get an application completed, the<br />
Model 1 architecture is quite popular because of its ease of development.<br />
However, more complex applications will need to follow a different approach.<br />
That approach is described as Model 2 architecture.<br />
2.3.2 Model 2 architecture<br />
1<br />
Request<br />
Response<br />
3<br />
<strong>Application</strong> <strong>Server</strong><br />
2<br />
JSP Database<br />
The all servlet and all JSP approach both have inherent problems mixing the<br />
business logic of servlets with presentation of HTML. These two approaches<br />
cause applications to become difficult to maintain and less flexible. For these<br />
reasons, Model 2 architecture was introduced. Model 2 is basically a<br />
Model-View-Controller (MVC) architecture (see 2.3.3, “MVC architectural<br />
pattern” on page 28) that separates the business logic and content presentation.<br />
Model 2 applications are more flexible and easier to maintain and extend<br />
because the business logic and the presentation are isolated from one another.<br />
Chapter 2. <strong>Application</strong> design 27
Input Page<br />
(View)<br />
Display Page<br />
(View)<br />
Figure 2-7 Model 2 architecture application flow<br />
2.3.3 MVC architectural pattern<br />
1<br />
Request<br />
Response<br />
5<br />
Serlvets<br />
(Control)<br />
Display Page<br />
JSP<br />
(View)<br />
Model 1 versus Model 2: It is not the intention of this publication to single out<br />
any one model as being better than the other. For the purposes of <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express and the targeted market of <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express, the Model 1 architecture is better suited. As<br />
mentioned earlier, Model 1 architecture lends itself towards small projects that<br />
can be developed quickly or when development teams do not have strong<br />
Java servlet skills. That said, it is important to note that using the Model 1<br />
architecture will hinder future scalability of applications. Extending the<br />
application using Model 1 architecture becomes difficult since the page<br />
presentation is so tightly coupled to the business logic. If a project is planned<br />
for future growth, then a Model 2 or MVC architecture is recommended and<br />
encouraged. It may be beneficial to “pay now versus pay later” to gain the<br />
flexibility provided by the MVC design pattern.<br />
The model-view-controller architectural pattern was conceived in the mid-1980s<br />
by developers of the Smalltalk-80 GUI library. It has since then been extensively<br />
applied in most object-oriented user interface and application control toolkits. It<br />
has also been generalized as a pattern for implementing the separation of<br />
concerns among application layers in general, not only the three originally<br />
proposed layers.<br />
According to the MVC pattern, a software component (an application, a module,<br />
and so forth) should separate its business logic (the model) from its presentation<br />
(the view). There are many reasons for this requirement, among which are the<br />
following.<br />
28 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
3<br />
Interactive<br />
2<br />
4<br />
<strong>Application</strong> <strong>Server</strong><br />
JavaBean<br />
(Model)<br />
Database
► You may have more than one view of the same model. If both the business<br />
logic and its presentation were built together, adding an additional view would<br />
cause considerable disruptions and increase the component's complexity. A<br />
good example of a model with two views would be a banking application that<br />
can be accessed through both the Internet and mobile phones.<br />
► You do not want to have to change the model every time you modify the view.<br />
The view is definitely dependent on the model, since it presents specific<br />
aspects of the model to the user. It makes no sense, however, to have the<br />
model depend on the view. Building both together dramatically increases the<br />
chances of this happening, and of you having to change the model every time<br />
you implement a small change to the view.<br />
This separation can be achieved through the layering of the component into:<br />
► The model layer, responsible for implementing the business logic.<br />
► The view layers, each responsible for rendering the user interface (be it<br />
graphical or not) to a specific client type and in a specific fashion.<br />
With these two layers, we can implement the business logic and present it to the<br />
user. That solves only half of the problem. We would also like to be able to<br />
interact with the model. The implementation of this interaction is better left to a<br />
third layer, called controller.<br />
This model-view-controller structure has several benefits:<br />
► You can isolate development effort to some extent, so that implementation<br />
changes in one part of the Web application do not require changes to another.<br />
The developers responsible for writing the business logic can work<br />
independently of the developers responsible for the flow of control, and<br />
Web-page designers can work independently of the developers.<br />
► You can more easily prototype your work. For example, you might:<br />
– Create a prototype Web application that accesses several<br />
workstation-based programs.<br />
– Change the application in response to user feedback.<br />
– Implement the production-level programs on the same or other platforms.<br />
Outside of the work you do on the programs themselves, your only<br />
adjustments are to configuration files or name-server content, not to other<br />
source code.<br />
► You can more easily migrate legacy programs, because the user interaction is<br />
the same wherever those programs run and however they interact with data<br />
stores.<br />
► You can maintain an environment that comprises different technologies<br />
across different locations.<br />
Chapter 2. <strong>Application</strong> design 29
In the following sections, we discuss some of the properties of each of these<br />
layers.<br />
Model<br />
The model layer manages the application domain’s concepts, both behavior and<br />
state. It responds to requests for information about its state and responds to<br />
instructions to change its state.<br />
Just like any software component, the model should have a public interface that<br />
is well defined and as simple as possible. This is usually achieved through the<br />
use of a facade. The intent of facades is to provide a simple and unified interface<br />
to the otherwise complex model that lies behind it. By doing so, we reduce the<br />
dependencies between the model classes and its clients. Fewer dependencies<br />
means more freedom to adapt to new requirements.<br />
Note: Facade is a documented design pattern. For more information, refer to<br />
Design Patterns: Elements of Reusable Object-Oriented Software.<br />
As an example, consider an appliance with which you are certainly familiar: a<br />
television set. You will probably agree that changing TV channels is quite a<br />
simple task. Now ask yourself these questions:<br />
► Do you know how the television set represents channels internally?<br />
► Do you know exactly what goes on when you change TV channels?<br />
► Do you think you should know these things?<br />
Chances are that you have answered no to all of the questions above. What is<br />
the advantage of not knowing how TVs represent their data and implement their<br />
operations? You could buy a new TV, which does these things internally in a<br />
completely different way, and you could still change channels.<br />
Figure 2-8 on page 31 shows the model layer with its encapsulated business<br />
domain objects and the exposed facade object.<br />
30 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Façade<br />
Figure 2-8 Model layer<br />
Model<br />
Please note that the model does not have any dependences on views or<br />
controllers.<br />
View<br />
The view layer implements a rendering of the model. The responsibility of the<br />
view is to know what parts of the model’s state are relevant for the user, and to<br />
query the model for that information. The view retrieves the data from the model<br />
or receives it from the controller, and displays it to the user in a way the user<br />
expects.<br />
Controller<br />
The controller’s responsibility is to capture user events and to determine which<br />
actions each of these events implies, depending on both the user’s and the<br />
application’s state. This usually involves verifying pre- and post-conditions.<br />
These actions can then be translated to messages to the model and view layers,<br />
as appropriate.<br />
Dependencies between MVC layers<br />
Figure 2-9 on page 32 shows the dependencies allowed in the MVC pattern.<br />
Note that the fewer dependencies your layers have, the easier it will be for the<br />
layers to respond to requirement changes.<br />
Chapter 2. <strong>Application</strong> design 31
Figure 2-9 Dependencies allowed in the MVC pattern<br />
So, to summarize, the MVC pattern is really about separation.<br />
2.4 Reviewing the supporting technologies<br />
2.4.1 JavaScript<br />
A B A depends on B<br />
Controller View<br />
Model<br />
<strong>Application</strong>s written for deployment on <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express<br />
are uniquely suited to the following technology options.<br />
Browser-based or client-side JavaScript is common. <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express also supports server-side JavaScript through the Bean<br />
Scripting Framework (BSF) of the Express <strong>Application</strong> <strong>Server</strong>.<br />
BSF enables you to use scripting language functions in your Java server-side<br />
applications. This framework also extends scripting languages so that you can<br />
use existing Java classes and JavaBeans in the JavaScript language. With BSF,<br />
you can write scripts that create, manipulate, and access values from Java<br />
objects, or you can write Java programs that evaluate and access results from<br />
scripts. BSF provides an access mechanism to Java objects for the scripting<br />
languages it supports, so that both the scripting language and the Java code can<br />
access code exclusive functions. The access mechanism is implemented<br />
through a registry of objects maintained by BSF.<br />
BSF in <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express supports the Rhino<br />
ECMAScript. The implementation is standard client-side JavaScript with all client<br />
object references removed and with the following server-side objects added:<br />
32 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
2.4.2 Servlets<br />
► request<br />
► response<br />
► pageContext<br />
► session<br />
► application<br />
► out<br />
► config<br />
► page<br />
► exception<br />
Java servlets are Java alternatives to Common Gateway Interface (CGI)<br />
programs. As with CGI programs, Java servlets can respond to user events from<br />
an HTML request, and then dynamically construct an HTML response that is sent<br />
back to the client. Java servlets have the following advantages over traditional<br />
CGI programs:<br />
► Java-based<br />
Because Java servlets are written in Java, they inherit all the benefits of the<br />
Java technologies.<br />
► Persistence and performance<br />
A servlet is loaded once by a Web server and invoked for each client request.<br />
Java servlets do not incur the overhead of instantiating a new servlet with<br />
each request. CGI processes typically must be loaded with each invocation.<br />
Java servlets can work better than CGI programs, especially for business logic<br />
and control flow.<br />
However, for a servlet to return an HTML page to a browser, it must output HTML<br />
from within the Java code. A Java programmer has to write many out.println<br />
statements to return the HTML. This mixes the roles of the content developer and<br />
the Java programmer, even limiting the usefulness of content-authoring tools.<br />
Java<strong>Server</strong> Pages were developed to address the problem of writing HTML<br />
statements in Java source code.<br />
2.4.3 Java<strong>Server</strong> Pages<br />
Java<strong>Server</strong> Pages are an HTML extension for doing server-side scripting in Web<br />
pages. Java<strong>Server</strong> Pages are similar to HTML files, but provide the ability to<br />
display dynamic content within Web pages. Here are some of the advantages of<br />
using Java<strong>Server</strong> Pages technology over other methods of dynamic content<br />
creation:<br />
Chapter 2. <strong>Application</strong> design 33
2.4.4 Tag libraries<br />
► Separation of dynamic and static content<br />
This allows for the separation of application logic and Web page design,<br />
reducing the complexity of Web site development and making sites easier to<br />
maintain.<br />
► Platform independence<br />
Because Java<strong>Server</strong> Pages technology is Java-based, it is<br />
platform-independent. Java<strong>Server</strong> Pages can run on nearly any Web site<br />
application server. Java<strong>Server</strong> Pages can be developed on any platform and<br />
viewed by any browser because the output of a compiled JSP page is HTML.<br />
► Scripting and tags<br />
Java<strong>Server</strong> Pages support both embedded Java and tags. Java is typically<br />
used to add page-level capability to the Java<strong>Server</strong> Pages. Tags provide an<br />
easy way to embed and modify JavaBean properties and to specify other<br />
directives and actions.<br />
While Java<strong>Server</strong> Pages look like HTML pages that access dynamic data, they<br />
are actually Java servlets. The application server compiles Java<strong>Server</strong> Pages<br />
and executes them. Being a servlet is what allows Java<strong>Server</strong> Pages to easily<br />
add dynamic content.<br />
Because Java<strong>Server</strong> Pages solved the problem of having HTML produced by<br />
Java code, many Web applications were written solely as Java<strong>Server</strong> Pages<br />
(known as JSP Model 1).<br />
However, while Java<strong>Server</strong> Pages are good for producing HTML, they are not<br />
good for writing business logic and control because having Java code inside<br />
Java<strong>Server</strong> Pages could easily make them hard to read or maintain.<br />
You will also notice that the sample applications leverage custom tag libraries<br />
whenever possible. Custom tag libraries contain Java code that provides a<br />
function. The tag library can be used from any JSP page. They are a powerful<br />
way to include server-side logic using HTML-like syntax. All of the complexities of<br />
the server-side logic are hidden in the tag library. However, not all methods of<br />
server-side beans may be exported as tags. For this reason, the samples<br />
occasionally use Java scriptlets to access unexposed methods.<br />
Tag libraries reduce the necessity of embedding large amounts of Java code in<br />
JSP pages by moving the functionality provided by the tags into tag<br />
implementation classes. In doing so, tag libraries make authoring JSP pages<br />
easier, both for the Web page author and for tools that expose the functionality<br />
encapsulated by the library to the author.<br />
34 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
2.4.5 XML<br />
2.4.6 Web services<br />
Tag libraries increase productivity by encouraging division of labor between<br />
library developers and library users. JSP tag libraries are created by a developer<br />
who is an expert at accessing data and other services, and used by Web page<br />
authors who can focus on the design of user interfaces.<br />
Finally, JSP tag libraries are portable; they can be used by any JSP page<br />
independent of the page's scripting language, any authoring tool supporting tag<br />
libraries, and any JSP 1.1-compliant server.<br />
eXtensible Markup Language (XML) is a markup language for the exchange of<br />
structured documents. It is a meta-language, meaning a language for defining<br />
other languages. XML by itself does not define any tags; it provides a facility to<br />
define custom tags and the structural relationships between them.<br />
XML documents are text-based and composed of markup and content:<br />
► Markup instructs XML processors about how to treat the content, and how it is<br />
organized.<br />
► Content is the character data you would see on a printed or displayed page.<br />
Web services are self-contained, modular applications that can be described,<br />
published, located, and invoked over a network. Web services perform<br />
encapsulated business functions, ranging from simple request-reply to full<br />
business process interactions.<br />
These services can be new applications or just wrapped around existing legacy<br />
systems to make them network-enabled. Services can rely on other services to<br />
achieve their goals.<br />
The core technologies used for Web services are:<br />
► XML<br />
► SOAP<br />
► WSDL<br />
► UDDI<br />
Chapter 2. <strong>Application</strong> design 35
2.4.7 Struts<br />
Struts is an open-source framework for building MVC-based Web applications.<br />
Struts is part of the Jakarta project, sponsored by the Apache Software<br />
Foundation. The Struts framework provides the benefits of modularity, flexibility,<br />
and reusability of components, combined with the easy development associated<br />
with MVC-based Web applications.<br />
The goal of the Struts project is to provide an open-source framework useful in<br />
building MVC-based Web applications using servlet and JSP technologies. From<br />
an MVC point of view, Struts provides the following.<br />
► Model: nothing. The business logic must be provided by the Web application<br />
developer, usually as Java objects (JavaBeans or Enterprise JavaBeans).<br />
► View: an org.apache.struts.action.ActionForm class to create form beans that<br />
are used to pass data between the controller and the view. In addition, Struts<br />
provides custom tag libraries that assist developers in creating interactive<br />
form-based applications.<br />
► Controller: an org.apache.struts.action.Action class that developers use to<br />
create the classes that control the flow of the application. Also, Struts<br />
provides an org.apache.struts.action.ActionServlet class to implement a<br />
controller servlet.<br />
Struts also provides utility classes to support XML parsing, automatic population<br />
of JavaBeans properties based on the Java reflection APIs, and<br />
internationalization of prompts and messages.<br />
A typical Struts Web application has a single servlet that uses an XML file for<br />
configuration information. There will be multiple action classes and JSPs (using<br />
the Struts taglibs).<br />
For more information on Struts, we recommend the following:<br />
► Go-ForIt Chronicles, Part 19: Struttin' your stuff with <strong>WebSphere</strong> Studio<br />
tutorial from <strong>IBM</strong> DeveloperWorks. To see the list of tutorials, go to:<br />
http://www.ibm.com/developerworks/<br />
Select the <strong>IBM</strong> developer solutions product domain and then select<br />
Education.<br />
► For information on using Struts with <strong>WebSphere</strong> Studio products, see Legacy<br />
Modernization with <strong>WebSphere</strong> Studio Enterprise Developer, SG24-6806.<br />
Although written for the Enterprise Developer configuration of <strong>WebSphere</strong><br />
Studio, the information on Struts is also relevant for Studio Site Developer.<br />
► The Jakarta Struts home page at:<br />
http://jakarta.apache.org/struts<br />
36 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► The introduction guide at:<br />
http://jakarta.apache.org/struts/userGuide/introduction.html<br />
► The following articles on Struts in the VisualAge for Java zone of <strong>WebSphere</strong><br />
Developer Domain at:<br />
http://www7b.software.ibm.com/wsdd/<br />
– Apache Struts and VisualAge for Java, Part 1: Building Web-based<br />
<strong>Application</strong>s using Apache Struts<br />
– Apache Struts and VisualAge for Java, Part 2: Using Struts in VisualAge<br />
for Java 3.5.2 and 3.5.3<br />
2.5 Designing the database<br />
2.5.1 Normalization<br />
Database design is one of the most important steps in Web application design.<br />
Here we will discuss a few things to be kept in mind as we develop the database<br />
model for our application. When you design tables you must choose an<br />
appropriate data model and data types for them. You also need to be aware of<br />
the pros and cons of creating indexes and be thoughtful in determining their<br />
usefulness.<br />
In this section, we will explain some database concepts that need to be applied<br />
to create a sound, efficient data model.<br />
Normalization is the process of determining the structure of database tables. The<br />
objective is to introduce flexibility into the structure, while reducing redundant<br />
data. The reduction in data can improve the performance of update and delete<br />
statements, since the data is only touched once. By normalizing data, you try to<br />
ensure that all columns in the table depend on the primary key.<br />
There are four levels or degrees of normalization. We will limit our discussion to<br />
the third normal form for the sake of simplicity and to be within the scope of this<br />
publication.<br />
First normal form<br />
In the first normal form, each cell in the table is atomic, meaning that it contains<br />
only one value.<br />
Second normal form<br />
In the second normal form, each non-key column is dependent upon the entire<br />
key and not just part of the composite key.<br />
Chapter 2. <strong>Application</strong> design 37
2.5.2 Indexes<br />
Third normal form<br />
In the third normal form, each non-key column is dependent upon the key column<br />
as in the second normal form, but is also independent of other non-key columns.<br />
In Table 2-1 we can see that the DeptName column is dependent on the DeptNo<br />
column. This table does not conform to the third normal form. If we update<br />
DeptName for one employee, it would not automatically update the DeptName<br />
column for other employees belonging to the same department<br />
Table 2-1 Table not in third normal form<br />
EMPNO(Primary Key) LastName DeptNo DeptName<br />
001 Brown 01 Support<br />
002 Smith 02 Sales<br />
To normalize this data to conform to the third normal form, we would create two<br />
tables. The first table, Table 2-2, contains the relation between the employee and<br />
the department number. The second table, Table 2-3, contains the relation<br />
between the department number and the department name. An update to the<br />
department name only needs to be done once.<br />
Table 2-2 Table in third normal form<br />
EMPNO(Primary Key) LastName DeptNo<br />
001 Brown 01<br />
002 Smith 02<br />
Table 2-3 Table in third normal form<br />
DeptNo(Primary Key) DeptName<br />
01 Support<br />
02 Sales<br />
One consideration when normalizing tables is that the more you normalize, the<br />
better it results in insert and update performance. However, it can slow down the<br />
query response time.<br />
Indexes are used to improve query performance. They provide a faster<br />
mechanism to search the database table for a particular column value(s) and<br />
avoid expensive and slower table scans. Columns of a table that are often used<br />
in search clauses are prime candidates for indexes. The downside of indexes is<br />
that they take up disk space and slow execution of insert and update statements.<br />
38 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
2.5.3 Datatypes<br />
Datatypes is a column attribute definition used when creating tables. The<br />
datatype tells us what kind of data will be held in the column and what length it<br />
will be. Care should be taken when selecting datatype and size for a column to<br />
ensure that it can hold all possible values for that column and at the same time<br />
not be so large that it bloats the table and database size, thus adversely affecting<br />
performance.<br />
2.5.4 Deriving the data model from the use-case model<br />
As we saw in the requirements, the entities that interact with the Online Catalog<br />
sample are buyer and business owner. The buyer views and buys items. The<br />
business owner maintains the item inventory and pricing information.<br />
We came up with the following entities that map to the business requirements of<br />
the Online Catalog sample.<br />
► Customer: This entity contains all attributes/information about a buyer who<br />
buys from the online store.<br />
► Item: This entity contains all attributes/information about items on sale in the<br />
online store.<br />
► ShippingOrder: This entity contains all information needed to complete a<br />
shipping order.<br />
► Users: This entity contains the user name/password of all admin users.<br />
The data model of the tables required by the Online Catalog sample is shown in<br />
Figure 2-10 on page 40.<br />
Chapter 2. <strong>Application</strong> design 39
CUSTOMER<br />
CUSTOMER_ID :CHAR(10)<br />
CUSTOMER_NAME :VARCHAR(40)<br />
ADDRESS :VARCHAR(40)<br />
CITY :VARCHAR(40)<br />
STATE :CHARACTER(2)<br />
EMAIL_ADDRESS :VARCHAR(20)<br />
PHONE :CHAR(10)<br />
CC_TYPE :CHAR(2)<br />
CC_NUMBER :VARCHAR(20)<br />
ZIP : CHAR(5)<br />
INTEREST1 : CHAR(1)<br />
INTEREST2 : CHAR(1)<br />
PASSWORD : CHAR(10)<br />
USERS<br />
USERNAME :CHAR(8)<br />
PASSWORD :CHAR(8)<br />
Figure 2-10 Data model for the Online Catalog sample application<br />
As you proceed through the publication, you will see how the database built<br />
based on this model is used by the application.<br />
2.6 For more information<br />
For more information, see the following sources:<br />
► Understanding Java<strong>Server</strong> Pages Model 2 architecture<br />
http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html<br />
► <strong>IBM</strong> Framework for e-Business: Technology, Solution, and Design Overview<br />
SG24-6248<br />
► More information about UML<br />
http://www.omg.org<br />
ORDER_NUMBER : INTEGER<br />
CUSTOMER_ID :CHAR(10)<br />
ITEM_NUMBER :CHAR(5)<br />
QUANTITY :INTEGER<br />
SALE_PRICE :DECIMAL(9,2)<br />
ORDER_DATE :DATE<br />
STATUS :CHAR(1)<br />
SHIPPING_ORDER<br />
► <strong>WebSphere</strong> Version 4 <strong>Application</strong> Development Handbook, SG24-6134<br />
40 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
ITEM<br />
ITEM_NUMBER :CHAR(5)<br />
ITEM_SHORT_DESC :VARCHAR(15)<br />
ITEM_LONG_DESC : VARCHAR(150)<br />
QUANTITY :INTEGER<br />
PRICE :DECIMAL(9,2)<br />
SOTD_FLAG :CHAR(1)
► <strong>IBM</strong> Patterns for e-business<br />
http://www.ibm.com/developerworks/patterns/<br />
► Rational Rose from Rational<br />
http://www.rational.com<br />
► ArgoUML<br />
http://argouml.tigris.org<br />
► Magicdraw<br />
http://magicdraw.com<br />
Chapter 2. <strong>Application</strong> design 41
42 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3<br />
Chapter 3. Using Studio Site Developer<br />
Studio Site Developer reduces time and effort when creating, managing, and<br />
debugging multi-platform Web applications. This easy-to-use toolset supports the<br />
visual layout of dynamic Web pages. It is rich in wizards and aids that support<br />
Web development and deployment. It includes a unit test environment for testing<br />
applications and provides the operational and configuration interface for remote<br />
application servers.<br />
This chapter will introduce the Studio Site Developer workbench and its features.<br />
The topics covered are:<br />
► Workbench overview<br />
► Perspectives, views, and editors<br />
► The workspace<br />
► Finding help<br />
► Recovering files<br />
© Copyright <strong>IBM</strong> Corp. 2003 43
3.1 The workspace<br />
Studio Site Developer maintains a workspace where the project data (files) are<br />
stored. Every time you save a resource, the changes are stored in the file<br />
system. The first time Studio Site Developer starts, you are given the option to<br />
select a directory for the workspace or take the default. The installation default on<br />
Windows is:<br />
C:\Documents and Settings\userid\My Documents\<strong>IBM</strong>\wasexpress\<br />
workspace<br />
For Linux, the default is:<br />
$home/<strong>IBM</strong>/wasexpress/workspace<br />
Figure 3-1 Selecting the workspace<br />
In this window, you also have the option of suppressing the message on future<br />
startups and always using the current directory you specify.<br />
Tip: If you choose to suppress the workspace option at startup, you can<br />
change your mind later. Simply start Studio Site Developer with the following<br />
commands:<br />
cd <br />
wasexpress -setworkspace<br />
The option box will appear during the startup.<br />
Since there is a memory overhead associated with having multiple projects in the<br />
workspace at the same time, you may wish to configure multiple workspaces for<br />
different projects. This reduces the amount of clutter in the navigator views, and<br />
also minimizes the number of entries in the <strong>Server</strong> control panel, making it easier<br />
to find a particular server configuration or instance. Each workspace is created<br />
as a separate folder in the file system.<br />
44 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Tip: If you want to skip the option box, but would like to change workspaces,<br />
you can start Studio Site Developer with the following command:<br />
wasexpress -data workspace_name<br />
For example:<br />
wasexpress -data c:\user-workspace<br />
If the workspace directory does not exist, it will be created.<br />
If you have sufficient memory available on your workstation, it is possible to<br />
execute multiple instances of Studio Site Developer running simultaneously<br />
using different workspaces. This technique is useful, for example when working<br />
on two releases of a project at the same time, such as building a new release and<br />
performing maintenance on an old one. Each development branch can have its<br />
own workspace and copies of the project files.<br />
3.1.1 Recovering files from their local history<br />
When working with Studio Site Developer, there are two things to remember:<br />
► All deletes are permanent. There is no recycle bin.<br />
► A history of all changes is maintained locally and files can be reset to a<br />
previous state.<br />
A history of all files that you have changed is cached locally. This allows you to<br />
compare a resource with a previous version and, if required, replace it with that<br />
version. The local history of each file is updated when you create or modify a file.<br />
Each time you save a file, a copy of its previous state is also saved. A new history<br />
for a resource is created the first time you modify the base version of it.<br />
This allows you to compare the current file state to a previous state and to<br />
replace the file with a previous state. Each state in the local history is identified<br />
by the date and time the file was saved.<br />
Note: Only files have local histories, not projects or folders.<br />
Comparing a file to the local history<br />
To view the local history of a file, select the file in the navigator view, right-click,<br />
and select Compare with -> Local History from its context menu.<br />
Chapter 3. Using Studio Site Developer 45
Figure 3-2 Compare with Local History window<br />
Each version kept in the local history is listed at the top. Select the listing to<br />
compare that version with the current copy. The differences are highlighted in the<br />
window below.<br />
Replacing a file with a copy from the local history<br />
You can also revert to the previous state of a file by selecting Replace With -><br />
Local History from the context menu of the resource in the navigator view.<br />
Note: These local histories are independent of the team development<br />
environment and the shared team repository.<br />
Setting preferences for local history<br />
You can set the amount of disk space along with other history attributes for<br />
Studio Site Developer to use for local history information on the Workbench<br />
Preferences page (Window -> Preferences -> Workbench -> Local History).<br />
46 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3.2 Perspectives<br />
Figure 3-3 Local history preferences<br />
Perspectives provide different ways of viewing and working with resources. A<br />
perspective consists of a set of views, editors, and toolbar options suited to the<br />
task most likely performed within that perspective. For example, the <strong>Server</strong><br />
perspective is designed with server or unit test environment operation in mind.<br />
There is a view for the server console, a view that shows server configurations, a<br />
view that allows you to start and stop servers, and so forth. The Web perspective<br />
is designed for a Web application developer and, by default, views and tools are<br />
available that are most suited for that task.<br />
For example, Figure 3-4 on page 48 shows the default layout for the Web<br />
perspective. The Web perspective is used primarily to develop Web application<br />
resources, such as HTML and JSP files.<br />
Chapter 3. Using Studio Site Developer 47
Shortcut bar<br />
Figure 3-4 Web perspective<br />
Open perspective<br />
Each pane you see in Figure 3-4 represents a view, and the tabs you see below<br />
the panes can be used to toggle that pane to show another view. Note that there<br />
are several views visible and some that are not. The toolbar at the top will contain<br />
tools relevant to the perspective and view. As you change perspectives or views,<br />
you will see the toolbar change also.<br />
For example, the top right pane in this perspective is the editor area. In this area<br />
you can see a JSP open in the Source view. By selecting the tab at the bottom of<br />
the pane, you can see the same file using the Design view, which presents a<br />
graphical view of the file. Multiple files can be open simultaneously for editing.<br />
The workbench window can have several perspectives opened, but only one is<br />
visible at one point in time. You can switch easily between perspectives by<br />
clicking the different icons in the shortcut bar.<br />
48 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Toolbar<br />
Multiple files open for editing
3.2.1 Editors<br />
You can open a new perspective from the toolbar by selecting Window -> Open<br />
Perspective or by clicking the top icon of the shortcut bar.<br />
Among the predefined perspectives you will find in Studio Site Developer are<br />
those listed in Table 3-1. These are the perspectives we found to be the most<br />
commonly used during Web application development in a <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express environment.<br />
Table 3-1 Perspectives<br />
Perspective Task<br />
Web For building HTML and JSP files. This is the primary<br />
perspective used for application development in <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express, and you will see it used<br />
throughout the publication.<br />
CVS Repository For team development tasks using Concurrent Version System<br />
(CVS). You will see this perspective used in Chapter 15,<br />
“Development in a team environment” on page 515.<br />
Data For connecting to JDBC databases and working with database<br />
design. You will see this perspective used in Chapter 6,<br />
“Accessing databases” on page 153.<br />
<strong>Server</strong> For configuring and operating the runtime test and production<br />
environments. You will see this perspective used in Chapter 13,<br />
“Deploying applications” on page 455.<br />
XML For working with XML resources. You will see this perspective<br />
used in Chapter 10, “Working with XML” on page 309.<br />
Perspectives can easily be customized to suit your needs and just as easily reset<br />
to their original configuration. You can also compose your own perspective by<br />
defining the views it should contain. You will see the more commonly used<br />
perspectives in more detail in the appropriate chapters.<br />
Resource types used in Web applications have default editors associated with<br />
them. When you double-click a resource in the workbench the associated editor<br />
for that type opens the file for editing. For example, in Figure 3-4 on page 48, the<br />
active editor is the Page Designer, which is associated with JSP and HTML files.<br />
If no editor is currently associated with a particular file extension, the Workbench<br />
checks to see if there is one associated in the operating system and, if so, uses<br />
that editor to open the file.<br />
You can change or add editors associated with a file extension using preference<br />
settings:<br />
Chapter 3. Using Studio Site Developer 49
3.2.2 Using fast views<br />
1. From the menu bar, select Window -> Preferences.<br />
2. In the left panel, select File Associations under the Workbench hierarchy.<br />
3. You can then select a file extension and associate an internal or external<br />
editor for it.<br />
You can have multiple resources that use different editors open simultaneously.<br />
Switching between them in the editing pane is as easy as selecting the file name<br />
on the top bar above the editor area. If there is an asterisk (*) to the left of the file,<br />
it means that it contains unsaved changes.<br />
Tip: When you open a file and then switch perspectives, Studio Site Developer<br />
will keep the file synchronized between the perspectives. To conserve system<br />
resources it is good practice to do the following:<br />
► Close perspectives that you do not need.<br />
► Do not open multiple perspectives of the same type (it is allowed).<br />
► Close resources open in the editor area when you no longer need them<br />
open.<br />
You do not have to recustomize a perspective just to see a view that is not<br />
normally available from the perspective. You can open a view as a fast view for<br />
temporary use.<br />
Whether a view opens as a fast view or not is determined by the perspective<br />
preferences:<br />
1. Open Window -> Preferences -> Workbench -> Perspectives.<br />
2. In the Open a New View box, select As a fast view.<br />
3. Click OK to close the preference box.<br />
This setting says that if you are in a perspective and open a view (Window -><br />
Show View) that is not in the perspective, the view will be opened temporarily in<br />
the perspective. An icon representing the view will show in the shortcut bar on<br />
the left. The view will only remain in sight as long as it is current (you have the<br />
cursor in it). If you move the cursor outside the view and click, the fast view will<br />
disappear. You can bring it back by selecting the icon.<br />
For example, in Figure 3-5 on page 51, we have opened the Java Hierarchy view<br />
from within the J2EE perspective. The view initially opens in the left half of the<br />
perspective and an icon is placed in the shortcut bar.<br />
50 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
New icon<br />
Figure 3-5 Using fast views<br />
To remove the icon, right-click it and select Close.<br />
Java Hierarchy view<br />
You can also designate views in the perspective as fast views. This effectively<br />
removes them from the perspective and puts an icon in the shortcut bar. To do<br />
this right-click the title bar of the view and select Fast View. For example, if you<br />
took the Properties view in Figure 3-5 and made it a fast view, you would no<br />
longer see the Properties tab, but would instead see an icon for the view in the<br />
toolbar (see Figure 3-6 on page 52). The view would only be active when you<br />
select the icon. Moving the cursor to another view would hide the view.<br />
Chapter 3. Using Studio Site Developer 51
New icon<br />
Figure 3-6 Designating a view as a fast view<br />
The fast views are only defined for the current perspective and will only exist as<br />
long as the perspective is open. This does not mean that you cannot switch from<br />
perspective to perspective without losing the fast view, but if you select the<br />
perspective in the shortcut bar, right-click, and select Close you will.<br />
If you want to retain the fast views across Studio sessions, you should save the<br />
perspective.<br />
3.2.3 Customizing perspectives<br />
Properties view<br />
Properties tab has been removed<br />
You can customize perspectives by:<br />
► Closing or opening views. Views can be opened with the Window -> Show<br />
View option. A view can be closed by clicking the X at the top right corner of<br />
the view.<br />
► Maximizing a view by double-clicking the title bar. This is useful when you<br />
need a large window for code editing. Double-click again to restore the layout.<br />
► Moving views to other panes or stacking them behind other views. To move a<br />
view:<br />
52 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
a. Select the view's title bar and start dragging the view.<br />
b. While you drag the view, the mouse cursor changes to a drop cursor. The<br />
drop cursor indicates what will happen when you release the view you are<br />
dragging:<br />
The floating view appears below the view underneath the cursor.<br />
The floating view appears to the left of the view underneath the<br />
cursor.<br />
The floating view appears to the right of the view underneath the<br />
cursor.<br />
The floating view appears above the view underneath the cursor.<br />
The floating view appears as a tab in the same pane as the view<br />
underneath the cursor.<br />
You cannot dock the floating view at this point.<br />
► Double-clicking the title bar of a view to make it fill the window. Double-click<br />
the title bar again to return it to normal size and position.<br />
► Adding views. You can add a view by doing the following:<br />
a. Open the perspective you want to customize.<br />
b. From the main menu bar, select Window -> Show View.<br />
c. Select the view you want to add and click OK.<br />
d. The view will dock in its default position but can be moved to any location.<br />
► Saving the perspective either by overlaying the original definition or under a<br />
new name by selecting Window -> Save Perspective As.<br />
Important! Until you are confident that you want to permanently change<br />
the perspective, we recommend that you save it as a new perspective.<br />
Once you overlay a perspective definition, you cannot reset it to its original<br />
state.<br />
To reset a perspective to its saved state, select Window -> Reset Perspective<br />
from the main menu.<br />
3.2.4 Setting perspective preferences<br />
There are a few preferences you can set globally for perspectives. These<br />
preferences can be seen by selecting Window -> Preferences -> Workbench -><br />
Perspectives. The options you have are as follows.<br />
Chapter 3. Using Studio Site Developer 53
3.3 Finding help<br />
► Select a default perspective. Selecting a default simply assures that the<br />
perspective is visible in the list of perspectives when you select Window -><br />
Open Perspective.<br />
► Determine whether perspectives are opened in the existing window or new<br />
window.<br />
► Determine whether views are opened in the existing window or as a fast view.<br />
► By default, when you create a new project, you are automatically switched to<br />
the appropriate perspective to work with that project. If the perspective is not<br />
already open, it is opened. You can select whether the new perspective is<br />
opened in the same window, in a new window, or not opened/switched to.<br />
Figure 3-7 Preferences menu<br />
The workbench provides an online help system that includes a full-text search<br />
engine and context-sensitive interface help designed to help you find any<br />
necessary information quickly and easily.<br />
54 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
You can find help information in one of two ways:<br />
► Infopops show context-related help. You can see infopop information by<br />
placing the cursor in the field or window you want help with and pressing F1.<br />
► Online help contains a full set of documentation that you can browse based<br />
on the contents or search. To reach the online help select Help -> Help<br />
Contents from the workbench menu.<br />
The online help is organized into the following categories:<br />
► Web developer information: Designed for application development. This will<br />
be the primary information set for the conventional Studio Site Developer<br />
user.<br />
► Tool developer information: Designed for tool developers who are extending<br />
the Studio Site Developer workbench to include new application development<br />
tools.<br />
► J2SE SDK 1.3.1 APIs and J2EE SDK 1.3.1 APIs: API documentation for the<br />
Java 2 SDK. It is based on the API documentation provided by Sun<br />
Microsystems for the Java 2 Platform, Standard Edition, Version 1.3.1.<br />
► <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express: Documentation for the Express<br />
<strong>Application</strong> <strong>Server</strong> component.<br />
► Support Information: Contains FAQs and technical documents related to Site<br />
Developer, <strong>Application</strong> <strong>Server</strong> V5 and Express, Cloudscape, and DB2UDB.<br />
Figure 3-8 Online help<br />
Chapter 3. Using Studio Site Developer 55
The online help is laid out in an easy-to-use format. From the Help window you<br />
can print out a topic so that it can be read off-line or marked up for reference.<br />
To synchronize the navigation frame with the current topic, you can click the<br />
Show in Table of Contents button. This is helpful if you have followed several<br />
links to related topics in several files and want to see where the current topic fits<br />
into the navigation path.<br />
As an alternative to browsing the information in sequence, you can use the<br />
search engine. To do so, enter a word or phrase to search in the Search box and<br />
click GO.<br />
56 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 4. Working with Web<br />
applications<br />
4<br />
This chapter provides an overview of Web applications, how they are built, and<br />
how they are treated at runtime. In this chapter we will discuss:<br />
► Enterprise applications<br />
► Web applications<br />
► Web projects<br />
► Packaging<br />
► Deployment descriptors<br />
► Studio support and tools<br />
► <strong>Server</strong> support<br />
Note: Throughout this publication you will see the terms Web module, Web<br />
application, and Web project. For the context of this publication they all mean<br />
the same thing and are used interchangeably. The same is true for the terms<br />
enterprise application, enterprise application project, and enterprise<br />
application module.<br />
© Copyright <strong>IBM</strong> Corp. 2003 57
4.1 Enterprise application<br />
An enterprise application project contains the hierarchy of resources that are<br />
required to deploy an enterprise (J2EE) application. It can contain a combination<br />
of Web modules, EJB modules, JAR files, and application client modules. It<br />
includes a deployment descriptor and an <strong>IBM</strong> extension document, as well as<br />
files that are common to all J2EE modules that are defined in the deployment<br />
descriptor. It can contain a complete application that may be a combination of<br />
multiple modules. Enterprise applications make it easier to deploy and maintain<br />
code at the level of a complete application instead of as individual pieces.<br />
Enterprise <strong>Application</strong> projects are exported as enterprise archive (EAR) files<br />
that include all files defined in the enterprise application project as well as the<br />
appropriate module archive file for each J2EE module project defined in the<br />
deployment descriptor, such as Web archive (WAR) files and EJB JAR files.<br />
An enterprise application may contain JAR files to be used by the contained<br />
modules. This allows sharing of code at the application level by multiple Web or<br />
EJB modules.<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express does not support EJB modules, so the<br />
typical enterprise application built and deployed with <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express will consist primarily of Web modules and supporting JAR files.<br />
4.1.1 Enterprise application deployment descriptor<br />
The enterprise application deployment descriptor contains information about the<br />
components that make up the enterprise application. This deployment descriptor<br />
is called application.xml and is located under the META-INF directory.<br />
Figure 4-1 on page 59 shows the deployment descriptor for an enterprise<br />
application called OnlineCatalogEar. The enterprise application contains one<br />
Web module called OnlineCatalog.<br />
58 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 4-1 Enterprise Deployment Descriptor<br />
As you can see, the deployment descriptor is in XML format. The application<br />
element is the root element and contains information about the enterprise<br />
application and its elements. The module element represents a single J2EE<br />
module, which can contain EJB, Web, or Java elements. You can also see the<br />
security-role element that contains the J2EE roles to be used for application<br />
security.<br />
4.2 Web application<br />
The Java Servlet Specification 2.3 and the J2EE specification contain the<br />
concept of a Web application. A Web application contains Java<strong>Server</strong> Pages,<br />
servlets, applets, Java classes, HTML files, graphics, and descriptive meta<br />
information that connects all these elements. The format is standardized and<br />
compatible between multiple vendors.<br />
The specification also defines a hierarchical structure for the contents of a Web<br />
application that can be used for deployment and packaging purposes. Many<br />
servlet containers, including the one provided by Express <strong>Application</strong> <strong>Server</strong>,<br />
support this structure.<br />
Chapter 4. Working with Web applications 59
Elements contained within a Web application<br />
Any Web resource can be included in a Web application, including the following:<br />
► Servlets and Java<strong>Server</strong> Pages.<br />
► Utility classes: Standard Java classes may be packaged in a Java archive<br />
(JAR) file. JAR is a standard platform-independent file format for aggregating<br />
files (mainly Java classes files).<br />
► Static documents: HTML files, images, sounds, videos, etc. This term<br />
includes all the documents a Web server is able to handle and to provide to<br />
client requests.<br />
► Client side applets, beans, and classes.<br />
► Descriptive meta information, which ties all of the above elements together.<br />
► Custom Tag Libraries<br />
► Struts<br />
► XML files<br />
► Web Services<br />
Directory structure<br />
The directory structure for a Web application requires the existence of a<br />
WEB-INF directory. This directory contains Java and support classes that contain<br />
application logic. Access to these resources is controlled through the servlet<br />
container, within the application server.<br />
Figure 4-2 on page 61 shows an example of a typical directory structure under<br />
the WEB-INF directory.<br />
60 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
web.xml<br />
WEB-INF<br />
Figure 4-2 The WEB-INF directory: A sample structure<br />
lib<br />
classes<br />
myjar.jar Servlet1.class mypackage<br />
Servlet2.class<br />
Servlet3.class<br />
The required elements are:<br />
► web.xml: This file is required and is the deployment descriptor for the Web<br />
application.<br />
► lib: This directory is required and is used to store all the Java classes used in<br />
the application. This directory will typically contain JAR files, including tag<br />
libraries.<br />
► classes: This directory is also required. Typically, servlet classes and utility<br />
classes for the servlets compose this directory. It is possible to keep a<br />
package structure in this directory and to put class files under several<br />
subdirectories of the classes directory (as it is done for the Servlet2.class file<br />
in the subdirectory mypackage in Figure 4-2).<br />
Although there are no other requirements for the directory structure of a Web<br />
application, we recommend that you organize the resources in separate logical<br />
directories for easy management; for example, an images folder to contain all<br />
graphics.<br />
The deployment descriptor<br />
As with the enterprise application, a deployment descriptor exists for the Web<br />
application. The Web deployment descriptor, web.xml, contains elements that<br />
describe how to deploy the Web application and its contents to the servlet<br />
container within the Web server. Note that JSPs execute as servlets and are<br />
treated as such in the Web deployment desciptor. The information in the Web<br />
deployment descriptor includes:<br />
Chapter 4. Working with Web applications 61
► A set of initialization parameters for the servlet context object. All the servlets<br />
running in the same Web application have the same servlet context and can<br />
access these attributes.<br />
► Servlet information: For each servlet we will find its name, its fully qualified<br />
class name or the path leading to its file for a JSP, and its parameters for<br />
initialization (these parameters belong to the servlet and will not be shared<br />
with other servlets). We will also find out whether the servlet must be loaded<br />
when the server is started, and a set of mapping rules, allowing a servlet to<br />
respond to requests for a set of URLs.<br />
► A list of default files (welcome pages) to send to the user when the request<br />
does not specify any file in a directory. Typically index.html, index.htm, and<br />
index.jsp may be used here.<br />
► A list of error pages to send to the user when the request generates an error.<br />
HTTP errors or Java errors (exceptions) may be handled in that way.<br />
► JSP and other tag libraries used within the Web application.<br />
► References to external resources and enterprise beans: These references<br />
can then be easily located by the servlets. It can include entries in the JNDI<br />
lookup table, the location of enterprise bean interfaces, or simply a<br />
declaration of an application’s environment entry.<br />
► Security constraints: the access to some resources can be limited and<br />
configured in the deployment descriptor. These resources are grouped into<br />
collections and the constraints are on these collections.<br />
► Any other type of information useful during the deployment to the servlet<br />
container. It may include the description of the application (including if it is<br />
distributable), timeout settings, additional information about mime mapping,<br />
and so on.<br />
The deployment descriptor file enables the application configuration to be<br />
specified independently from the server. It clearly simplifies the deployment<br />
process because the same application can be deployed into different servers<br />
without having to review its content.<br />
A Web deployment descriptor is shown in Example 4-1.<br />
Example 4-1 Web deployment descriptor<br />
<br />
<br />
<br />
OnlineCatalog<br />
<br />
SearchItemMasterView<br />
SearchItemMasterView<br />
62 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Wishlist/SearchItemMasterView.jsp<br />
<br />
username<br />
db2admin<br />
<br />
<br />
password<br />
db2admin<br />
<br />
<br />
driverName<br />
COM.ibm.db2.jdbc.app.DB2Driver<br />
<br />
<br />
url<br />
jdbc:db2:SALESAPP<br />
<br />
<br />
<br />
LoginServlet<br />
LoginServlet<br />
common.LoginServlet<br />
<br />
<br />
SearchItemMasterView<br />
/SearchItemMasterView<br />
<br />
<br />
LoginServlet<br />
/LoginServlet<br />
<br />
<br />
index.html<br />
index.htm<br />
index.jsp<br />
default.html<br />
default.htm<br />
default.jsp<br />
<br />
<br />
http://jakarta.apache.org/taglibs/page-1.0<br />
/WEB-INF/lib/page.jar<br />
<br />
<br />
Chapter 4. Working with Web applications 63
Some elements of Example 4-1 on page 62 are discussed below.<br />
► is the root element and encompasses all other elements.<br />
► contains information for a servlet or JSP, including initialization<br />
parameters.<br />
► defines a mapping between a servlet and a URL pattern.<br />
This allows the servlet to be referenced in the application by a generic name.<br />
► contains an ordered list of welcome files in it. This is<br />
useful when a valid partial request is received. In such cases the server<br />
appends each welcome file in the order mentioned in this element and sends<br />
the request to the first resource that it matches.<br />
► is used to describe each tag library used in the application.<br />
Web application archive concept<br />
Along with the Web application concept, the Java Servlet Specification 2.3 also<br />
specifies a file format named Web archive (WAR) to package Web applications.<br />
All the elements contained within a Web application are compressed into a WAR<br />
file for deployment. Using WAR files allow Web applications to be packaged in a<br />
platform-independent way.<br />
4.2.1 A Web application in an application server<br />
Within the server the Web application is rooted at a specific path called the<br />
context path. All the requests from clients beginning with this path will be routed<br />
to the application.<br />
All the Java components of the same Web application share information and<br />
have access to the same pool of resources. This information is encapsulated in<br />
the servlet context provided by the servlet container. Since there is one and only<br />
one servlet context per Web application, servlet instances of a Web application<br />
will point to the same ServletContext instance.<br />
An application server can contain many Web applications with every Web<br />
application rooted to a specific path. The server manages a servlet context for<br />
each of these Web applications.<br />
The server is responsible for encapsulating the data sent by the client into an<br />
HttpServletRequest object. This task includes identifying the following elements,<br />
obtained from the client’s request for a URL:<br />
► Context path: The path prefix leading to the Web application. This context<br />
path is associated with the servlet context of the application.<br />
► Servlet path: The section of the requested URL that directly corresponds to<br />
the mapping that activated this request. Typically, mapping consists of<br />
64 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
associating a servlet or a resource with a set of URLs. For each request<br />
pointing to one of these URLs, the servlet will be invoked.<br />
► Path info: The last part of the URL, not identified as part of the servlet path.<br />
The concatenation of these three elements is the request Uniform Resource<br />
Identifier (URI) path or URL path. It represents the URL passed by a request to<br />
invoke a servlet. For example,<br />
http://www.ibmapp.com/OnlineCatalog/Administration/AddNewtem.jsp can be<br />
broken down as follows:<br />
► Request URI path: /OnlineCatalog/administration/AddNewtem.jsp<br />
► Context path: /OnlineCatalog (it represents the path prefix where the Web<br />
application was deployed)<br />
► Servlet path: /administration/AddNewItem.jsp<br />
The servlet will have access to these elements that can be configured on the<br />
deployment descriptor or later on the servlet container for each Web application.<br />
4.3 Working with Web applications<br />
Studio Site Developer is designed for working with J2EE applications. It has<br />
wizards that aid you with creating enterprise and Web modules, including the<br />
required directory structure and elements. The deployment descriptors for both<br />
are automatically created and maintained. When you need to update the<br />
deployment descriptor, an editor just for this purpose is provided.<br />
4.3.1 Creating an enterprise application<br />
In Studio Site Developer, all non-static Web projects belong to an enterprise<br />
application project.<br />
There are several ways to go about creating an enterprise application project:<br />
► Use the Create New Enterprise <strong>Application</strong> Project wizard.<br />
This wizard can be started by selecting File -> New -> Project. Select J2EE<br />
in the left pane and Enterprise <strong>Application</strong> Project in the right.<br />
The wizard creates the enterprise application, the deployment descriptor, and<br />
the directory structure. You also have the option to create a Web module<br />
and/or an application client module.<br />
Chapter 4. Working with Web applications 65
Although this wizard allows you to create the Web module, it does not take<br />
you through the same process as you would see in the Create a New Web<br />
Project wizard. Because of this, we found this method of creating an<br />
enterprise application project to have limited usefulness. As you will see in the<br />
next two bullets, there are other ways to create an enterprise project that we<br />
find more useful.<br />
If you do use this method, you will be automatically switched to the J2EE<br />
perspective. Be sure to switch back to the Web perspective to continue<br />
working on the Web project.<br />
► Create the enterprise application as a part of the Create a New Web Project<br />
wizard. This is the method we will use in this example.<br />
► If you are importing a Web project, you can create the enterprise application<br />
as you go through the import wizard.<br />
We recommend that you start by creating the Web project and let that wizard<br />
create the enterprise application project for you.<br />
4.3.2 Creating a Web project<br />
To illustrate creating a Web project (Web module) we will use the Online Catalog<br />
example. From the Web perspective, do the following:<br />
1. Select File -> New -> Dynamic Web Project (or select New -> Project -><br />
Web -> Dynamic Web Project from the context menu in the Project<br />
Navigator view).<br />
2. Enter the project name, OnlineCatalog, and verify that the Configure<br />
advanced options check box is selected. Using the advanced options will,<br />
among other things, allow you to select the enterprise application for this<br />
project.<br />
66 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 4-3 Creating a Web Project<br />
3. Click Next.<br />
4. Click New... beside the EAR Project listbox.<br />
Chapter 4. Working with Web applications 67
Figure 4-4 Creating a Web Project<br />
5. Enter OnlineCatalogEAR as the Project name.<br />
68 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 4-5 Creating a Web Project<br />
6. Click Finish. This will create the OnlineCatalogEAR Enterprise <strong>Application</strong><br />
Project.<br />
7. Verify that the J2EE 1.3 level is selected. The context root will default to the<br />
Web project name.<br />
Chapter 4. Working with Web applications 69
Figure 4-6 Creating a Web Project<br />
8. Click Next.<br />
Tip: You have several Web Project Features to choose from. These are for<br />
your convenience and can be selected after the Web project has been<br />
created. To access the Web Project Features, select your Web project and<br />
then select Project -> Properties from the main menu. From the<br />
Properties window, select Web Project Features. The Available Web<br />
Project features list allows you to select the available features for your Web<br />
project.<br />
9. Select JSP Tag Libraries to include all the supported tag libraries to the<br />
project.<br />
70 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 4-7 Creating a Web Project<br />
10.Click Next.<br />
Important: A new feature of the New Web Project wizard allows you to<br />
select a default template for your project. Once selected, the template will<br />
be applied to any new pages created using Web Site Designer. Web Site<br />
Designer can be accessed by expanding your Web project and<br />
double-clicking Web Site Configuration from the project directory<br />
structure.<br />
11.Select the Use a default Page Template for the Web Site check box.<br />
12.Select the Sample Page Template radio button.<br />
13.From the Thumbnail selection box, scroll down to and select B-01_blue.htpl.<br />
Chapter 4. Working with Web applications 71
Figure 4-8 Creating a Web Project<br />
14.Click Finish.<br />
The new Web project will be created. This includes the appropriate directory<br />
structure, the style sheet, and Web deployment descriptor. A module entry for<br />
this Web module is added to the enterprise application deployment descriptor.<br />
4.3.3 Web project directory structure<br />
Figure 4-9 on page 73 shows the directory structure created for the Web project.<br />
72 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 4-9 Directory structure<br />
Next, we describe some of the specifics of the directory structure:<br />
► Web Site Configuration: Double-clicking this item will open up the Web site<br />
diagram editor. The Web site diagram has a corresponding file<br />
(.website-config) located in the root of the project.<br />
► Web Deployment Descriptor: Double-clicking this item will open up the Web<br />
deployment descriptor editor. The editor can also be opened by<br />
double-clicking the corresponding web.xml file located in the<br />
WebContent/WEB-INF folder.<br />
► JavaSource: Contains the project's Java source code for classes, beans, and<br />
servlets. When these resources are added to a Web project, they are<br />
automatically compiled, and the generated files are added to the<br />
WEB-INF/classes directory. The contents of the source directory are not<br />
packaged in WAR files unless an option is specified when a WAR file is<br />
created.<br />
Chapter 4. Working with Web applications 73
► WebContent: The location of all Web resources, including HTML, JSP, graphic<br />
files, and so on. If the files are not placed in this directory (or in a subdirectory<br />
structure under this directory), the files will not be run on the server. The Web<br />
Content folder represents the contents of the WAR file that will be deployed to<br />
the server.<br />
► WebContent/META-INF: This directory contains the MANIFEST.MF file, which<br />
is used to map class paths for dependent JAR files that exist in other projects<br />
in the same enterprise application project. An entry in this file will update the<br />
runtime project class path and Java build settings to include the referenced<br />
JAR files.<br />
► WebContent/theme: The suggested directory for cascading style sheets and<br />
other style-related objects, including all files related to any Web site templates<br />
as used through Web Site Designer.<br />
► WebContent/WEB-INF: Based on the Sun Microsystems Java Servlet 2.3<br />
specification, this directory contains the supporting Web resources for a Web<br />
application, including the web.xml file and the classes and lib directories. You<br />
can also access the web.xml file by double-clicking Web Deployment<br />
Descriptor from the root of the project.<br />
► WebContent/WEB-INF/classes: This directory is for servlet classes, utility<br />
classes, and the Java compiler output directory. The classes in this directory<br />
are used by the application class loader to load the classes. Folders in this<br />
directory will map to package and class names. Do not place any class files<br />
directly into this directory. They are placed here automatically when the Java<br />
compiler compiles Java source files. Any files placed directly in this directory<br />
will be deleted by the compiler when it runs.<br />
► WebContent/WEB-INF/lib: The supporting JAR files that your Web application<br />
references. Any classes in .jar files placed in this directory will be available for<br />
your Web application. Tag libraries used in the application are also located in<br />
this directory.<br />
► Libraries: Contains the supporting JAR files that your Web application<br />
references. This folder mirrors the content of the lib folder. In addition, Web<br />
Library Projects, which are "virtual" JAR files that do not physically reside in<br />
the Web project, but are associated with Java projects elsewhere in your<br />
workspace, are included in this folder.<br />
74 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
4.3.4 <strong>Application</strong> templates<br />
Instead of creating applications from scratch, Studio Site Developer users have<br />
the option of creating applications based on pre-defined templates. The end<br />
result is a ready-to-deploy application, generated with little effort. Studio Site<br />
Developer provides a library of predefined templates. You can use these, or add<br />
your own templates for future use. Additional templates are also available for<br />
download.<br />
The Template <strong>Application</strong> Wizard (File -> New -> Template <strong>Application</strong>) guides<br />
you through the process of selecting a template, customizing it, and generating<br />
the application. The wizard allows you to select a template from the library, from<br />
custom templates that you have created and saved, or from the Web using a<br />
download button that takes you to the Web site.<br />
Chapter 4. Working with Web applications 75
76 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 5. Working with HTML<br />
5<br />
The most basic of all Web application components is the HTML Web page. We<br />
will continue our discussion on using Studio Site Developer by showing you how<br />
to build a simple Web page. The content of this chapter includes:<br />
► Studio Site Developer tool support for working with HTML<br />
► The new Web Site Designer support included with <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express V5.0.2<br />
► An example that illustrates how to use the Web Site Designer and page<br />
templates<br />
© Copyright <strong>IBM</strong> Corp. 2003 77
5.1 HTML support in Studio Site Developer<br />
Building HTML pages is probably the most basic of all Web development<br />
activities. Studio Site Developer provides extensive support for working with<br />
HTML, including tool bars, wizards, content assist aids, validation and syntax<br />
checking, graphics tools, and other types of support you would expect from a<br />
mature Web development tool.<br />
5.1.1 Using the Web perspective<br />
Figure 5-1 Web perspective<br />
The Web perspective is the primary perspective used to build Web project<br />
components. The default views have been selected and placed to facilitate<br />
working on HTML and JSP files. The Web perspective can be opened by<br />
selecting Window -> Open Perspective -> Web.<br />
78 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
You can see the default layout of the Web perspective in Figure 5-1 on page 78.<br />
Project files in the Project Navigator view show a structured view of the<br />
application. Double-clicking a file in the navigator will open it in the editor area<br />
(center) using the Page Designer.<br />
The toolbar and drop-down options at the top give you easy access to tools and<br />
wizards designed to make building Web applications easy. The items in the<br />
toolbar change based on the active editor and resource. You can control the<br />
options you see to some extent by modifying the toolbar viewing options in the<br />
Toolbar drop-down.<br />
The default views in the Web perspective are designed and positioned for<br />
optimum efficiency. Note that the default layout for perspectives tends to change<br />
over time from one product release to another. This can be due to new views,<br />
usability feedback, or just the fact that developers have discovered a more<br />
convenient and popular way of doing things. In Studio Site Developer V5.1, the<br />
Web perspective has the following views in its default layout:<br />
► Project Navigator<br />
► Gallery<br />
► Struts Explorer<br />
► Attributes<br />
► Styles<br />
► Thumbnails<br />
► Quick Edit<br />
► Tasks<br />
► Colors<br />
► <strong>Server</strong>s<br />
► Palette<br />
► Snippets<br />
Other views may appear as you perform tasks. For example, the first time you<br />
test an application and use the <strong>Server</strong>s view, the Console view will appear.<br />
We will discuss a few of the default views briefly here, and in addition, a few other<br />
views that we find helpful in working with Web applications. For information about<br />
adding views and rearranging the views on your workspace, see 3.2.3,<br />
“Customizing perspectives” on page 52. The descriptions of all views can be<br />
found in the Studio help text.<br />
Chapter 5. Working with HTML 79
Project Navigator view<br />
The Project Navigator view shows the application resources in a project-oriented<br />
hierarchy. There are three kinds of resources:<br />
Files Files correspond to files in the file system.<br />
Folders Folders are like directories in the file system. They can contain<br />
files as well as other folders.<br />
Projects Projects organize resources into logical application components.<br />
When you create a new project, for example, an enterprise<br />
application or Web project, a new folder is created for the project<br />
with the appropriate folder structure beneath it in the workspace.<br />
The structure shown in the navigator aligns with the structure of J2EE enterprise<br />
and Web applications.<br />
Attributes view<br />
The Attributes view shows you the attributes of the selected element in the editor<br />
and allows you to change them. For example, if the cursor in the editor is within a<br />
table tag, you will see table attributes in the Attributes view. You can set things<br />
like the table or cell background colors, text alignment within the cell, and the size<br />
of the cell. If the cursor is within a link, the attributes will show you the URL to link<br />
to, the window to open, and other link attributes.<br />
In Figure 5-1 on page 78, the cursor in the editor area is immediately after the<br />
tag. In the Attributes view, you have access to the attributes you can set<br />
for that tag. If the cursor was situated within a table, the Attributes view would<br />
look like Figure 5-2.<br />
Figure 5-2 Attributes view for table attributes<br />
80 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Tip: To set the attributes of an element, you must have that element selected<br />
or place the cursor within the tag that defines the element. Sometimes this can<br />
be tricky using the Design view since you cannot see the source tags. Add the<br />
Outline view to your perspective and use it to select the correct element, then<br />
switch back to the Attributes view.<br />
Thumbnail and Gallery views<br />
The Gallery view gives you a list of predefined resources that can be placed in<br />
the open file. The resources available include images, wallpaper, Webart<br />
(buttons, logos, arrows, and illustrations), sound files (.wav and .mid formats),<br />
and style sheet files.<br />
When you open any of the folders in the Gallery view, the available files are<br />
displayed in the Thumbnail view.<br />
Figure 5-3 Thumbnails and Gallery views<br />
Gallery view<br />
Thumbnails view<br />
The Gallery view, working together with the Thumbnail view, allows you to easily<br />
add or apply the files available in the gallery to your HTML file. To use the gallery:<br />
1. Open the folder (for example, the Image folder) in the Gallery view.<br />
Chapter 5. Working with HTML 81
2. From the Thumbnails view, drag the desired thumbnail (image file) to the<br />
appropriate location in the HTML page. Or, double click the thumbnail and it<br />
will be added to the current cursor location in the open HTML page.<br />
If you select a style sheet (.css) file, the new style will be applied to the target<br />
page, and a link to the style sheet will be added to the HTML source in the proper<br />
location.<br />
Links view<br />
The Links view shows Web pages that link to the current file, and the Web pages<br />
that the open file links to. The Links view is an important tool in keeping track of<br />
the overall flow of the application and in maintaining the integrity of the links in<br />
the application.<br />
The current file is the focus (center) of the view. Which file is current depends on<br />
where the cursor is. If the cursor is positioned in a file in the editor area, then that<br />
file is current and will be in the center of the Links view. If you have selected a file<br />
in the Project Navigator view, that file is current.<br />
You can open any of the files in the view by double-clicking their icon. Opening a<br />
new file, changes the Links view so that the new file is current. Holding the cursor<br />
over a file will give you a pop-up showing you the full directory location. A “+” icon<br />
means that the file has links that aren’t displayed in the view. You can display<br />
them click clicking the plus sign.<br />
In Figure 5-4, you can see that AddNewItem.jsp is the current file (it is situated in<br />
the middle of the view). There is one broken link (represented by a line with<br />
double slashes) to back.gif.<br />
Figure 5-4 Links view<br />
broken link<br />
Table 5-1 on page 83 shows the symbols you will see in the view and their<br />
meaning.<br />
82 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Table 5-1 Links view symbols<br />
Symbol Description<br />
This arrow indicates that the link is to<br />
a file outside the Web content folder.<br />
This icon indicates that the link is to a<br />
cascading stylesheet.<br />
This arrow indicates the number of<br />
times the file in focus (index.html)<br />
links to the file to which it points.<br />
This icon indicates that the link is to a<br />
graphic. Links to graphics are<br />
sometimes referred to as embedded<br />
links because they are rendered as<br />
part of the same HTTP request<br />
(appear on the same page).<br />
This arrow indicates that the validity of<br />
the link cannot be verified.<br />
This icon indicates that the link is to a<br />
mailing address.<br />
Links to file types that are not<br />
recognized are represented by this<br />
icon.<br />
Colors view<br />
The Colors view allows you to select colors for background or text from a color<br />
palette. To assign a color to text, highlight the text, select the color in the palette,<br />
and select Set as Text Color from the drop-down list. The background color for a<br />
table (or cell or row) or for the page can be selected in the same manner by<br />
placing the cursor in the appropriate position.<br />
Chapter 5. Working with HTML 83
Colors view<br />
Figure 5-5 Setting colors using the Colors view<br />
Tasks view<br />
The Tasks view contains a list of two types of elements:<br />
Problems Problems are tool-determined issues that have to be resolved.<br />
Example problems are Java compile errors, syntax errors, or<br />
broken links for HTML/JSP files. They are automatically added to<br />
the Task view when working with the tool. When you double-click<br />
a problem, the editor for the file containing the problem opens<br />
and the cursor is pointed at the location of the problem.<br />
Tasks You can manually add tasks yourself. For example, you can add<br />
a task that reminds you that you have to implement a Java<br />
method. Place the cursor in the method’s implementation,<br />
right-click, and select Add -> Task. When you double-click the<br />
task, the file opens and the cursor is located in the method. You<br />
can also add general tasks that do not refer to a specific file.<br />
84 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
You can set up filters to show only the tasks you really want to see by using the<br />
filter icon ( ).<br />
In Figure 5-1 on page 78, the filter has been set to on in this case to limit the<br />
items seen to the current file. You can see that one item is in the Tasks view,<br />
indicating a problem in the code. Double-clicking the task will bring the line where<br />
the error is into focus in the editor. A corresponding icon appears in the editor<br />
where the problem is. In this case, it is a broken link. Once the problem is<br />
corrected, the entry in the Tasks view will disappear.<br />
Quick Edit view<br />
The Quick Edit view lets you add short scripts to your HTML and JSP files. The<br />
Quick Edit view opens when you select a tag while editing an HTML or JSP file in<br />
Page Designer. For example, if you select a button tag on a JSP page, you can<br />
then associate a click event with that button and add a script to it.<br />
The left pane displays a list of possible events associated with the selected tag.<br />
The right pane is a script editor. After selecting an event in the left pane, you can<br />
add a script for that event in one of the following ways:<br />
► Enter the script directly.<br />
► Drag and drop a snippet from the Snippets view.<br />
► Insert simple actions by selecting from a list.<br />
The icons on the toolbar allow you to perform the following actions:<br />
► Select a script language, for example Java or JavaScript.<br />
► Apply the script to the current HTML or JSP file.<br />
► Reset the script currently in the Quick Edit view back to the original document<br />
contents.<br />
► Use the drop-down menu to perform additional actions:<br />
– Filter the list of events in the events list.<br />
– Insert or edit the script for a simple action by selecting from a list. In some<br />
cases, a dialog box opens so you can enter variables related to the simple<br />
action.<br />
As you add or change scripts in the Quick Edit view, the HTML or JSP file is<br />
updated if you select another tag, select another event for scripting, or click the<br />
Apply Script button on the toolbar.<br />
Besides scripting events, you can use Quick Edit to modify SCRIPT, jsp:scriptlet,<br />
jsp:expression, and jsp:declaration scripts.<br />
Chapter 5. Working with HTML 85
Palette view<br />
The Web tools Palette view lets you quickly drag and drop items onto a file you<br />
are editing. You can use this view when you are editing JSP or HTML files in<br />
Page Designer.<br />
The Palette view contains a series of drawers that you can open. Each drawer<br />
contains related items that you can drag and drop into the active editor. For<br />
example, if you are editing an HTML page in Page Designer, you can open the<br />
HTML drawer and drag and drop an image into the page. A window will open to<br />
let you select an image from the file system to add. The drawers and their<br />
contents vary depending on the active editor.<br />
Figure 5-6 Palette view<br />
Palette view<br />
86 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
You can customize the Palette view. For example, you can add additional items to<br />
the HTML drawer (right-click within the Palette view, choose Customize, and then<br />
select the additional HTML items to add). Or you can increase the size of the<br />
icons (right-click within the palette and choose Use Large Icons).<br />
Snippets view<br />
The Snippets view allows you to catalog and organize reusable programming<br />
objects, such as HTML tagging, JavaScript, and JSP code, along with files and<br />
custom JSP tags. The view can be extended based on additional objects that you<br />
define and include.<br />
Figure 5-7 Snippets view<br />
Snippets view<br />
To view or collapse the objects in a specific category, or drawer, click the<br />
category name.<br />
The Snippets view has the following features:<br />
► Drag-and-drop to Page Designer's Design page and various source editing<br />
pages: you can drag items from the view into the active editor and the text will<br />
be dropped into the document at the cursor location<br />
Chapter 5. Working with HTML 87
► Double-Click Support: you can double-click an item and have it inserted at the<br />
current cursor position in the active editor<br />
► User-defined categories and items: you can define, edit, and remove items<br />
from view categories as desired.<br />
► Plugin-defined categories and items: plug-in developers can contribute a<br />
default list of items to their own categories.<br />
► Variables in insertions: by default, items will be edited using a dialog and,<br />
when inserted, you will be prompted for values and attributes for each of the<br />
variables.<br />
► Category filtering: you can select which categories are shown in the Snippets<br />
view.<br />
► Custom insertion: plug-in developers can customize the behavior of items so<br />
that when they are dropped during a drag-and-drop action, both the text that<br />
is inserted and the insertion location are strictly defined.<br />
► Category organization: all categories and items within them are displayed<br />
alphabetically by default.<br />
Outline view<br />
The Outline view gives you an overview of the key elements that make up the<br />
resource that is being edited. It allows quick and easy navigation through your<br />
resource. By selecting one of the elements in the Outline view, the line in the<br />
editor view that contains the selected element is highlighted.<br />
88 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-8 Outline view<br />
Outline view<br />
<strong>Server</strong>s view and Console view<br />
The <strong>Server</strong>s view (similar to the one shown below) allows you to manage<br />
application servers and configurations used for testing applications. This view<br />
displays a list of the defined applications servers and their state. You can use this<br />
view to create and delete servers and to manage them (start, stop, etc.).<br />
Chapter 5. Working with HTML 89
Figure 5-9 <strong>Server</strong>s view<br />
When a server is running, the Console view shows server messages.<br />
Testing and deploying applications is discussed further in Chapter 13, “Deploying<br />
applications” on page 455.<br />
5.1.2 Editing with the Page Designer<br />
<strong>Server</strong>s view<br />
The Page Designer provides a visual-based environment that enables you to<br />
create and work with a file while viewing its elements on the page. When you<br />
open HTML or JSP files, the Page Designer is the default editor. The file will open<br />
in the editor area where you will have three views to work with: Design, Source,<br />
and Preview. You can alternate the way in which you see the file by moving<br />
among these views.<br />
For example, you can use the Design view to position graphics in the page, then<br />
switch to the Preview view to see how it will look from a Web browser. The<br />
Source view can be used to view the raw source code for the file, but not the<br />
screen presentation. The Page Designer provides full visual editing capabilities,<br />
including the ability to drag and drop from the Project Navigator view, the<br />
Thumbnail view, and Microsoft Internet Explorer.<br />
90 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Design view<br />
The Design view is the WYSIWYG environment that enables you to create and<br />
work with a file while viewing its elements on the page. For example, you can see<br />
the graphics that you have inserted into the file and continually check the visual<br />
presentation of the Web page as you design it. This is in contrast to the Source<br />
page, which shows you the HTML or JSP source code for the file, but not the<br />
screen presentation. The Design page provides full visual editing capabilities,<br />
including the ability to drag and drop from the Project Navigator view, the<br />
Thumbnails view, and Microsoft Internet Explorer.<br />
Figure 5-10 Design view<br />
Source view<br />
The Source view enables you to view and work with a file's source code directly.<br />
You can see the Source view in Figure 5-1 on page 78. The Outline and<br />
Attributes views both have features that supplement the Source view.<br />
Chapter 5. Working with HTML 91
Tip: When you place the cursor within a tag in the Source view, a bar appears<br />
to the left that encompasses the entire tag. For example, in Figure 5-1 on<br />
page 78 the cursor is after the tag. The bar on the left spans all the<br />
lines of code between the and tags. This is especially<br />
useful in visually locating the beginning and ending tags for nested lists,<br />
tables, etc.<br />
Preview view<br />
The Preview shows you how the current page is likely to look when viewed in an<br />
external Web browser. This view is only useful for viewing static content HTML.<br />
There is no runtime capability so dynamic content (such as JSP tags) will not be<br />
shown. To view JSP dynamic content, you will need to use the Run on <strong>Server</strong><br />
option (<strong>WebSphere</strong> test environment) from the page's context menu in the<br />
Project Navigator view.<br />
Tip: You can also use the Tools -> Launch External Web Browser menu<br />
option to open the current file in an external Web browser.<br />
Syntax validation<br />
The HTML Syntax Validator included in Studio Site Developer validates HTML<br />
basic syntax and HTML DTD compliance for HTML and JSP files created in Page<br />
Designer. You can turn it on or off and configure an option on the preferences<br />
page (accessed by clicking Window -> Preferences -> Web and XML Files -><br />
HTML -> HTML Annotations) to also validate your code as your type.<br />
Syntax validators are available for checking basic syntax as you work with files.<br />
Before getting started, it is a good idea to check the preferences to make sure<br />
that the appropriate validators are active. For example, the HTML syntax<br />
validator is not turned on by default.<br />
To enable or disable the validators or to change the default validation options,<br />
select Windows -> Preferences -> Validation.<br />
92 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-11 Validators<br />
Validation errors are shown in the Task view.<br />
5.1.3 Building applications with Web Site Designer<br />
A new feature of Studio Site Developer V5.1, called the Web Site Designer, has<br />
been provided to simplify and speed up the creation of HTML and JSP pages in a<br />
Web site. You can view the Web site in a Navigation view to add new pages,<br />
delete pages and move pages in the site. The Web Site Designer is especially<br />
suited for building pages that use a page template.<br />
The Web Site Designer is used to create the structure for your application in<br />
much the same way you would create a book outline to serve as the basis for<br />
writing a book. You use the Web Site Designer to visually lay out the flow of the<br />
application, rearranging the elements (JSPs, HTML pages) until it fits your<br />
needs. Then you continue by creating pages based on this design.<br />
Chapter 5. Working with HTML 93
Important: Using Web Site Designer is not required for developing<br />
applications in Studio Site Developer. The HTML/XHMTL wizard can also be<br />
used to create Web pages (see 5.1.4, “HTML/XHTML wizard” on page 108).<br />
The advantage of using Web Site Designer is in the layout of your application.<br />
It may become difficult to remember every page and every link in your<br />
application using traditional methods. Web Site Designer, on the other hand,<br />
provides you with a high-level picture of your application.<br />
A typical application development scenario using the Web Site Designer might go<br />
through the following steps:<br />
1. Create a Web project. Select a default page template to use for the Web<br />
pages. For information about page templates, see 5.1.5, “Using Page<br />
templates” on page 109. As you create Web pages, the default template will<br />
be used.<br />
2. Open the Web Site Configuration file. You will find this in the root directory of<br />
the project. It is automatically created when you create the Web project. This<br />
file is actually an XML file called .website-config that will contain Web site<br />
design information as you build your Web site using the designer.<br />
3. Begin designing your application by adding pages to the configuration. At this<br />
stage, you are simply adding elements to the design that represent JSP and<br />
HTML pages, and defining their relation to each other. For example, you could<br />
start by creating a top page called index.html.<br />
4. Add additional pages and place them in the design so that the application flow<br />
is illustrated. For example, if index.html will have four menu options, you<br />
should select the index.html box and add four new child pages (one per<br />
option) to the flow.<br />
5. Continue to visually lay out the application flow by creating design elements<br />
that represent each HTML and JSP page in the application. You can move<br />
elements around the diagram as you go to change the application flow.<br />
6. When you are done, create a real page for each design element (you could<br />
also create the Web pages as you go along).<br />
As you build your Web site design, the information is stored in the .website-config<br />
file so that navigation links and site maps can be generated automatically. This<br />
means that when the structure of a site changes, for example, when a new page<br />
is added, the navigation links are automatically regenerated to reflect the new<br />
Web site structure.<br />
94 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
This dynamic navigation is accomplished using special comment tags for the<br />
navigation bar and site map. These comment tags use the site structure<br />
information and other site-related information that Web Site Designer stores in an<br />
XML file called .website-config. When you create a Web project, Web Site<br />
Designer support is a default feature of the project. The Web project contains a<br />
placeholder for the website-config file named Web Site Configuration.<br />
Opening the Web Site Configuration file<br />
Double-clicking Web Site Configuration launches Web Site Designer and<br />
opens .website-config file. Using the Web Site Designer editor, you can add,<br />
delete, and rearrange the Web pages that compose the Web site. There are two<br />
views in the editor: the Navigation view and the Detail view. The Navigation view<br />
shows the structure of the Web site and the Detail view shows a list of all the<br />
Web pages used in the site structure.<br />
Figure 5-12 Web site diagram for Online Catalog sample<br />
Adding and editing pages<br />
Each page can be created and opened for editing from the Web site<br />
configuration by double-clicking the page icon from the Web Site Designer.<br />
Chapter 5. Working with HTML 95
Important: If a Web page icon has been added to the Web Site Designer (File<br />
-> Add New Page), but the page has not been created, you will be asked to<br />
create the page in the Create a Page dialog. You can choose to create an<br />
HTML or JSP page. Depending on what option is selected, the appropriate<br />
wizard will be displayed.<br />
When opened for editing, the default editor for the page is used. In this case of<br />
HTML and JSP pages, the default editor is the Page Designer.<br />
Using page templates<br />
Using page templates improves the efficiency of developing Web applications.<br />
You can alter an existing page template or create your own and then apply the<br />
page template to all of the Web pages in your Web site to ensure a consistent<br />
design. When editing the page template, you can use the free layout mode to<br />
make changes to the layout of each Web page. Instead of making a change<br />
(such as altering the size of the navigation bar) on each individual Web page, you<br />
can alter the page template instead. Then, you can apply that change to your<br />
entire Web site.<br />
Note: See 5.2, “Adding HTML pages to the Online Catalog sample” on<br />
page 135 for an example of using the Web Site Designer.<br />
Using the Site Parts drawer<br />
When working with pages, the Site Parts drawer in the Palette view is particularly<br />
useful. It contains Web site elements, such as different navigation bars and a site<br />
map that you can drag and drop into your Web page.<br />
96 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-13 Site Parts drawer<br />
Using the Context menu<br />
Depending on what area or element is right-clicked within the Web Site Designer,<br />
a different context menu is displayed. For the purpose of this discussion, we are<br />
going to categorize the areas in the Web Site Designer as:<br />
1. Editor surface - The surface of the Web Site Designer where you add, delete,<br />
and modify page icons.<br />
2. Unassociated page icon - A page icon that does not have a physical file<br />
(HTML or JSP) associated to it.<br />
3. Associated page icon - A page icon that has a physical file associated to it.<br />
The table below lists (and describes) all the items of the context menu and<br />
groups them into the appropriate category.<br />
Table 5-2 Context menu items<br />
Item Sub Item Category Description<br />
Open 3 Opens the<br />
associated page in<br />
its default editor.<br />
Open With 3 Allows you to open<br />
the associated<br />
page in the default<br />
editor or a different<br />
editor.<br />
Chapter 5. Working with HTML 97
Item Sub Item Category Description<br />
Create Page 2 Allows you to<br />
create an HTML or<br />
JSP page.<br />
Depending on what<br />
option is selected<br />
the appropriate<br />
wizard is invoked.<br />
Save 1, 2, 3 Saves any changes<br />
made in the Web<br />
Site Designer<br />
editor.<br />
Cut 2, 3 Removes the page<br />
icon from the<br />
diagram.<br />
Add New Page As Top 1 Adds a new page<br />
icon to the diagram<br />
and specifies it as a<br />
starting page.<br />
Add Existing<br />
Pages...<br />
98 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Before 2, 3 Adds a new page<br />
icon to the diagram<br />
and places it before<br />
the selected page<br />
icon.<br />
After 2, 3 Adds a new page<br />
icon to the diagram<br />
and places it after<br />
the selected page<br />
icon.<br />
As Child 2, 3 Adds a new page to<br />
the Web diagram<br />
and sets it as a<br />
child page of the<br />
selected page icon.<br />
1, 2, 3 Allows you to add<br />
existing pages from<br />
the project to the<br />
diagram.
Item Sub Item Category Description<br />
Add New Project Before 2, 3 Allows you to add a<br />
project to the<br />
diagram before the<br />
selected page icon.<br />
Add Existing<br />
Project<br />
After 2, 3 Allows you to add a<br />
project to the<br />
diagram after the<br />
selected page icon.<br />
As Child 2, 3 Allows you to add a<br />
project as a child of<br />
the selected page<br />
icon.<br />
Before 2, 3 Allows you to add<br />
an existing project<br />
to the diagram<br />
before the selected<br />
page icon.<br />
After 2, 3 Allows you to add<br />
an existing project<br />
to the diagram after<br />
the selected page<br />
icon.<br />
As Child 2, 3 Allows you to add<br />
an existing project<br />
as a child of the<br />
selected page icon.<br />
Delete 2, 3 Removes the page<br />
icon from the<br />
diagram but also<br />
prompts you to<br />
delete the<br />
associated page<br />
from the project.<br />
Move... 3 Allows you to move<br />
the location of the<br />
associated page.<br />
Rename... 2, 3 Allows you to<br />
change the file<br />
name of the<br />
associated page.<br />
Chapter 5. Working with HTML 99
Item Sub Item Category Description<br />
Edit Navigation<br />
Label...<br />
Navigation Navigation<br />
Candidate<br />
Set Navigation<br />
Root<br />
Site Map Site Map<br />
Candidate<br />
100 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
2, 3 Allows you to<br />
change the<br />
navigation label of<br />
the page icon.<br />
2, 3 Allows you to<br />
enable or disable<br />
the page icon as a<br />
navigation<br />
candidate. Enabled<br />
page icons are<br />
indicated with a<br />
checkmark beside<br />
this item.<br />
2, 3 Allows you to<br />
enable or disable<br />
the page icon as a<br />
navigation root.<br />
Enabled page<br />
icons are indicated<br />
with a checkmark<br />
beside this item.<br />
2, 3 Allows you to<br />
enable or disable<br />
the page icon as a<br />
site map candidate.<br />
Enabled page<br />
icons are indicated<br />
with a checkmark<br />
beside this item.<br />
Page Template Apply Template 2, 3 Allows you to apply<br />
a template to the<br />
page icon. A wizard<br />
is invoked when<br />
this option is<br />
selected.<br />
**Open Template<br />
With<br />
3 Allows you to open<br />
the applied<br />
template in an<br />
editor or your<br />
choice.
Item Sub Item Category Description<br />
**Replace<br />
Template...<br />
2, 3 Allows you to<br />
replace the existing<br />
template with<br />
another one of your<br />
choice.<br />
**Detach Template 2, 3 Allows you to<br />
detach the<br />
currently applied<br />
template from the<br />
page icon.<br />
Style Add CSS Link 3 Allows you to add a<br />
CSS link to the<br />
page.<br />
Edit CSS 3 Allows you to edit a<br />
CSS that is linked<br />
to the page.<br />
Remove CSS Link 3 Allows you to<br />
remove a CSS link<br />
from the page.<br />
Run on <strong>Server</strong>... 3 Allows you to run<br />
the selected page<br />
on a test<br />
application server.<br />
Display As Top 2, 3 Displays the<br />
selected page icon<br />
as the top item. You<br />
can double-click<br />
the yellow arrow to<br />
return to the<br />
previous view.<br />
Appearance Show Navigation<br />
Title<br />
1, 2, 3 Displays the<br />
navigation label in<br />
the page icon.<br />
Show File Name 1, 2, 3 Displays the<br />
associated page<br />
name in the page<br />
icon.<br />
Show Page<br />
Template<br />
1, 2, 3 Displays the<br />
template name in<br />
the page icon.<br />
Chapter 5. Working with HTML 101
Item Sub Item Category Description<br />
** - These items are only available if a template has already been applied to a page.<br />
Understanding the icons<br />
After you have added pages (associated or not) to the Web Site Designer, an<br />
icon is added to the editor surface representing each page. Depending on the<br />
options selected for the page and the type of page created, the icons will appear<br />
differently. Each icon indicates information about the page.<br />
Figure 5-14 Page icon<br />
Show Number of<br />
Children<br />
Change Layout<br />
Orientation<br />
102 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
1, 2, 3 When the parent<br />
page icons are<br />
compressed in the<br />
diagram, a number<br />
is displayed on the<br />
icon indicating the<br />
number of<br />
associated child<br />
pages.<br />
1, 2, 3 Changes the layout<br />
of the diagram to<br />
vertical or<br />
horizontal.<br />
Set Hanging Style 2, 3 Changes the view<br />
of the diagram to a<br />
hanging display.<br />
Navigation candidate icon Navigation root icon<br />
Icon border<br />
Sitemap candidate icon Navigation label
Navigation candidate<br />
If the Navigation candidate icon is enabled, the Navigation label of the icon will<br />
appear in the site navigation of the application. This function is enabled by<br />
default. It can be disabled by right-clicking the page icon and selecting<br />
Navigation -> Navigation Candidate from the context menu. Setting it as the<br />
candidate again is done in the same way.<br />
Note: The icons become gray in color if the function associated with the icon<br />
is not enabled. For example, in Figure 5-14 on page 102, the Navigation root<br />
icon is grayed out because this page icon is not set as a Navigation root.<br />
Navigation root<br />
Enabling the Navigation root function sets the associated page as a navigation<br />
root for the site. Traditionally, the index.html page of a site is set as the navigation<br />
root. By default, this function is not enabled; to enable (or disable) it, right-click<br />
the page icon and select Navigation -> Set Navigation Root from the context<br />
menu.<br />
Figure 5-15 Navigation root enabled<br />
Site map candidate<br />
A feature of Web Site Designer allows you to create a site map for your<br />
application. By default, every page icon is enabled as a site map candidate. If you<br />
do not wish to set a page as a candidate, right-click the icon and select Site Map<br />
-> Site Map Candidate from the context menu. Setting the candidate again is<br />
done in the same way.<br />
Navigation label<br />
The navigation label of the page icon is the text that will appear in the site<br />
navigation menu. Therefore, the label should be simple and descriptive of the<br />
page being linked to, for example, Home or View Catalog.<br />
Icon border<br />
If there is no page associated with an icon, the icon border is dashed (as in<br />
Figure 5-14 on page 102). Once a page is created or associated to the icon, the<br />
border becomes solid. In addition to the border being changed, a fourth icon will<br />
be added to the page icon: the Code icon. If the icon is a less than and greater<br />
than sign icon, it means that the associated page is an HTML page. If the icon is<br />
a blue diamond, then the associated page is a JSP.<br />
Chapter 5. Working with HTML 103
Figure 5-16 Associated page icon<br />
Page templates<br />
If a page template has been applied to a page, the top part of the icon is blue.<br />
► To add a template to a page, right-click the page icon, select<br />
Page Template -> Apply Template... from the context menu, and then follow<br />
the wizard instructions.<br />
Figure 5-17 Template applied to page<br />
Code icons<br />
Icon border<br />
► To remove the applied template, right-click the page icon and select Page<br />
Template -> Detach Template from the context menu.<br />
► When a template is applied to the page, you can also open the template and<br />
replace the template. To open the template, right-click the icon and select<br />
Page Template -> Open Template With -> Page Designer for Template<br />
from the context menu.<br />
► To replace the template, right-click the page icon, select Page Template -><br />
Replace Template... from the context menu, and then follow the wizard<br />
instructions.<br />
Inserting a navigation bar<br />
You can insert a navigation bar into a Web page by inserting a navigation object<br />
from the Palette view.<br />
104 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: If you use a page template to govern the layout and visual design of all<br />
the pages in a Web site, you can insert a navigation bar onto the page<br />
template, rather than adding the navigation to every page individually. The<br />
links in the navigation bar are then updated dynamically for each individual<br />
page in the site. For more information on creating a page template, see<br />
“Creating a page template” on page 111.<br />
To insert a navigation bar into a Web page:<br />
1. Double-click a page icon in Web Site Designer to open the Design page in<br />
Page Designer.<br />
2. Select the Site Parts drawer in the Palette view. You have the following<br />
navigation bar options:<br />
– Horizontal Navigation Bar<br />
– Horizontal Graphical Navigation Bar<br />
– Vertical Navigation Bar<br />
– Vertical Graphical Navigation Bar<br />
– Navigation Drop Down<br />
3. Choose the style of navigation you want to insert and drag and drop the<br />
palette object onto the page. Depending on which navigation bar you choose,<br />
one of several insert dialogs opens.<br />
4. Select whether you want to use a Sample or a User-Defined navigation bar. If<br />
you want to use a sample navigation bar, select one of the Thumbnail images<br />
and the File name field will be automatically populated. If you have a<br />
user-defined navigation bar, you can click Browse to locate the file in the<br />
current project or import the file from the file system.<br />
5. Select the type of links that you want to appear in the navigation bar. You can<br />
select links based on page relationships. For example, you can select links<br />
based on parent-child relationships or you can select links based on<br />
sequence (previous and next pages). If you select previous or next links, you<br />
can supply a label to appear for those links, such as Back and Forward.<br />
Click OK. The navigation bar is inserted on the page.<br />
Chapter 5. Working with HTML 105
Inserting a navigation trail<br />
You can insert a navigation trail, sometimes referred to as breadcrumbs, into a<br />
Web page by inserting the object from the Palette view.<br />
Note: If you use a page template to govern the layout and visual design of all<br />
the pages in a Web site, you can insert a navigation trail onto the page<br />
template, rather than adding the navigation to every page individually. The<br />
links in the navigation trail are then updated dynamically for each individual<br />
page in the site.<br />
To insert a navigation trail into a Web page:<br />
1. Double-click a page icon in Web Site Designer to open the Design page in<br />
Page Designer.<br />
2. Select the Site Parts drawer in the Palette view and drag and drop the<br />
Navigation Trail object onto the page; an insert dialog opens.<br />
3. Select whether you want to use a Sample or a User-Defined navigation trail. If<br />
you want to use a sample navigation trail, select one of the Thumbnail images<br />
and the File name field is populated. If you have a user-defined navigation<br />
trail, you can click Browse to locate the file in the in the Current project or<br />
Import the file from the file system.<br />
4. Choose the Separator character, the character that appears between each<br />
link in the trail.<br />
5. Choose the Start character and the End character, the characters that<br />
appear at the beginning and the end of the trail.<br />
6. Click OK; the navigation trail is inserted on the page.<br />
Inserting a site map<br />
You can insert a site map into a Web page by inserting the object from the<br />
Palette view. Typically, each Web site has one page that contains a map, or<br />
organized collection of links, of the whole site.<br />
To insert a site map into a Web page:<br />
1. Double-click a page icon in Web Site Designer to open the Design page in<br />
Page Designer.<br />
2. Select the Site Parts drawer in the Palette view and drag and drop the Site<br />
Map object onto the page; an insert dialog opens.<br />
3. Select whether you want to use a Sample or a User-Defined site map. If you<br />
want to use a sample site map, select one of the Thumbnail images and the<br />
File name is populated. If you have a user-defined site map, you can click<br />
106 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Browse to locate the file in the in the current project or import the file from the<br />
file system.<br />
4. Choose the start level and the end level, the level of the hierarchy of the site<br />
structure included in the site map. For example, if you have six levels of pages<br />
in your site, 1 being the top page; you can choose to only include levels 1-3 in<br />
your site map (though any limit is allowed). This is useful if the pages below<br />
level 3 are very detailed, specific pages and you want the site map to only<br />
include links to broader, overview pages.<br />
5. Click OK; the site map is inserted on the page.<br />
Modifying a site part specification<br />
Web Site Designer generates site parts, such as navigation bars and site maps,<br />
from the site structure and appearance definition file, or the specification page.<br />
The specification page is an HTML file, named spec.html, that contains special<br />
comment tags and expressions. A specification page can be specified as an<br />
attribute of siteedit:navbar, siteedit:navtrail, siteedit:navtab and siteedit:sitemap<br />
tags, which are the tags inserted in your Web pages when you add site parts.<br />
You can modify the appearance of site parts by editing the associated<br />
specification page:<br />
1. In a Web page open in Page Designer, select a site part tag, such as<br />
siteedit:navbar.<br />
2. In the Attribute view, click Edit. The specification page opens.<br />
3. Edit the specification page as you would edit any other HTML file.<br />
Note: You must enter tags and expressions in the Source page of Page<br />
Designer.<br />
4. Save the specification page when you are finished.<br />
Example 5-1 on page 108 shows an example of a spec.html.<br />
Chapter 5. Working with HTML 107
Example 5-1 spec.html<br />
<br />
[<br />
< !-- siteedit:forEach var="item" items="${sitenav.items}" varStatuc="status"<br />
--><br />
< !-- siteedit:choose --><br />
< !-- siteedit:when test="${item.self}" --><br />
${item.label}<br />
< !-- /siteedit:when --><br />
< !-- /siteedit:otherwise --><br />
< !-- /siteedit:choose --><br />
< !-- siteedit:if test="${!status.last}" -->|< !-- /siteedit:if --><br />
< !-- /siteedit:forEach --><br />
]<br />
<br />
5.1.4 HTML/XHTML wizard<br />
If you do not want to use the Web Site Designer, you can use the HTML/XHTML<br />
wizard to add pages to your project.<br />
Follow these steps to create a new HTML or XHTML file:<br />
1. Select File -> New -> HTML/XHTML File to launch the wizard.<br />
2. Click Browse to select the appropriate location for the file. The folder that you<br />
choose should be under the WebContent folder of the Web project. If an<br />
HTML file that is included in a dynamic Web project is not stored under this<br />
folder, then it will not be included in the WAR file that is deployed to the server.<br />
In addition, link validation will not encompass files that are not under the<br />
WebContent folder.<br />
3. Type a name for your new file.<br />
4. Ensure that the appropriate HTML or XHTML option is displayed in the<br />
Markup Language drop-down list.<br />
5. You have three options for proceeding:<br />
a. If you want to accept the defaults associated with a new HTML or XHTML<br />
file, leave the Model field as None and make sure the Configure advanced<br />
options is deselected.<br />
b. If you want to apply a page template to your new file, select Page<br />
Template in the Model field and click Next.<br />
i. If you want to use one of the sample templates provided, select<br />
Sample Page Template and then choose one of the templates shown<br />
in the Thumbnail box.<br />
108 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
ii. If you want to use a template of your own, select User-defined Page<br />
Template and then click Browse to select the template from the file<br />
system.<br />
c. If you do not want to use a page template, but want to specify or customize<br />
the file options, select the Configure advanced options check box and<br />
click Next.<br />
i. If you want to select an encoding type, deselect the Use workbench<br />
encoding check box to select a new encoding attribute. Select the<br />
appropriate encoding value to add to the file's HTML declaration from<br />
the Encoding drop-down list.<br />
ii. The default is the value set in the HTML Files preferences page, which<br />
is accessed by selecting Window -> Preferences, and then expanding<br />
the Web and XML Files preferences.<br />
iii. Ensure that the proper content type is selected in the Content Type<br />
drop-down list. The default is text/html.<br />
iv. Select the Document Type that you wish to associate with the HTML or<br />
XHTML file. The default for an HTML file is HTML 4.01 Transitional,<br />
while the default for an XHTML file is XHTML 1.1.<br />
v. Specify a cascading style sheet (CSS) file to be referenced by the new<br />
HTML or XHTML file. Typically, CSS files are located in the theme<br />
folder under the WebContent folder. You can click Add to choose a<br />
style sheet from the file system. Choose Remove to delete a style<br />
sheet from the list, or use the arrow buttons to rearrange the order in<br />
which the file references the style sheets. If a style sheet is already<br />
associated with the project in which you are creating the new file, that<br />
style sheet is the default.<br />
6. Click Finish to create the file in the project that you have selected. As a<br />
default, the new file opens in Page Designer, in the Design page.<br />
5.1.5 Using Page templates<br />
Page templates provide a starting point for JSP and HTML pages. By selecting a<br />
template to use throughout the application, you ensure a consistent look and feel<br />
for the application. Using templates also makes maintenance of this look easy. A<br />
change to the template automatically updates all pages using that template.<br />
Studio Site Developer provides a page template library populated with a<br />
commonly used templates. You can use these as they are, modify them, or<br />
create your own templates. The Web page wizards, Page Designer, and Web<br />
Site Designer tools are especially designed to make using templates easy.<br />
Chapter 5. Working with HTML 109
An example of a page template you will find in the library is shown in Figure 5-18<br />
on page 110.<br />
Figure 5-18 Page template<br />
Page templates can be applied to a Web page in one of the following ways:<br />
► By specifying the template when you use a wizard to create the page. This is<br />
true regardless of whether you are using the wizard from a navigation view, a<br />
tool bar or the Web Site Designer.<br />
► By using the Web Site Designer. You can apply a template as you create<br />
pages or to existing pages as you add them to the Web Site Configuration.<br />
You can also apply or replace templates to pages already in the configuration.<br />
► By using the Page Designer. With the page open, select Page -> Page<br />
Template. You can apply, replace, or detach the template. You also have the<br />
option of opening the template for modification.<br />
A default page template can be specified when you create a Web project. If you<br />
specify a default template, it will be automatically selected when are given the<br />
option in wizards to select a template for a page.<br />
110 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Page templates versus style sheets<br />
Though style sheets have not been discussed as of yet (see 5.1.9, “Working with<br />
style sheets” on page 120), there may be some confusion about page templates<br />
and style sheets. Page templates are used if you wish to create a standard layout<br />
for the JSP and HTML pages in your application. For example, you may want<br />
each page in your application to have a header, a navigation menu on the left<br />
side of the page, and a footer. All of these elements can be created in a page<br />
template and then used by the pages in your application; this obviously will aid in<br />
the maintenance of your application as changes only need to be made in one<br />
area. Style sheets, on the other hand, are used by page templates (or JSP and<br />
HTML pages) to set fonts, colors, table formatting, etc. Again, like page<br />
templates, maintenance is done in one area, which will save time.<br />
A page template can act as a style sheet if you set your styles within the page<br />
template. Since the template is used by every page in your site, any settings in<br />
the page template will be reflected in the corresponding pages. That said, this is<br />
not the recommended development scenario. It is best to keep the page template<br />
and style sheet separate.<br />
Creating a page template<br />
To create a page template that you can use in Page Designer, follow these steps:<br />
1. Create a new dynamic Web project:<br />
a. Choose File -> New -> Project.<br />
b. Select Web -> Dynamic Web Project and click Next.<br />
c. Enter a Project name and click Finish.<br />
2. Create a JSP, an HTML, or an XHTML file. If you are creating a JSP file, follow<br />
these steps:<br />
a. Select the newly created project in the Project Navigator.<br />
b. Choose File -> New -> JSP File. The New JSP File wizard appears.<br />
c. Fill in the Folder and the File Name fields.<br />
d. Select HTML as the Markup language and None as the Model.<br />
e. Click Finish. The new page opens in Page Designer.<br />
3. If you are creating an HTML or XHML file instead of a JSP file, follow these<br />
steps:<br />
a. Select the newly created project in the Project Navigator.<br />
b. Choose File -> New -> HTML/XHTML File. The New HTML File wizard<br />
appears.<br />
c. Fill in the Folder and the File Name fields.<br />
Chapter 5. Working with HTML 111
d. Select HTML or XHTML as the Markup language and None as the Model.<br />
e. Click Finish. The new page is opened in Page Designer.<br />
4. Right-click the mouse in Page Designer to add content to the page:<br />
a. Enter text directly.<br />
b. Drag and drop items from the palette (Window -> Show View -> Other -><br />
Web -> Palette).<br />
c. Choose Insert -> Page Template -> Content Area. The content area is<br />
very important to users because it is the only area in which they can insert<br />
or add information. They cannot edit the rest of the page created from the<br />
page template.<br />
d. Choose Insert -> Page Template -> Page Fragment. Inserting a page<br />
fragment lets you include part of a page from another file (this is similar to<br />
an SSI include or a JSP include). Changes in the page fragment are also<br />
applied immediately to all the pages created from the template.<br />
5. Choose File -> Save as Page Template. The Save as Page Template<br />
window opens and you can select the folder in which to save the template file.<br />
5.1.6 Working with framesets<br />
In our sample application, we no longer use framesets, but instead, use the page<br />
templates. However, framesets are still commonly used in Web applications to<br />
control the organization and flow of the Web pages. One common Web page<br />
design consists of a banner or title in a horizontal top frame, navigation links in a<br />
narrow left frame with content in a wider frame on the right. Studio Site Developer<br />
provides you with easy-to-use tools to create and work with framesets.<br />
As an example, let’s build an entry for a Web site using a frameset. We will create<br />
a parent frame called index.html. It will have the following frames:<br />
► A frame that spans the top called header.html. It will contain the company<br />
logo and links to company information.<br />
► A frame on the lower left called menu.html. It will contain menu options.<br />
► A frame on the lower right called main.html. It will contain the page displayed<br />
when the user selects an option.<br />
To build this frameset, you would do the following:<br />
1. Create a new HTML page in the Web Content directory called index.html<br />
(New -> HTML/XHTML file).<br />
2. Switch to the Design view and select Frame->Split Frame ->Split<br />
Horizontally in the menu bar.<br />
112 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3. The frameset parent file is the file that contains tagging which defines the<br />
frameset and calls other files into the frames. We want index.html to be the<br />
parent, so select In the frameset parent in the Split Frame dialog.<br />
Figure 5-19 Split frame<br />
Click OK.<br />
4. In the Design view, you will see a bar splitting the frame into two horizontal<br />
frames. Place the cursor in the bottom frame.<br />
5. On the workbench menu bar, click Frame -> Split Frame -> Split Vertically.<br />
A bar is displayed, splitting the bottom frame into two vertical frames. Drag the<br />
bars so they are positioned as shown in Figure 5-20 on page 114.<br />
Chapter 5. Working with HTML 113
header.html<br />
menu.html<br />
Figure 5-20 Working with framesets<br />
current file name<br />
main.html<br />
When you are in the Design view, the source code updated depends on which<br />
frame the cursor is in. You can see the current file name in the upper left<br />
corner of the editor area.<br />
6. On the workbench menu bar, click File -> Save All. You will have the<br />
opportunity to name each page of the frame. In this case:<br />
a. Save newpage1 as header.html.<br />
b. Save newpage2 as menu.html.<br />
c. Save newpage3 as main.html.<br />
As you are asked to save each page, the relevant frame will be identified with<br />
a dotted outline in the editor area. You may need to move the wizard window<br />
to the side in order to see which window you are naming.<br />
Figure 5-21 on page 115 shows the code generated in index.html.<br />
114 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
toggle between<br />
frameset and frame<br />
parent
Tip: To see the source for index.html, switch to the Source view. When you<br />
switch, you will initially see the source for the frame the cursor was in. There<br />
will be a drop-down box at the top of the editor pane that lets you select which<br />
of the files in the frameset you want to view.<br />
You can also switch to the frameset parent (index.html) in the Design view<br />
using the Show Frames toggle switch above the editor pane, but there is no<br />
visual indication of the frameset tags so you are limited as to what you can do.<br />
Figure 5-21 Viewing the frameset source<br />
Note that the frame attributes can be modified for each frame by placing the<br />
cursor within the appropriate tags.<br />
Chapter 5. Working with HTML 115
5.1.7 Adding tables, links, text, and images<br />
Studio Site Developer provides tools for adding text, tables, links, and images to<br />
your HTML or JSP pages.<br />
Working with text<br />
Working with text is simple. Place the cursor in the Source view where you want<br />
the text to go and start typing. Pressing the Enter key at the line of text will enter<br />
a break tag. To start a new paragraph, just move the cursor down.<br />
As you work with the text, you will find several useful toolbar options. For<br />
example, you can select text and use icons to make it bold, center it, enlarge it,<br />
change the font, or underline it.<br />
Working with tables<br />
Working with tables is easy when done from the Design view. Figure 5-22 shows<br />
the various tools available for creating tables. The Table drop-down has a variety<br />
of options that allow you to manipulate the table configuration. The Attributes<br />
view allows you to assign characteristics to tables and rows.<br />
Figure 5-22 Working with tables<br />
116 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Adding a table<br />
Position the cursor to the point where you want the table. Select Insert -> table.<br />
Enter the number of rows and columns, then click OK.<br />
Resizing a table<br />
You can resize the table by selecting the columns, rows, or the complete table<br />
and dragging to the new size. Otherwise, the table cells will be the size of<br />
whatever their content is.<br />
Table attributes<br />
Attributes for the table can be set using the Attributes view. The attributes listed<br />
in Table 5-3 can be set.<br />
Table 5-3 Table attribute options<br />
Table attributes Cell attributes Row attributes<br />
► Alignment<br />
► Text flow<br />
► Caption<br />
► Width and height<br />
► Cell spacing<br />
► Cell padding<br />
► Border width<br />
► Background color and<br />
image<br />
► Cell type (header or<br />
data)<br />
► Horizontal and vertical<br />
alignment<br />
► Background color<br />
► Width and height<br />
► Autowrap option<br />
► Background color and<br />
image<br />
► Horizontal and vertical<br />
alignment<br />
► Background color<br />
Adding a link<br />
Studio Site Developer provides the tools to easily add links to files or URLs using<br />
the Insert -> Link toolbar option. The types of links you can choose from are file,<br />
http, FTP, e-mail, or other.<br />
Tip: You can also drag and drop files into the page from the Project Navigator<br />
bar, the Thumbnail view, or even from Windows Explorer. When you do this, a<br />
window opens with options that determine how the file is included. In this<br />
window, you simply state that you want a link to the file inserted.<br />
If the file is from a directory outside of the project, the file will be copied into<br />
the project directly under the Web Content directory. You can move this to<br />
another directory by dragging it to the folder in the Navigator view. The links<br />
will be automatically updated to reflect the new location.<br />
Adding a text link<br />
Text links are inserted by selecting Insert -> Link from the toolbar. If you have<br />
not selected text in the Source view to represent the link, you can add it during<br />
the Insert Link wizard.<br />
Chapter 5. Working with HTML 117
Figure 5-23 Adding a link<br />
These values can be changed once the link has been added by using the<br />
Attributes view.<br />
Tip: In the previous frameset example, we assigned frame names with the<br />
Attributes view. If you are working with frames, you can enter the name of the<br />
frame as a target window for a link. Then, when adding additional links, you<br />
will have that frame as a selection too.<br />
Adding an image link<br />
To add a image file that acts as a link:<br />
1. Add the image file by clicking Insert -> Image file.<br />
2. While the image is still selected, select Insert -> Link.<br />
3. Select the type of link.<br />
4. Browse to the target of the link, select it, and click Open.<br />
5. Choose a target window (choose from this frame, parent frame, new window,<br />
full screen, or type in a frame name). Note that once you type in a frame name<br />
manually, that name is an option the next time you select a target window.<br />
6. Click OK.<br />
Adding images and image maps<br />
The Insert drop-down menu allows you to add images or background images to<br />
the page.<br />
118 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
To add an image to the body of a page, you can drag and drop it from another<br />
location (including from external files from Windows Explorer), or you can do the<br />
following:<br />
1. Place the cursor on the page in the location you want to put the image.<br />
2. Select Insert -> Image file -> From file (or from URL).<br />
3. Browse to the image, select it, and click Open.<br />
The Attributes view for an image allows you to change the layout of the image<br />
or to assign an existing image map.<br />
4. You can add and work with image maps by selecting the image and then<br />
clicking Edit -> Image -> Image Map.<br />
5.1.8 Working with forms, input fields, and buttons<br />
As with the other elements we have seen, Studio Site Developer provides tools,<br />
views, wizards, and other aids to make working with forms, input fields, and<br />
buttons easy. Forms are a familiar method for collecting data from users in a<br />
structured way. Form design in Page Designer is best supported in the Design<br />
page, where you can see the spatial and style-related attributes as you construct<br />
the form.<br />
Most activities related to creating and editing forms are available by clicking<br />
Insert -> Form and Input Fields. To create a form, place the cursor where you<br />
want to position the form and select Insert -> Form and Input Fields -> Form.<br />
After determining a layout scheme for your form elements, you can use the<br />
options in Insert -> Form and Input Fields to insert the following fields and<br />
controls:<br />
► Submit, Reset, Image, General, and Extended buttons<br />
► Radio button<br />
► Check box<br />
► List box<br />
► Drop-Down menu<br />
► Group box<br />
► Text area<br />
► Text field<br />
► File Selection field<br />
As you add form elements, the dialog for each object will open so that you can<br />
supply format, style, and content details.<br />
Chapter 5. Working with HTML 119
5.1.9 Working with style sheets<br />
Style sheets can be created when you create the Web project, or they can be<br />
added later. It is a good idea to decide on the overall theme (color, fonts, etc.) for<br />
your Web application in the beginning and create the style sheet at the start of<br />
the development effort. Then as you create the HTML and JSP files, you can<br />
select that style sheet to ensure that the look of the Web pages will be consistent.<br />
Style sheets are commonly kept in the Web Content/theme folder.<br />
Style sheets can be created when the Web project is created (see 4.3.2,<br />
“Creating a Web project” on page 66) or at any time using File -> New -> Other<br />
-> Web -> CSS File from the toolbar. To work with a style sheet, you open it as<br />
you would any other file. A special editor called the CSS Designer will be used to<br />
open the file.<br />
Figure 5-24 shows the default style sheet, called blue.css, that is added to Web<br />
projects when they are created. You will find it under the Web Content/theme<br />
folder.<br />
Figure 5-24 blue.css<br />
120 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Two panes will appear in the editor area. On the right, you see the style sheet<br />
source. On the left, you can see a preview of the effect that each style setting<br />
has. You can select an actual Web page to apply and display styles created by<br />
CSS Designer, or use the sample HTML file, which provides a minimal version of<br />
the defined styles. The Styles view at the lower left helps you locate and select<br />
the element you want to work with.<br />
Individual styles in a style sheet are typically defined as follows:<br />
selector { property : value; }<br />
Creating a new Cascading Style Sheet (CSS)<br />
1. From the Web perspective, select File -> New -> CSS File to launch the<br />
Create a CSS File wizard.<br />
2. Select the appropriate container for the file from the list of project folders (and<br />
subfolders). Typically, you should place a CSS file in the theme folder located<br />
in the WebContent folder. The folder that you choose should be under the<br />
WebContent folder of the Web project. If the new file is not under this folder,<br />
then it will not be included in the WAR file that is deployed to the server. In<br />
addition, link validation will not encompass files that are not under the<br />
WebContent folder.<br />
3. Type a file name into the appropriate field. The .css file type will be appended<br />
when the file is created.<br />
4. Click Finish to create and open the file in the editing area.<br />
5. Add entries to the file by right-clicking in the Source pane, selecting Add and<br />
then the tag type. A window will open that contains selections for the<br />
attributes of the tag.<br />
Creating and linking to a new Cascading Style Sheet (CSS)<br />
1. Open the Styles view from the Web perspective.<br />
2. Select New Link from the Select and Link to external style sheet tool bar<br />
button to launch the Create and Link to a CSS File wizard.<br />
3. Select or enter the appropriate container for the file from the list of project<br />
folders (and subfolders). Typically, you should place a CSS file in the theme<br />
folder located in the WebContent folder. The folder that you choose should be<br />
under the WebContent folder of the Web project. If a style sheet is not under<br />
this folder, then it will not be included in the WAR file that is deployed to the<br />
server. In addition, link validation will not encompass files that are not under<br />
the WebContent folder.<br />
4. Type a file name into the appropriate field. The .css file type will be appended<br />
when the file is created.<br />
Chapter 5. Working with HTML 121
5. Select the Link radio button from Insertion type. You can also select the<br />
Import radio button from Insertion type. This type is, however, not supported<br />
by all browsers. Therefore, it is recommended that you select the Link radio<br />
button unless there is good reason to do otherwise. The name of the selected<br />
style sheet file appears in the Styles view, and the settings in the style sheet<br />
file are applied to the page being edited.<br />
6. Click Finish to create and open the file in the editing area.<br />
Linking to an existing style sheet file<br />
By setting a link from your page to an existing style sheet file, you can apply the<br />
style in that file to your page.<br />
To set an external style sheet link, do the following:<br />
1. Open the Styles view from the Web perspective by selecting Window -><br />
Show View -> Styles.<br />
2. Open the file that you want to link to a cascading style sheet.<br />
3. Select the Select and Link to external style sheet tool bar button in the<br />
Styles view, which opens the Select and Link to External Style Sheet dialog.<br />
4. Click the list button to locate the external style sheet that you want to link to.<br />
You have the option of either locating the desired .css file within your project<br />
workspace (by selecting the Browse menu option), or importing one of the<br />
samples provided with <strong>WebSphere</strong> Studio, using the Import from Samples<br />
menu option.<br />
5. Select the Link radio button from Insertion type, and then click the OK button.<br />
You can also select the Import radio button from Insertion type. This type is,<br />
however, not supported by all browsers. Therefore, it is recommended that<br />
you select the Link radio button unless there is good reason to do otherwise.<br />
The name of the selected style sheet file appears in the Styles view, and the<br />
settings in the style sheet file are applied to the page being edited.<br />
Tip: If you have embedded styles in the HTML file, the embedded styles<br />
override the style specifications in an external style sheet file.<br />
5.1.10 Working with WebArt Designer<br />
WebArt Designer is a program for creating and editing image files. To edit an<br />
image file, simply open it from the Project Navigator view. The file will<br />
automatically open in the WebArt Designer. If you want to create a new image,<br />
you can open the designer by selecting File -> New -> Web -> Image File. Or<br />
you can select WebArt Designer from the Tools drop-down if it is visible.<br />
122 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The WebArt Designer supports the following image types and file extensions:<br />
► WebArt files (*.mif)<br />
► GIF files (*.gif)<br />
► JPEG files (*.jpg, *.jpeg, *.jpe)<br />
► PNG files (*.png)<br />
► Bitmap file (*.bmp)<br />
Tip: You can insert an image created with WebArt Designer into a Web page<br />
in the same way as a regular image file.<br />
You can see the WebArt Designer in Figure 5-25.<br />
Gallery<br />
Figure 5-25 WebArt designer - window 1<br />
Canvas<br />
Object<br />
Stack<br />
When the designer opens, you will see three areas:<br />
► Canvas: the canvas is where you build the graphic.<br />
► Template gallery: the gallery is a collection of predefined buttons, logos, and<br />
other graphics image types available for use. At the top, you will see two tabs,<br />
Chapter 5. Working with HTML 123
the WebArt Gallery tab and the Gallery tab. Under each tab is a list of object<br />
types from which you can choose. Selecting a type will display the objects of<br />
that type in the lower pane. You can use an object by dragging it to the<br />
canvas.<br />
► The object stack area: this indicates the relationships of the objects and<br />
allows you to select one or more objects in the canvas.<br />
Building an image involves working with objects. The following are object types<br />
used in WebArt Designer:<br />
► Shapes: consisting of lines.<br />
► Logos: designed text.<br />
► Buttons: images that resemble a button.<br />
► Photo frames: photo frame that decorates a photographic image.<br />
► Clip art: Windows metafile read by WebArt Designer. Maintains better quality<br />
when its size is changed compared to an “image” object.<br />
► Image: all images other than the preceding four types of objects. Any image<br />
file created by software other than WebArt Designer is this type of object.<br />
Basically, you will build an image by adding objects to the canvas and saving the<br />
canvas for use in projects. You can also save objects to add to the gallery.<br />
Creating a sample object<br />
Let us walk through an example.<br />
1. Open the WebArt Designer by selecting File -> New -> Web -> Image File.<br />
2. Name the file and select the images folder in your project. Select GIF for the<br />
file type and click Finish. The WebArt Designer will open with a blank canvas.<br />
3. Open the Gallery tab and select the Materials for Wallpaper folder under the<br />
Gallery list. Select an object and drag it to the canvas. You will see the<br />
wallpaper object appear in the object stack area. Drag the corner of the object<br />
so that the wallpaper covers most of the canvas.<br />
124 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-26 Using the WebArt Designer - 1<br />
4. Highlight Buttons in the gallery and select the About Us object. Drag the<br />
object to the canvas and place it near the top of the wallpaper.<br />
5. Add text by selecting the text icon to the left of the canvas. Move the cursor to<br />
the canvas and type Welcome to our Site. As you add each object, notice<br />
that it is also placed in the object stack area. The top object is in front of the<br />
other objects. You can change the order by dragging objects to a new position<br />
in the object stack area. For example, if you put the wallpaper object at the<br />
top, all other objects are hidden.<br />
Chapter 5. Working with HTML 125
Figure 5-27 Using the WebArt Designer - 2<br />
6. Add an oval object and stack it over the text. You will need to rearrange the<br />
objects in the object stack area so the text appears over the oval. Right-click<br />
in the oval and select Edit Object to change the color.<br />
126 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-28 Using WebArt Designer - 3<br />
stack the text above the oval<br />
7. If you think you will use this new image again in graphic design, you should<br />
save the canvas as a WebArt file (*.mif). Just select File -> Save Canvas as.<br />
Or, if you want to save certain objects, you can select the object (or group<br />
multiple objects into one) and then save the object with File -> Save Object.<br />
For example, if you want to save the oval and text in Figure 5-28, select the<br />
oval object and the text object in the object stack area. Then group the<br />
selected objects using Object -> Group -> Group. With the new grouped<br />
object selected, use the File -> Save Object option to save it.<br />
Note: You can select multiple adjacent objects by holding the Shift key<br />
while you click the objects at both ends of the list. You can use the Ctrl key<br />
instead if the objects are not next to each other in the list.<br />
The objects you save as WebArt files are available to you by browsing to the<br />
folder where they are stored in the gallery under the Folder option.<br />
Chapter 5. Working with HTML 127
Figure 5-29 Grouping objects<br />
You will notice that the new group is represented as one object in the object<br />
stack area.<br />
8. The last step is to save the canvas as a GIF file so that you can use it in your<br />
application. Select File -> Save Canvas as and enter the folder and image<br />
name. You can place the image directly into your project (for example, an<br />
images file) by browsing to the project location in the workspace. Or you can<br />
save it to a local directory and use drag and drop to add it to your Web page.<br />
This example is very basic. To effectively use the WebArt Designer, you need to<br />
open the WebArt Designer help. We suggest you read through the help topics<br />
before beginning.<br />
5.1.11 Working with animation<br />
An animated GIF is a series of image files in GIF format, displayed sequentially<br />
to give the appearance of an animation. You can insert an animated GIF into a<br />
page in the same way as a regular GIF image file. Animated GIFs can be viewed<br />
on a regular Web browser without any special plug-ins.<br />
128 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The AnimatedGif Designer is a program for creating animated GIF files, and<br />
comes with a gallery of predefined animation files. With the AnimatedGif<br />
Designer, you can:<br />
► Combine several images to create an animation.<br />
► Apply an animation effect on a single image to create an animation.<br />
► Apply an animation effect on text to create an animated banner.<br />
Frame<br />
An animation created with AnimatedGif Designer is a collection of frames. A<br />
frame is displayed in the frame display window. If you double-click a frame, a<br />
dialog for setting frame properties appears.<br />
Frames are categorized into three types: the image frame, the attribute frame,<br />
and the comment frame, as shown in Figure 5-30 on page 130.<br />
► Attribute frame: the first frame of an animation. You cannot move this frame<br />
from its location or delete it. The attribute frame contains information related<br />
to the entire animation, such as the specification of the color palette and the<br />
repetition count. To view and change those attributes, double-click the<br />
attribute frame. This frame does not appear on the screen when the animation<br />
is played on a Web browser.<br />
► Image frame: aframe for a single image in an animation. Image frames are<br />
generated when you insert image files or when you add animation effects. To<br />
change the properties of an image frame, double-click it.<br />
► Comment frame: the frame used for inserting your comments into the<br />
animated GIF file. You can insert, for example, the date when the animation<br />
was created or the name of the person who created it. To insert a comment<br />
frame, click Edit -> Insert Comments on the menu bar. This frame does not<br />
appear on the screen when the animation is played on a Web browser.<br />
Chapter 5. Working with HTML 129
Figure 5-30 Type of frames<br />
Creating a sample animation<br />
To use the AnimatedGif Designer, you should open it and select the help from the<br />
toolbar. We will take you through a quick example, but this only highlights one<br />
specific usage.<br />
The following explains how to create an animation from a set of images.<br />
1. Open the AnimatedGIF Designer by selecting Tools -> AnimatedGIF<br />
Designer. In the first window, select Animation Wizard.<br />
Note: If you do not see the Tools drop-down, open an HTML or JSP file in<br />
the editor.<br />
2. Select the Create an animation using more than one image option, and<br />
then click the Next button (note the other options here).<br />
130 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-31 Animation Wizard dialog<br />
3. In the next window of the wizard, click the Add Image button, select an image<br />
file, and then click the Open button. Each image you select is added to the<br />
list. You can repeat this step as many times as you like until you have added<br />
all of the images you want to use.<br />
Tip: If you click files while holding down the Shift key or the Ctrl key, you<br />
can select more than one file at a time. The Shift key allows you to select<br />
multiple sequential files. The Ctrl key allows you to select files at random.<br />
Figure 5-32 Animation Wizard dialog<br />
Chapter 5. Working with HTML 131
The animation is played starting with the first image in the list. Drag the name<br />
of the image file to the position you want, or click the First, Up, Down, and<br />
Last buttons to rearrange the images. When you have the images in the<br />
correct order, click the Next button.<br />
4. The next window allows you to work with the alignment of the images.<br />
Figure 5-33 Animation Wizard dialog<br />
Click Next.<br />
5. In the next screen, specify the repetition count of the animation and the delay<br />
time of each frame.<br />
Figure 5-34 Animation Wizard dialog<br />
132 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Click Next.<br />
6. The next screen allows you to preview the animation. If you need to make<br />
changes, you can step back through the wizard.<br />
Figure 5-35 Animation Wizard dialog<br />
7. Click the Finish button. The Animation Wizard ends and the frames for the<br />
images used in the animation are displayed in the animation window with the<br />
title newimagex.<br />
Tip: A single animation window corresponds to a single animated GIF file.<br />
8. Click File -> Save As on the menu bar and specify the location and file name<br />
of the animated GIF file to be saved. Then click the Save button.<br />
The animated GIF can be added to a Web page just as you would add any other<br />
image file.<br />
Chapter 5. Working with HTML 133
Figure 5-36 <strong>WebSphere</strong> Studio AnimatedGif Designer<br />
The animation you have created is saved as a single animated GIF file.<br />
134 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
5.2 Adding HTML pages to the Online Catalog sample<br />
This example will illustrate how to use the Web Site Designer and page<br />
templates to build application pages. A standard template will be used as the<br />
basis for the Web pages. The template we chose has a place for a company logo<br />
at the top and a navigation bar to the left. In this example, we will update the<br />
standard template to hold our company logo, then create two pages for the<br />
application. The first page, index.html, is the entry point for the application. The<br />
second page, aboutus.html, is a company information page. It will be created as<br />
a child page of index.html, automatically creating a link from the navigation bar.<br />
This link is reflected in all pages using the page template.<br />
Tip on finding the default welcome page for a Web application: The Web<br />
deployment descriptor contains a list of file names that will be used to<br />
determine the initial application welcome page. This list is seeded with default<br />
file names, including index.html, when you create the Web project. To see the<br />
list, open the Web deployment descriptor by double-clicking it in the Project<br />
Navigator view. When it opens in the editor area, select the Pages view.<br />
5.2.1 Creating HTML pages using Web Site Designer<br />
Web Site Designer will be used to create the index.html page and to layout the<br />
first child page for the Online Catalog sample. Creating pages using the Web Site<br />
Designer is an alternative to the method used in previous releases (New -><br />
HTML/XHTML File or New -> JSP File). That method is still valid and available.<br />
5.2.2 Customizing a page template<br />
In our sample, we have created a Web project and specified the B-01_blue.htpl<br />
page template as a default. Because this is a standard template supplied with<br />
Studio, we will need to customize it to include our company logo and name<br />
before creating our Web pages. All of the files related to the template are stored<br />
in the theme folder under the Web Content directory.<br />
1. Expand the Web Content folder within the OnlineCatalog Web project.<br />
2. Expand the theme folder. Notice the six files in the folder. These are all used<br />
to create the template.<br />
– B-01_blue.htpl<br />
– blue.css<br />
– c.gif<br />
– footer.html<br />
– logo_blue.gif<br />
– nav_side.html<br />
Chapter 5. Working with HTML 135
3. To add our company name to the Web site, the B-01_blue.htpl page needs to<br />
be edited. Double-click the B-01_blue.htpl file. The page is opened in the<br />
Source view of the Page Designer for Template editor.<br />
Figure 5-37 Page Designer for Template editor<br />
4. Change the page title by highlighting the text between the tags and<br />
typing Tom, Dick & Harry’s RVs....<br />
136 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-38 Page Designer for Template editor<br />
5. Change to the Design view by clicking the Design tab at the bottom of the<br />
editor.<br />
6. Click the data cell to the right of the default company logo and type in Tom,<br />
Dick & Harry’s RVs....<br />
7. The default text color is black, which is difficult to see against the blue<br />
background. To address this, we will create a new Cascading Style Sheet<br />
(CSS) class and apply it to the text.<br />
Highlight the Tom, Dick & Harry’s RVs... text and right-click.<br />
8. From the context menu, select Style -> Add Style Rule.... The Set Selector<br />
of New Style dialog opens.<br />
Important: Using this method adds the style to the page. In this example, it is<br />
fine because we are working with a template and all changes made in the<br />
template will be reflected in any page that is referencing the template. If you<br />
are not using a template, the CSS class being created should first be added to<br />
a CSS file and then referenced in the page. For more information on using<br />
CSS, please see 5.1.9, “Working with style sheets” on page 120.<br />
9. Select the Class radio button and enter .page-header as the Class name.<br />
Chapter 5. Working with HTML 137
Figure 5-39 Set Selector of New Style dialog<br />
10.Click OK. The Add Style dialog opens.<br />
11.Select Fonts from the style element selection window.<br />
12.From the Font family font selection window, scroll down and select the Arial<br />
font, then click Add.<br />
13.From the Color drop-down list, select White.<br />
14.In the Size drop-down list, select 18.<br />
138 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-40 Add Style dialog<br />
15.Select Fonts styles from the style element selection window.<br />
16.From the Weight drop-down list, select Bold.<br />
Chapter 5. Working with HTML 139
Figure 5-41 Add Style dialog<br />
17.Click OK.<br />
18.Now that a new CSS class called .page-header has been created, we can<br />
apply it to the text. Highlight Tom, Dick and Harry’s RVs... once again and<br />
right-click. From the context menu, select Style -> Apply Class -><br />
page-header. The text will be edited to include the display features that were<br />
created.<br />
140 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-42 Formatted page header text<br />
19.Save the B-01_blue.htpl page by closing the Page Designer for Template<br />
Editor and clicking Yes from the Save Resource window.<br />
Figure 5-43 Saving the template<br />
20.The last thing to do before creating the HTML page is to edit the company<br />
logo. From the theme folder, double-click the logo_blue.gif file. <strong>WebSphere</strong><br />
Studio Art Designer is opened and the image is shown in the editor.<br />
Chapter 5. Working with HTML 141
Figure 5-44 <strong>WebSphere</strong> Studio Art Designer<br />
Text tools<br />
21.Select the Text tool button from the toolbar.<br />
The Text tool parameters are displayed at the bottom of the toolbar.<br />
22.Change the text parameters as follows: Color = White; Font = Arial; Size = 18;<br />
Weight = Bold.<br />
23.Click in the center of the image and type TDH.<br />
24.Position the text to be in the center of the image.<br />
142 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-45 Edited company logo<br />
25.Highlight all the elements of the new image and right-click.<br />
26.From the context menu, select Save Wizard for Web.... The Save Wizard<br />
dialog opens.<br />
27.Click Next twice and then click Finish. The Save As dialog opens.<br />
28.Locate the theme folder of the Web project, select the logo_blue.gif file and<br />
click Save. The theme folder can be found at:<br />
//WebContent/theme<br />
When prompted to replace the previous version, click Yes.<br />
29.Close <strong>WebSphere</strong> Studio Art Designer.<br />
5.2.3 Creating HTML pages<br />
Now that the template has been updated, we can begin to create our HTML<br />
page.<br />
1. Expand the OnlineCatalog Web project and double-click Web Site<br />
Configuration.<br />
Chapter 5. Working with HTML 143
Figure 5-46 Opening Web Site Designer<br />
2. The Web Site Designer opens in the editor area with two views: Navigation<br />
and Detail. Right-click in the Navigation view and select Add New Page -> As<br />
Top.<br />
Figure 5-47 Web Site Designer - Navigation view<br />
A page icon will appear representing a Web application page. The first page<br />
created in a new Web site only has the option of becoming the top page, or<br />
the top of the navigation hierarchy. The next page that is added can be set in<br />
relation to the top page.<br />
144 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3. Replace the Navigation Label text newpage with Home.<br />
4. Right-click the Home icon and select Create Page from the context menu.<br />
Figure 5-48 Create a new page<br />
5. You will be prompted to select whether you want to create a new HTML or<br />
JSP page. Select HTML and click OK.<br />
6. Make sure that /OnlineCatalog/Web Content is shown as the folder name<br />
and enter index for the file name. Verify that HTML and Page Template have<br />
been selected for the Markup Language and Model, respectively.<br />
Chapter 5. Working with HTML 145
Figure 5-49 Creating an HTML page<br />
7. Click Next.<br />
8. Verify that the B-01_blue.htpl template has been selected.<br />
146 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 5-50 Creating an HTML page<br />
9. Click Finish.<br />
The new file opens in Page Designer.<br />
Chapter 5. Working with HTML 147
Figure 5-51 index.html opened in Page Designer<br />
10.Close Page Designer by clicking the X on the index.html tab and return to the<br />
Web Site Designer.<br />
11.Now you have a new Web site with the top page defined. You can continue<br />
populating your site by creating page icons in Web Site Designer to map out<br />
your site (see Figure 5-52 on page 149). You can use Web Site Designer to<br />
plan and layout your whole site's organization, and then create each of the<br />
Web page files to fill out the site.<br />
12.To add an additional page icon, right-click in the Navigator view and select<br />
Add New Page -> As Child from the context menu. This will add a child page<br />
to index.html.<br />
13.Change the Navigation Label text to About Us.<br />
14.Creating the new page is done in the same manner as was done with<br />
index.html. Right-click the About Us page icon and select Create Page from<br />
the context menu.<br />
15.Select HTML as the file type.<br />
16.Click OK.<br />
17.Name the page aboutus.html and click Next.<br />
148 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
18.Click Finish.<br />
The new page is opened in Page Designer.<br />
19.Close Page Designer.<br />
20.Save Web Site Designer by pressing Ctrl-S.<br />
Figure 5-52 Web Site Designer - Navigator view<br />
Web Site Designer can be closed by clicking the X on the OnlineCatalog tab.<br />
Tip: Experienced Web designers may have preferences as to how an HTML<br />
page is created. The HTML file preferences allow you to influence many<br />
aspects of HTML file content during creation and editing. To set the<br />
preferences, select Window -> Preferences -> Web and XML files -> HTML<br />
files.<br />
21.When the Web site is run on the server, the navigation links on the template<br />
will dynamically be generated based on the site map created.<br />
Chapter 5. Working with HTML 149
Figure 5-53 Runtime of index.html<br />
150 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Navigation links
Note: By default, every page that is added to the site map will be added as a<br />
navigation link. To remove a page from the navigation, right-click it and select<br />
Navigation -> Navigation Candidate. Verify that there is no check mark<br />
beside the Navigation Candidate option. This will disable the feature for the<br />
selected page and the Navigation Label text for that page will not be shown as<br />
a navigation link.<br />
The Navigation Root feature is helpful if you wish to set a page in the site as a<br />
navigation root. By default, the first page you add to the Web diagram is set as<br />
the navigation root and any page added as a child of the navigation root page<br />
will have links added to the navigation bar (as long as they are navigation<br />
candidates). But what if you wanted to start a different navigation root within<br />
your site? Right-click the page in the Web site diagram editor and select<br />
Navigation -> Navigation Root from the context menu. This page will no<br />
longer contain the child links from the original navigation root page, but rather<br />
will have links to any child pages from itself.<br />
The Site Map Candidate feature is also very interesting. If a page in the Web<br />
site diagram is enabled as a Site map candidate, the page will show up in the<br />
site map if the Site Map item from the Site Parts drawer of the Palette view is<br />
used. To enable and disable the site map candidate feature, right-click a page<br />
icon in the Web diagram editor and select Site Map -> Site Map Candidate<br />
from the context menu. For more information on using a site map, please see<br />
“Inserting a site map” on page 106.<br />
Chapter 5. Working with HTML 151
152 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 6. Accessing databases<br />
This chapter provides information on accessing databases and using the<br />
information in Web pages. The following topics will be discussed:<br />
► Java Database Connectivity (JDBC) overview<br />
► Working with databases in Studio Site Developer<br />
Runtime database access will be discussed in Chapter 13, “Deploying<br />
applications” on page 455.<br />
6<br />
Note: This chapter assumes that you have installed a database product. The<br />
example assumes that you have installed <strong>IBM</strong> DB2 on the Studio Site<br />
Developer system. Assuming that the development machine, the database<br />
server machine, and the application server machine are three separate<br />
physical machines, you will need the following:<br />
► Database server: Must have a database product installed<br />
► Development machine (with Studio Site Developer): Must have access to<br />
database drivers<br />
► <strong>Server</strong> machine (with Express <strong>Application</strong> <strong>Server</strong>): Must have access to<br />
database drivers<br />
© Copyright <strong>IBM</strong> Corp. 2003 153
6.1 Java Database Connectivity (JDBC) overview<br />
JDBC allows you to make calls to databases from your Java applications or Java<br />
applets. JDBC is vendor neutral and provides access to a wide range of relational<br />
databases, as well as to other tabular sources of data. It can even be used to get<br />
data from flat files or spreadsheets. This portability and versatility are the main<br />
attractions of using JDBC for database access in application programs.<br />
Figure 6-1 shows the basic components of a JDBC connection.<br />
Java <strong>Application</strong><br />
JDBC Driver Manager<br />
Vendor-supplied JDBC Driver<br />
Figure 6-1 JDBC overview<br />
JDBC API<br />
The JDBC API sends the SQL commands from the application to the JDBC<br />
driver manager, which in turn talks to the vendor-specific driver that actually<br />
connects to the database.<br />
6.1.1 Data source versus direct connection<br />
JDBC 2.0 provides two methods of establishing database connections. The first<br />
method is done by using the driver manager interface. This is a carry over from<br />
JDBC 1.0 and is expensive in terms of performance. Using this method, a<br />
connection is created each time you access the database from your program,<br />
thereby incurring a substantial processing overhead.<br />
The JDBC 2.0 Standard Extension API introduced an alternative way of handling<br />
database connections using data source objects. By using data source objects,<br />
you have access to a pool of connections to a data source. Connection pooling<br />
gives you the following advantages:<br />
154 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
JDBC Manager Driver API<br />
Database
► It improves performance. Creating connections is expensive; a data source<br />
object creates a connection as soon as it is instantiated.<br />
► It simplifies resource allocation. Resources are only allocated from the data<br />
source objects, and not at arbitrary places in the code.<br />
► It simplifies connection calls.<br />
Data source objects work as follows:<br />
1. When a servlet or other client wants to use a connection, it looks up a data<br />
source object by name from a Java Native Directory Interface (JNDI) server.<br />
2. The data source object then returns a connection to the client.<br />
3. If the data source object has no more connections, it may ask the database<br />
manager for more connections (as long as it has not exceeded the maximum<br />
number of connections).<br />
4. When the client has finished with the connection, it releases it.<br />
5. The data source object then returns the connection to the available pool.<br />
Note: Because of the advantages of connection pooling, using data source<br />
objects is the preferred method of handling database connections in Web<br />
applications. The Express <strong>Application</strong> <strong>Server</strong> has full support for connection<br />
pooling and for registering data sources via JNDI.<br />
6.2 Working with databases in Studio Site Developer<br />
Studio Site Developer provides a number of features that make it easier to work<br />
with relational databases in your projects. These features include:<br />
► The ability to import and use existing database models<br />
► The ability to create your own database objects and generate DDL for the<br />
target database<br />
► The ability to generate XML schemas from database models<br />
► An SQL wizard to interactively build and execute SQL queries from an<br />
imported database model or via an active connection<br />
► The ability to generate Web pages and supporting Java classes based on<br />
existing or new SQL queries<br />
► The ability to access database API from Java<strong>Server</strong> Pages using either<br />
JavaBeans or JSP tags<br />
Chapter 6. Accessing databases 155
Using databases in an application involves several steps. From start to finish<br />
these steps can be summarized as:<br />
1. Create the database<br />
This is done using the database product, not the Studio Site Developer.<br />
2. Connect Studio Site Developer to the database<br />
This is done to enhance application development. (The server connection to<br />
the database for runtime execution is done separately.) Once the connection<br />
is made, it will remain for the life of the session. If you restart Studio Site<br />
Developer you will need to reconnect to the database in order to use<br />
database tools such as the Database Web Pages wizard.<br />
3. Import and work with the database design<br />
Studio Site Developer can look at the database and create design elements<br />
(schema, tables, views, etc.) that reflect the structure of the database. You<br />
can also use Studio Site Developer to create SQL statements that can be<br />
used to add tables, schema, etc.<br />
4. Code JSPs and/or servlets to access the database tables<br />
This can be done manually or using wizards.<br />
5. Connect the runtime environment to the database<br />
The application server needs a JDBC provider definition that points to the<br />
driver classes needed to access the database. If a data source connection is<br />
used, a data source definition must be defined to the server, naming the<br />
database and other access information.<br />
6.2.1 Using the Data perspective<br />
Studio Site Developer provides a perspective to handle the unique aspects of<br />
working with databases called the Data perspective. You use the Data<br />
perspective to connect to relational databases for application and database<br />
design purposes.<br />
If you are connecting to an existing database, you can import the database<br />
design into the project. This makes information about the database available to<br />
wizards that assist in building database access code. If you are building an<br />
application and have not created a database yet, you can design the database in<br />
Studio Site Developer and create the SQL needed by the database product to<br />
create the schema and tables needed for the application.<br />
156 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-2 Data perspective<br />
Here we describe aspects of the Data perspective:<br />
► DB <strong>Server</strong>s view: Allows you to create database connection definitions, or to<br />
connect/disconnect using existing definitions. If a connection is active, the<br />
database elements (as they exist in the database) can be seen and imported<br />
to a project.<br />
► Data Definition view: Allows you to work with the database elements. For<br />
example, you can define new schema or tables. Double-clicking an object in<br />
the Data Definition view will open it in the editor for modification. Note that this<br />
view shows the database elements as defined to Studio Site Developer. This<br />
may not be the same as the elements that actually exist in the database.<br />
► Outline view: Shows a tree structure of the elements in the resource open in<br />
the editor.<br />
► DB Output view: Displays information about actions related to stored<br />
procedures and user-defined functions.<br />
Chapter 6. Accessing databases 157
6.2.2 Creating the database<br />
Although Studio Site Developer can interact with databases, it cannot create a<br />
database for you. To begin, you must use the database product facilities to create<br />
the database.<br />
To illustrate the database access features of Studio Site Developer we will take<br />
you through the process we used to create and work with the SALESAPP<br />
database for our sample application. We recreated the sample using <strong>IBM</strong> DB2,<br />
Oracle, and Microsoft SQL <strong>Server</strong>.<br />
DB2<br />
In DB2 you can use the DB2 Control Center to create a database by selecting<br />
Databases -> Create -> Database. Or you can open a DB2 command window<br />
and enter:<br />
db2 create db SALESAPP<br />
The user that creates the database will be granted full access. You should<br />
consider creating a user ID (on the database server) and giving that user ID the<br />
proper access for the application. You can use the DB2 Control Center to do this.<br />
Oracle<br />
In Oracle a database name is specified during installation and tablespaces are<br />
created afterward to hold data. In this example, we have installed an Oracle<br />
instance and are now creating a tablespace named SALESAPP. This can be<br />
done either interactively in the Enterprise Manager console, or by doing the<br />
following with SQLPLUS:<br />
1. Create a tablespace called SALESAPP. For example:<br />
create tablespace salesapp datafile ‘saleslog’ size 4M reuse autoextend on<br />
next 2M maxsize unlimited<br />
2. Create a user and grant the dba option. For example, to add the db2admin<br />
user execute the following:<br />
create user db2admin profile default identified by db2admin default<br />
tablespace salesapp ;<br />
grant dba to db2admin with admin option;<br />
Microsoft SQL <strong>Server</strong><br />
In our sample application database we use a mechanism to generate<br />
incremental numbers in columns. In DB2 and Oracle this is achieved by creating<br />
a database object of type sequence. In SQL <strong>Server</strong> this can be achieved by<br />
creating a one-column/one-row table that stores order numbers and is manually<br />
incremented every time it is used. Unfortunately, since SQL handles this<br />
158 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
differently than DB2 and Oracle, the Online Catalog sample application pages<br />
will not work on a SQL <strong>Server</strong> database created in the same manner. However,<br />
for illustration purposes, here is the command to create a SALESAPP database<br />
on a SQL <strong>Server</strong>.<br />
CREATE DATABASE [salesapp] ON (NAME = N'salesapp_Data', FILENAME =<br />
N'C:\Program Files\Microsoft SQL <strong>Server</strong>\MSSQL\data\salesapp_Data.MDF' ,<br />
SIZE = 1, FILEGROWTH = 10%) LOG ON (NAME = N'salesapp_Log', FILENAME =<br />
N'C:\Program Files\Microsoft SQL <strong>Server</strong>\MSSQL\data\salesapp_Log.LDF' , SIZE<br />
= 1, FILEGROWTH = 10%)<br />
6.2.3 Connecting Studio Site Developer to the database<br />
Now that we have a database to work with we need to show Studio Site<br />
Developer where it is. To do this, we create a connection to the database.<br />
1. Open the Data perspective by selecting Window -> Open Perspective -><br />
Data.<br />
2. Right-click anywhere in the DB <strong>Server</strong>s view and select New Connection.<br />
Figure 6-3 New connection<br />
Chapter 6. Accessing databases 159
3. This will open the The New Database Connection wizard. For this exercise<br />
we used a DB2 database.<br />
We did, however, also test with Oracle and Microsoft SQL <strong>Server</strong> and will<br />
show you the connection for these.<br />
Figure 6-4 Creating a connection to a DB2 database<br />
a. DB2 connection<br />
The values needed in the wizard for connecting to a DB2 database are<br />
shown in Figure 6-4.<br />
The Connection name will be OnlineCatalogConn. This name is only<br />
used to identify the connection. It is chosen at random.<br />
The Database name is SALESAPP. This must be the same value you<br />
named your database when you created it using your database<br />
software.<br />
The User ID and Password you enter must have the proper<br />
authorization to access the database. In this case, we will use<br />
db2admin and db2admin, for the user ID and password.<br />
160 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The Database vendor type drop-down box contains a list of vendor<br />
databases that can be used in Studio Site Developer. We chose DB2<br />
Universal Database Express V8.1.<br />
The database is a local DB2 database, so we select the <strong>IBM</strong> DB2 APP<br />
Driver as the JDBC driver. In this instance, the JDBC driver class to<br />
match the selection (COM.ibm.db2.jdbc.app.DB2Driver) is filled in for<br />
you.<br />
Verify that the class location is correct. The drivers are supplied by the<br />
database vendor so you will need to have the drivers installed locally,<br />
even if you are accessing a remote server.<br />
If you wish to limit the schemas or tables returned use the Filters option.<br />
This option is typically used to filter out system tables since they are<br />
usually not needed in designing Web applications. It reduces the clutter of<br />
tables in the schema. This is not necessary and we did not do this.<br />
b. Oracle connection<br />
Figure 6-5 shows the same connection to an Oracle database. In this<br />
case, we chose the Oracle THIN JDBC driver. Oracle 9i is also<br />
supported.<br />
Figure 6-5 Connecting to an Oracle database<br />
Chapter 6. Accessing databases 161
Note that the class location points to the Oracle installation libraries.<br />
c. Microsoft SQL <strong>Server</strong><br />
The SQL <strong>Server</strong> location we used was a remote server. We connected to<br />
the database using the DataDirect Connect JDBC driver.<br />
Figure 6-6 Setting SQL <strong>Server</strong> connection<br />
4. Click Finish.<br />
6.2.4 Importing and working with the database design<br />
We now need to import the database design information into our project in order<br />
to take advantage of the database tools provided by Studio Site Developer.<br />
Importing the design<br />
Assuming you are connected to the database, you can import the design by<br />
doing the following:<br />
1. Right-click the new connection in the DB <strong>Server</strong>s view and select Import to<br />
Folder.<br />
162 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
2. A window will open to allow you to enter or browse to the folder (Web project)<br />
where you want the database design imported. Click Browse and select the<br />
OnLineCatalog project. Click OK and then Finish.<br />
Note: Do you need to reconnect to the database? If you need to<br />
re-establish a connection to the database, select the database in the DB<br />
<strong>Server</strong>s view. Right-click and select Reconnect.<br />
3. The imported information is stored by the wizard in the<br />
Web Content/WEB-INF/databases/SALESAPP directory. If this is the first<br />
time you have worked with a database in the project you will be asked if the<br />
wizard should create the directory. Click Yes.<br />
In this case, the database has been newly created so the import will just add a<br />
folder for the database and a Statements folder underneath. If you had imported<br />
a database with existing tables, views, schema, etc., you would see much more.<br />
Creating a schema<br />
When you imported the database to the Web project, a directory structure was<br />
created under the Web Content/WEB_INF folder to contain the database design<br />
information. You can see this in the Data Definition view by expanding the<br />
OnlineCatalog Web project folder.<br />
Note: If you have installed the sample application and created the database<br />
using the DB2 commands included with the additional material, the tables<br />
have already been created for you and the following steps do not apply. Just<br />
read through them so you will know how we did it.<br />
1. Find the Web Content/WEB_INF/databases/SALESAPP directory, right-click,<br />
and select New -> New schema definition....<br />
Chapter 6. Accessing databases 163
Figure 6-7 Create a schema<br />
2. Enter a schema name. For example, a common schema is the user ID of the<br />
user that will be accessing the database. For the Online Catalog application<br />
we use db2admin.<br />
3. Click Finish.<br />
Creating the database columns and tables<br />
The sample database will need the following tables to store data:<br />
► Item<br />
► Customer<br />
► Shipping_Order<br />
► Users<br />
We will show you the layout of each table and then show you how to use Studio<br />
Site Developer to create the SQL statements needed to create the tables.<br />
164 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
ITEM table<br />
The ITEM table contains the inventory items (Table 6-1).<br />
Table 6-1 ITEM table<br />
Column type Length Nullable Key<br />
ITEM_NUMBER character 5 N Y<br />
ITEM_SHORT_DESC varchar 50 Y N<br />
ITEM_LONG_DESC varchar 150 Y N<br />
QUANTITY integer Y N<br />
PRICE decimal 9,2 Y N<br />
SOTD_FLAG character 1 Y N<br />
CUSTOMER table<br />
The CUSTOMER table contains information about registered customers<br />
(Table 6-2).<br />
Table 6-2 CuSTOMER table<br />
Column type Length Nullable Key<br />
CUSTOMER_ID character 10 N Y<br />
CUSTOMER_NAME varchar 40 Y N<br />
ADDRESS varchar 40 Y N<br />
CITY varchar 40 Y N<br />
STATE character 2 Y N<br />
EMAIL_ADDRESS varchar 20 Y N<br />
PHONE character 10 Y N<br />
CC_TYPE character 2 Y N<br />
CC_NUMBER varchar 20 Y N<br />
ZIP character 5 Y N<br />
INTEREST1 character 1 Y N<br />
INTEREST2 character 1 Y N<br />
PASSWORD character 10 N N<br />
Chapter 6. Accessing databases 165
SHIPPING_ORDER table<br />
The SHIPPING_ORDER table contains orders submitted by customers<br />
(Table 6-3).<br />
Table 6-3 SHIPPING_ORDER table<br />
Column type Length Nullable Key<br />
ORDER_NUMBER integer N Y<br />
CUSTOMER_ID character 10 N N<br />
ITEM_NUMBER character 5 N N<br />
QUANTITY smallint Y N<br />
SALE_PRICE decimal 9,2 Y N<br />
ORDER_DATE date Y N<br />
STATUS character 1 Y<br />
USERS table<br />
The USERS table contains users with administrative capabilities (Table 6-4).<br />
Table 6-4 USERS table<br />
Column type Length Nullable Key<br />
USERNAME character 8 N Y<br />
PASSWORD character 8 N N<br />
When you created the schema (db2admin) earlier, a new folder structure for the<br />
schema was created under the SALESAPP folder. This structure includes<br />
subfolders for database elements (tables, views, etc.). To create the ITEM table<br />
in our database schema:<br />
1. Select the WEB-INF/databases/SALESAPP/db2admin/tables folder,<br />
right-click, and select New -> New table definition.<br />
2. Enter ITEM for the table name.<br />
166 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-8 Create a new table definition<br />
Click Next.<br />
3. In the next window, add each column name and data type using the Add<br />
Another button. Use Table 6-1 on page 165 as a reference for the columns<br />
that are needed in the ITEM table. When you are finished you should have a<br />
layout that looks like Figure 6-9 on page 168.<br />
Chapter 6. Accessing databases 167
Figure 6-9 Create the table columns<br />
Click Next.<br />
4. Now the wizard prompts for the primary key. In the case of our ITEM table, the<br />
ITEM_NUMBER column represents a unique value and so is a candidate for<br />
the primary key. All the other columns were nullable and so will not show up<br />
as key candidates. When you created the ITEM_NUMBER column you should<br />
have selected the Key column field (see Figure 6-9), so the key should<br />
already be selected. Change the primary key name to PK_ITEM. The wizard<br />
should now look like Figure 6-10 on page 169.<br />
168 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-10 Specify the primary key<br />
5. Click Next. We do not have any foreign keys so click Finish.<br />
6. Repeat the steps for creating the CUSTOMER, SHIPPING_ORDER,<br />
ANDUSERS tables.<br />
Generating DDL statements<br />
At this point you are probably wondering why Studio Site Developer needs to<br />
know about the database design. One good reason is that you can generate DDL<br />
statements to use as input to the database server to define the database<br />
elements (schema or tables). The alternative would be to create them using the<br />
database product, for example, the DB2 Control Center, and then import the<br />
design to Studio Site Developer. If you had an existing database with data, then<br />
this would be the way to go. But if you are creating the database to support the<br />
application, then using Studio Site Developer to create the design would be<br />
preferable.<br />
Chapter 6. Accessing databases 169
The next logical step is to create data definition language (DDL) statements for<br />
the tables we created. The DDL will contain the necessary SQL to create each<br />
table.<br />
1. Right-click the ITEM table in the Data Definition view and select Generate<br />
DDL.<br />
Figure 6-11 Generating DDL<br />
2. Enter the name of the folder where you want the generated .sql file to be<br />
stored and select options for the generation.<br />
– Generate SQL DDL with fully qualified names: This will include the<br />
schema name when referring to tables.<br />
– Generate SQL DDL with delimited identifiers: This option adds enclosing<br />
quotes, which are needed by some database vendors.<br />
– Generate associated drop statements: This option helps in dropping<br />
existing tables. This option is typically required for incremental database<br />
modifications when tables already exist.<br />
– Open SQL DDL file for editing when done: This will open the file at the end<br />
of the wizard. You do not need to select this unless you are curious to see<br />
the generated SQL. The table.sql file will be placed in the databases folder<br />
by default and you can open it at any time for editing or viewing.<br />
170 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-12 Generate DDL for a database object<br />
3. Click Finish.<br />
4. Find the SQL DDL file you just created, right-click, and select Run on<br />
Database <strong>Server</strong>.<br />
Chapter 6. Accessing databases 171
Figure 6-13 Execute the DDL - step 1<br />
5. Click Next. The next screen will ask you to select the items you want to<br />
create. Make sure the statements are selected and click Next.<br />
Figure 6-14 Execute the DDL - step 2<br />
6. Select a commit option.<br />
172 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
6.2.5 DB output view<br />
Figure 6-15 Execute the DDL - step 3<br />
7. Click Next. Select the box to use an existing connection and select the<br />
connection to the SALESAPP database. For example, our connection was<br />
called OnlineCatalogConn (see Figure 6-4 on page 160).<br />
8. Click Finish to create the table in the database.<br />
9. Follow the same procedure to generate and execute the DDL for the rest of<br />
the tables.<br />
In the Data perspective, the DB Output view displays information about actions<br />
related to stored procedures and user-defined functions. For example, when you<br />
run a stored procedure on the database server, the DB Output view displays<br />
messages, parameters, and the results of any SQL statements that are executed<br />
by the stored procedure. In addition to output from explicit stored procedures and<br />
user-defined functions, the DB Output view displays results from sample<br />
contents of a selected table.<br />
The DB Output view includes an actions list on the left side of the view and<br />
several tabbed pages on the right side. The pages on the right side display<br />
information that is related to the action that is selected in the actions list:<br />
► A Messages page displays messages, including the progress of actions<br />
► A Parameters page displays the parameters involved with a certain routine<br />
► A Results page displays the results of SQL statements that are executed by a<br />
routine<br />
The left side of the DB Output view contains the following fields:<br />
► Status, which indicates the current state of the statement.<br />
► Action, which indicates what kind of action occurred.<br />
► Object Name, which contains the name of the statement.<br />
Chapter 6. Accessing databases 173
To access the DB Output view:<br />
1. Click Window > Open Perspective > Other to open the Select Perspective<br />
window.<br />
2. Select Data and then click OK to open the Data perspective.<br />
3. Click the DB Output tab on the Tasks view to display the DB Output view.<br />
Figure 6-16 DB output view<br />
To view the sample contents of a table, navigate to a table definition in the DB<br />
servers view, right-click the table definition and select Sample contents from the<br />
context menu. The table contents will be displayed in the DB output view as<br />
shown above.<br />
6.2.6 Creating Web pages to access the database<br />
The Database Web Pages wizard provides an easy way to quickly create a<br />
simple HTML form to solicit user input and JSP pages that show the database<br />
access results. This set of pages can then be modified or customized later. This<br />
saves a lot of initial repetitive work. In this section we will use the wizard to create<br />
Web pages that search the database for a record based on user input.<br />
There are two approaches to using this wizard.<br />
► You can create the pages and assume that you will use them as the basis for<br />
the real pages in the application. This implies that you will probably rename<br />
the pages created to a naming convention that suits your project, and that you<br />
will update the generated code to customize the look and feel for your<br />
application or to add additional functions.<br />
► Or you can create the pages in an out-of-the-way location, for example, a<br />
folder that is not in the Web Content directory structure. You can open these<br />
pages and copy/paste relevant code into pages that you create for the<br />
application. By placing the wizard-generated pages somewhere other than<br />
the Web Content directory, you can prevent them from being deployed to the<br />
174 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
server. One consideration to this is that the generated JSPs will be registered<br />
as servlets in the Web application deployment descriptor. The servlet page<br />
will contain initialization parameters important for connecting to the database.<br />
You should remove them and add the pages you create instead.<br />
In this example, we are assuming that we will use the pages as generated and<br />
will place them in a folder called Wishlist under Web Content.<br />
1. Switch to the Web perspective.<br />
2. In the Project Navigator view, find and highlight the location where you want to<br />
create the pages. This can be directly in the Web Content directory, or in an<br />
application-specific directory. In our example, we select the Web<br />
Content/wishlist folder under the OnlineCatalog project (note that this folder<br />
must already exist).<br />
3. Right-click, and select New -> Other -> Web -> Database Web Pages.<br />
4. Click Next to start the Database Web Pages wizard.<br />
Figure 6-17 Database Web Pages wizard: Panel 1<br />
Chapter 6. Accessing databases 175
Java package: During the wizard you will have a chance to create a front<br />
controller for the Web pages. The front controller is a servlet and therefore will<br />
be compiled into a class. The Java package determines where the class is<br />
stored. If you leave this blank, default package is used.<br />
SQL Statement Type: The SQL statement type determines the type of SQL<br />
statements that will be created.<br />
The choices are:<br />
– Select statement<br />
– Update statement<br />
– Insert statement<br />
– Delete statement<br />
In this case since we are querying the database, we choose Select<br />
statement.<br />
Model: The model options determine the type of pages that will be created.<br />
The options you can choose from depend on the SQL statement type you<br />
selected. You can see a description of the option you have selected in the<br />
Description area below the model field.<br />
Since we have specified Select Statement as our SQL statement type, we<br />
have the following model options:<br />
– <strong>IBM</strong> Database Access Tag Lib - Select Statement<br />
Using this choice, a select is done against the database for information,<br />
which is then displayed in table format to the user. There is no need to<br />
allow the user to select an item for further details. Database access is<br />
handled using the JSPSQL tag library.<br />
– <strong>IBM</strong> Database Access Tag Lib - Master Details Pattern<br />
This is similar to the previous pattern, except the database information is<br />
displayed in two-tiers. The first database select retrieves high-level<br />
information and displays the records in a table format. The user can then<br />
select an entry to get further details. This pattern also accesses the<br />
database using the JSPSQL tag library.<br />
– <strong>IBM</strong> Database Access JavaBeans - Master Details Pattern<br />
This is similar to the tag library master details pattern with the exception<br />
that it uses JavaBeans instead of tag libraries to access the database.<br />
While the tag library patterns fit more into the Model 1 category of design,<br />
the JavaBeans pattern is more of a Model 2 type of design. This gives the<br />
flexibility of manipulating the data before it is displayed in the JSP.<br />
In our example we select <strong>IBM</strong> Database Access Tag Lib - Master Details<br />
Pattern.<br />
176 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Files: The files box shows the pages that will be created based on the options<br />
you have selected. This in an informational box only. You can see from our<br />
selections that the wizard is going to create four pages: An input form allowing<br />
the user to enter search criteria, a JSP page to display the database entries<br />
that match the criteria, and a JSP page to display the details of a selected<br />
entry. Optionally, a front controller will be created.<br />
5. Click Next.<br />
6. If you have previously saved SQL statements, you will be given the option of<br />
selecting a saved SQL file for use in the wizard. Since this is the first time<br />
through and we do not have any saved statements we are taken directly to the<br />
panel shown in Figure 6-18. This page allows you to specify the database you<br />
want to use and the method of creating the SQL statement.<br />
Figure 6-18 Choose the database and SQL create method<br />
Chapter 6. Accessing databases 177
Note: You can use this same process to build an SQL statement without<br />
going through the Database Web Pages wizard. Just select the database<br />
folder, right-click, and select New -> Other -> Data -> SQL Statement.<br />
First select the Save SQL Statement option and enter a descriptive name for<br />
the saved statement. This way you can reuse the SQL statement you create if<br />
you need to do this again.<br />
Your options to create the SQL statement are:<br />
– Be guided through creating an SQL statement<br />
– Manually type an SQL statement<br />
In our example we will let the wizard guide us through the process of creating<br />
the SQL statement. For short statements or for those that you have stored in<br />
a file, you could choose to type in the statement (copy/paste will work).<br />
Finally, you can select a database model to work with. The options are:<br />
– Use existing database model. This implies that you have connected to the<br />
database and imported the design to your Web project (as we have in this<br />
example).<br />
– Connect to a database and import a new database model. This allows you<br />
to go through the connect and import process now.<br />
In our example, we will select the SALESAPP database that we imported to<br />
our project by browsing to the correct folder in the Web project.<br />
178 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-19 Find the imported database<br />
Click OK.<br />
7. Click Next to begin creating the SQL statement.<br />
8. Select the Table tab. Select the ITEM table in the Available Tables column.<br />
Click > to move it to the Selected Tables column.<br />
Chapter 6. Accessing databases 179
Figure 6-20 Select the tables<br />
9. Move to the Columns tab to choose the columns you want included in the<br />
select. You can include each column by selecting it in the Available Columns<br />
panel and clicking > to move it to the Selected Columns window. In this case,<br />
since we want all the columns, we move them all at once using the >> button.<br />
180 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-21 Select the columns<br />
10.We will skip the Join tab since all of our information is coming from just one<br />
table.<br />
11.Click the Conditions tab. The way we envision our search is that we will look<br />
for a match or partial match in the long description (ITEM_LONG_DESC<br />
column) based on criteria provided by the user.<br />
Chapter 6. Accessing databases 181
Figure 6-22 Database select condition<br />
The conditions for the search are built by selecting the appropriate values in<br />
each condition column:<br />
– Column: Click in the first field under Column and select<br />
ITEM_LONG_DESC in the drop-down list.<br />
– Operator: Select LIKE.<br />
– Value: Values are expressions that are used to define the query. They can<br />
be as simple as a constant or something more complex. You can type in a<br />
value directly or you can use the Expression Builder wizard to build it.<br />
In this case we are going to use the Expression Builder wizard to create a<br />
variable (signified with a colon (:) at the beginning) to hold the search<br />
criteria. The variable will be represented by an input field on an HTML form<br />
and will be filled in by user input.<br />
Select Build Expression. As you go through the wizard you will be asked<br />
for the expression type and name. In this sample we want to define a<br />
variable called item_desc.<br />
182 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The values we enter during the wizard are:<br />
Type of expression: Constant<br />
Type of constant expression: String constant<br />
String constant type: Host variable name<br />
Variable name: item_desc<br />
At the end of the wizard, click Finish and you will be returned to the<br />
Conditions tab to complete the selection conditions.<br />
– And/Or: Leave this blank since there is only one condition for the search.<br />
12.Click the Order tab. We want to list the items in order by using the price.<br />
Select Price and move it to the Selected Columns window. Ascending order<br />
will be the default but you can change this by clicking under the Sort Order<br />
column and selecting DESC (descending).<br />
Figure 6-23 Order the columns<br />
13.Click Next. The SQL Statement page now displays the generated SQL<br />
statement and gives you a chance to modify it.<br />
Chapter 6. Accessing databases 183
Figure 6-24 The generated SQL statement<br />
14.Click Parse to make sure the statement is syntactically correct.<br />
Note: Testing the SQL: In our sample, we have not populated the database<br />
with data, but if you are using a database that contains data you could test<br />
your SQL statement by doing the following:<br />
1. Click Execute. A new panel will appear.<br />
2. Click Execute on this panel.<br />
3. A window will pop up asking for a value for the host variable; for<br />
example, our search would require the user to enter a description to<br />
search on. We would enter something like ‘%Fleetwood%’ (including<br />
the single quotes). The case of the argument must match the case<br />
found in the database. The % signs allow you to search for any<br />
character String containing Fleetwood. The long description for each<br />
item would be searched for that character String and the results<br />
returned.<br />
In “Update the search argument” on page 193, we will show you how to<br />
modify the code generated by the wizard so that the user does not have to<br />
enter the % marks or be concerned about case to get a match.<br />
4. Click Next. On the Runtime connection page we determine the type of<br />
database connection code to generate. We have two choices. Using a data<br />
184 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
source connection has the advantage of connection pooling, so select Use<br />
data source connection. Enter the data source name, user ID, and<br />
password to use. The data source entry refers to the data source definition on<br />
the application server. This entry is created later in “Defining a data source<br />
connection to the server” on page 200. Specifically, this value matches the<br />
value for the JNDI name in Figure 6-40 on page 206.<br />
Figure 6-25 Using a data source connection<br />
5. Click Next. In the controller page you can make decisions that determine how<br />
the flow of control is handled.<br />
Chapter 6. Accessing databases 185
Figure 6-26 Defining the controller page<br />
Following is a brief explanation of each option available.<br />
– Style sheets: This is used to select one or more style sheets to be used in<br />
the generated Web pages. Each CSS file listed will be used.<br />
– Use error page: This option allows you to specify a page that the user is<br />
forwarded to when an error is encountered while executing one of the<br />
generated resources<br />
– Store results in request or session: Storing the results in a session will<br />
allow the data to be used in multiple pages for the duration of the session.<br />
Storing the results in a request will allow access to the data only for the<br />
duration of the request. The result set is destroyed after the request is<br />
processed, freeing up memory on the server.<br />
– Front controller: A front controller is a servlet that serves as the single<br />
entry point for all requests to a Web application region. Logically, it is<br />
positioned between the browser and the presentation layer, providing a<br />
single point to perform all authentication, logging, debugging, and so forth.<br />
186 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The controller is responsible for dispatching presentation pages based on<br />
request parameters and application state data.<br />
You can choose to automatically create a new controller, reuse an existing<br />
controller, or not use a controller at all. If you choose to not use a<br />
controller, that functional layer of processing is not performed and the JSP<br />
is called directly from the HTML page. In this example, we opt to not use<br />
the front controller.<br />
6. Click Next. The following series of pages lets you design the pages. This<br />
function is limited but gives you a starting point for future modifications. These<br />
changes override CSS Style settings and the new settings are placed in style<br />
tags in the corresponding pages. The first page shows you the input HTML<br />
page.<br />
– Host variables: Make sure the ITEM_LONG_DESC variable is selected.<br />
This is represented by the input field you see on the page. If you deselect<br />
this variable, the input field (and label) will be removed from the page on<br />
the right.<br />
– Page tab: In the lower left corner of the window you will see two tabs.<br />
Clicking the items on the Page tab allows you to change the background,<br />
title, and field colors.<br />
Change the page title from the default, Input Form to something more<br />
meaningful, like Search Catalog.<br />
– Fields tab: The fields tab lets you change the attributes of the variable<br />
selected in the Host Variables view.<br />
Change the label (the text shown to the left of the variable in the page) to<br />
Search For.<br />
Chapter 6. Accessing databases 187
Figure 6-27 Design the input form<br />
7. Click Next.<br />
This page lets you make minor changes to the first results page. This page<br />
will display a list of all the entries that result from the search in a table format.<br />
You can change column titles for the table, change the page title, colors used,<br />
and you can select the columns to display.<br />
Because we selected the master detail pattern earlier, the pages are built so<br />
that the user can select an item in the table to see the complete details. This<br />
means that you can be more selective in what you display on the initial results<br />
page.<br />
a. In our example, we are only going to display the item number, price, and<br />
the short description. Start modifying this page by de-selecting the other<br />
columns.<br />
b. Select the Item_Number column in the Result set columns window, and<br />
then select the Fields tab below. Change the value of the Label property<br />
to Item. This will change the heading for that column in the output table.<br />
188 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The key value is the link between master and detail views. The details<br />
page selects data from the database based on the key value passed to it.<br />
In this case we want to retrieve the details of the record based on the item<br />
number, so we change the key value to true.<br />
Change the column width to 5 to make sure the entire item number can be<br />
displayed.<br />
c. Repeat this for each selected column using the following values given in<br />
Table 6-5.<br />
d. Change the title of the page to Search Results using the Page tab.<br />
Table 6-5 Master view page fields<br />
Column Label Column width Key value<br />
ITEM_NUMBER Item 5 true<br />
ITEM_SHORT_DESC Description 15 false<br />
ITEM_PRICE Price 12 false<br />
Chapter 6. Accessing databases 189
Figure 6-28 Design the master view page<br />
8. Click Next. The next step is to design the details page. This page is used to<br />
display the details of an item selected from the first results page.<br />
a. The process is the same as with the previous pages. Deselect the<br />
SOTD_FLAG column. For the other columns change the Field properties<br />
to useful values. In our sample we used the information given in Table 6-6.<br />
Table 6-6 Details view page fields<br />
Column Label Size Max length<br />
ITEM_NUMBER Item 5 10<br />
ITEM_SHORT_DESC Description 15 20<br />
ITEM_LONG_DESC More Info 20 40<br />
QUANTITY Quantity 20 40<br />
PRICE Price 20 40<br />
190 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-29 Final details page<br />
b. Click the Page tab and change the value of the page title to Item Details.<br />
9. Click Next. In the Specify Prefix window, change the prefix to SearchItem. The<br />
prefix is used to build the page names.<br />
Chapter 6. Accessing databases 191
Figure 6-30 Renaming the Web pages<br />
10.Click Finish. Click Yes if asked to overwrite any files.<br />
At this point the following items are generated:<br />
► HTML input form: This form is used to input the search criteria. It then calls<br />
the Master view.<br />
► MasterView JSP: This JSP gets the search criteria from the input form and<br />
executes the SQL statement using the JSPSQL tag library and connection<br />
information we provided. The SQL statement used is the one we created<br />
using the wizard. This form provides a link to the DetailsView JSP.<br />
► DetailsView JSP: This JSP gets the search criteria from the MasterView JSP<br />
and executes an SQL statement to retrieve the details of the selected<br />
database record. This JSP is generated as a result of selecting a master<br />
details pattern (see Figure 6-17 on page 175).<br />
192 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The form and the JSPs are now ready to be run on a server, but before you do<br />
that you will need to do one more thing. You will need to give the server the<br />
information it needs to connect to the database.<br />
Update the search argument<br />
One thing we want to do is to update the condition on the SQL statement in<br />
SearchItemMasterView.jsp to make sure that if the search argument appears in<br />
the item’s long description that we get a match. Currently, we use the “Like”<br />
argument. As coded, we will only get a match if the user input matches the long<br />
description exactly.<br />
The current code looks like:<br />
<br />
<br />
<br />
SELECT<br />
DB2ADMIN.ITEM.ITEM_NUMBER,<br />
DB2ADMIN.ITEM.ITEM_SHORT_DESC,<br />
DB2ADMIN.ITEM.ITEM_LONG_DESC,<br />
DB2ADMIN.ITEM.QUANTITY,<br />
DB2ADMIN.ITEM.PRICE,<br />
DB2ADMIN.ITEM.SOTD_FLAG<br />
FROM<br />
DB2ADMIN.ITEM<br />
WHERE<br />
DB2ADMIN.ITEM.ITEM_LONG_DESC LIKE :item_desc<br />
ORDER BY<br />
PRICE ASC<br />
<br />
<br />
<br />
Update the code as marked below in bold print.<br />
<br />
<br />
<br />
SELECT<br />
DB2ADMIN.ITEM.ITEM_NUMBER,<br />
DB2ADMIN.ITEM.ITEM_SHORT_DESC,<br />
DB2ADMIN.ITEM.ITEM_LONG_DESC,<br />
DB2ADMIN.ITEM.QUANTITY,<br />
DB2ADMIN.ITEM.PRICE,<br />
DB2ADMIN.ITEM.SOTD_FLAG<br />
FROM<br />
DB2ADMIN.ITEM<br />
WHERE UPPER (DB2ADMIN.ITEM.ITEM_LONG_DESC ) LIKE :item_desc<br />
ORDER BY<br />
Chapter 6. Accessing databases 193
PRICE ASC<br />
<br />
<br />
<br />
This does two things. It sets the case for both the input and the database values<br />
to upper case so they are the same, and it adds a % character to the beginning<br />
and end of the input parameter. This changes the input from a specific character<br />
string to a pattern allowing any characters before and after the string to be<br />
ignored during the match.<br />
6.2.7 Database connections<br />
Let us take a look at the code generated by the wizard that implements the<br />
connection to the database. During the wizard you had a choice of using a data<br />
source connection or driver manager connection. We recommend that you use<br />
data source, but we will take a look at both.<br />
Data source connection<br />
Figure 6-1 shows the code generated for the master view page.<br />
Example 6-1 Data source connection code<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
194 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
SELECT DB2ADMIN.ITEM.ITEM_NUMBER, DB2ADMIN.ITEM.ITEM_SHORT_DESC,<br />
DB2ADMIN.ITEM.ITEM_LONG_DESC, DB2ADMIN.ITEM.QUANTITY, DB2ADMIN.ITEM.PRICE,<br />
DB2ADMIN.ITEM.SOTD_FLAG FROM DB2ADMIN.ITEM WHERE DB2ADMIN.ITEM.ITEM_LONG_DESC<br />
LIKE :item_desc ORDER BY PRICE ASC<br />
<br />
<br />
<br />
The JSPSQL tag library (dab:) is used to connect to and access the database.<br />
Tag libraries are discussed later in Chapter 9, “Using tag libraries” on page 275.<br />
You do not need to understand tag libraries yet to learn the concepts in this<br />
section.<br />
The thing to notice here is that the connection code uses three initialization<br />
parameters (user name, password, and dataSourceName) stored in the servlet<br />
entry in the Web deployment descriptor to make the connection. When the<br />
Database Web Pages wizard created the JSPs, it registered them as servlets in<br />
the Web deployment descriptor and created these initialization parameters to<br />
define the database connection parameters.<br />
Figure 6-31 Servlet initialization parameters<br />
Chapter 6. Accessing databases 195
In order to run the application using the data source connection, one more step<br />
needs to be taken. The application server configuration will need to be updated<br />
so that it has the information it needs to access the database. In the case of a<br />
data source connection, this basically consists of defining a JDBC provider (that<br />
is, the JDBC driver class to be used to access the database) and creating a data<br />
source definition (thereby updating the JNDI namespaces) with information on<br />
how to access the database. We will show you how to do this in 6.2.9, “Testing”<br />
on page 200.<br />
Note: In this situation, the password used to access the database is stored<br />
unencrypted. An alternative to storing the user ID and password as servlet<br />
initialization parameters is to store them as JAAS authentication alias entries<br />
(where the password is encrypted). The wizard does not give this option, but<br />
you can easily update the code and create the definitions required for this. For<br />
information on this method, see 16.5, “JAAS security” on page 570.<br />
Driver manager connection<br />
The driver manager connection is defined in much the same way as the data<br />
source connection. Example 6-2 shows the code.<br />
Example 6-2 Driver manager connection code<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
SELECT DB2ADMIN.ITEM.ITEM_NUMBER, DB2ADMIN.ITEM.ITEM_SHORT_DESC,<br />
DB2ADMIN.ITEM.ITEM_LONG_DESC, DB2ADMIN.ITEM.QUANTITY, DB2ADMIN.ITEM.PRICE,<br />
DB2ADMIN.ITEM.SOTD_FLAG FROM DB2ADMIN.ITEM WHERE DB2ADMIN.ITEM.ITEM_LONG_DESC<br />
LIKE :item_desc ORDER BY PRICE ASC<br />
<br />
<br />
<br />
196 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
This connection also uses servlet initialization parameters, though they are<br />
slightly different from the data source connection. Figure 6-32 shows the servlet<br />
initialization parameters for a driver manager connection.<br />
Figure 6-32 Servlet initialization parameters<br />
Note: The servlet initialization parameters used for a driver manager<br />
connection include the JDBC driver class name. You will need to make sure<br />
that the server has access to this driver at runtime by adding the JAR file<br />
containing the driver to the server class path. This is done in the server<br />
configuration (Paths tab). Use the Add External JARS option. Drivers (other<br />
than Cloudscape) are provided by the database product. <strong>Server</strong> configuration<br />
is covered in 13.6, “Working with server configurations” on page 483.<br />
6.2.8 Defining a resource reference for the data source (optional)<br />
Resource references can be defined for many types of objects. In <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express, this will most likely be a data source. The resource<br />
reference defines things such as:<br />
Chapter 6. Accessing databases 197
► How credentials are passed to the data source (resource authorization)<br />
► Transaction isolation level<br />
► Shareability of connections<br />
If you don’t create a resource reference, defaults will be used. In <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express, the defaults are usually sufficient, making this step<br />
optional.<br />
To create a resource reference for a data source:<br />
1. Open the Web deployment descriptor (web.xml) and select the References<br />
tab.<br />
2. Select Resource at the top of the page.<br />
3. Click Add at the bottom of the Resource References window.<br />
4. When the NewResourceRef entry appears, type over it with an administrative<br />
name for the resource reference. In this case, we will use the name of the<br />
data source, jdbc/SALESAPP.<br />
5. Click Browse beside the Type in the Details window and type datasource in<br />
the Choose a type box. At the bottom select the javax.sql entry. Click OK.<br />
Figure 6-33 Type Selection panel<br />
6. In the Details window, select <strong>Application</strong> for the authentication type and<br />
Shareable for the sharing type.<br />
198 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
7. Enter the JNDI name in the <strong>WebSphere</strong> Bindings section. This must match<br />
the JNDI name used by the application.<br />
8. Leave the rest as they default and save the configuration.<br />
Figure 6-34 Resource reference for JDBC binding<br />
The source will look like Figure 6-3.<br />
Example 6-3 web.xml resource reference definition<br />
<br />
jdbc/SALESAPP<br />
javax.sql.DataSource<br />
<strong>Application</strong><br />
Shareable<br />
<br />
When the application is installed into a production server using the administrative<br />
console, the administrator will map the resource reference to an existing data<br />
source definition. In the Express test environment, a data source definition must<br />
exist in the server configuration with the same JNDI name.<br />
Chapter 6. Accessing databases 199
6.2.9 Testing<br />
We have not looked at deploying applications yet, but we will take you through<br />
the steps necessary to test the pages you just created in the Studio Site<br />
Developer test environment. This process assumes that you have not created<br />
any servers.<br />
For more explanation on creating servers and deploying applications see<br />
Chapter 13, “Deploying applications” on page 455.<br />
1. Use the instructions in 13.4.1, “Creating a server and server configuration” on<br />
page 466 to create an Express <strong>Application</strong> <strong>Server</strong> test environment.<br />
2. Use the instructions in “Defining a data source connection to the server” on<br />
page 200 to define the data source to the test server.<br />
Note: This step is not necessary if you are using the driver manager<br />
connection.<br />
3. Use the instructions in 13.4.2, “Publishing an application to the test<br />
environment” on page 468 to add the enterprise application to the server. In<br />
this example, we have been building the Online Catalog application. It is a<br />
part of the OnlineCatalogEar enterprise application.<br />
4. Use the instructions in 13.4.4, “Starting the test environment server” on<br />
page 471 to start the test server.<br />
5. Use the instructions in 13.4.5, “Running the application” on page 472 to test<br />
the Web pages. In this case, you will select SearchItemInputForm.html.<br />
Defining a data source connection to the server<br />
When you use a data source connection to a database, the data source<br />
information must be defined to the server. In this case, we need to define the<br />
data source for the SALESAPP database.<br />
1. Open the <strong>Server</strong> Configuration view in the Web perspective.<br />
2. Double-click the test server to open the configuration. Switch to the Data<br />
source tab.<br />
3. The first step is to add a JDBC provider to the configuration. This tells the<br />
server which JDBC driver class to use to access the database. Open the<br />
<strong>Server</strong> settings section and take a look at what is already defined under the<br />
<strong>Server</strong> settings section. The Cloudscape driver and data source information is<br />
predefined to support the sample applications shipped with <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express.<br />
200 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: Since this is a single-server environment (one node and one server),<br />
you can put all your JDBC provider and data source definitions in the<br />
<strong>Server</strong> settings.<br />
Figure 6-35 Data sources tab<br />
4. Click Add beside the JDBC provider list (the top box).<br />
5. Select <strong>IBM</strong> DB2 in upper window and DB2 JDBC Provider in lower window.<br />
Chapter 6. Accessing databases 201
Figure 6-36 Select database and driver<br />
6. Click Next and enter the information shown in Figure 6-37 on page 203. The<br />
name and description can be anything. The implementation class name and<br />
class path you see are the default for the DB2 JDBC provider. The driver<br />
specified in the class name must be available in the class path specified. Note<br />
that in this case, the class path uses a variable. You will see how to ensure<br />
that this variable is set correctly a little later.<br />
Note that we left the Native path entry empty. This is only required if the JBDC<br />
provider chosen uses non-Java (native) libraries.<br />
202 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-37 JDBC Driver information<br />
Important: By default, the db2java.zip file does not support the JDBC 2.0<br />
specification. You need to open the sqllib\java12 folder and execute<br />
usejdbc2.bat to copy the correct drivers to the zip file.<br />
7. Click Finish. The Data sources configuration page now looks like that shown<br />
in Figure 6-38 on page 204. Note that the entries in the lower boxes have<br />
disappeared. This is because they are not relevant to the selected JDBC<br />
driver. Since we just added the DB2 driver, it is selected and there are no data<br />
source or resource properties defined for it yet.<br />
Chapter 6. Accessing databases 203
Figure 6-38 Finished JDBC<br />
8. With the <strong>IBM</strong> DB2 driver selected in the JDBC provider list, click the Add<br />
button next to the data source section.<br />
9. Select DB2 JDBC Provider and Version 5.0 data source.<br />
204 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-39 Creating a data source<br />
Click Next.<br />
Note: If this is a J2EE 1.2 Web project, you must select Version 4.0 data<br />
source. If this is a J2EE 1.3 Web project, you must select Version 5.0 data<br />
source.<br />
10.Enter the information shown in Figure 6-40 on page 206.<br />
Chapter 6. Accessing databases 205
Figure 6-40 Data source information<br />
The JNDI name must match the name that you use in the application code. If<br />
you used the Database Web Pages wizard to create the application pages,<br />
this name is specified during the wizard (see Figure 6-25 on page 185) and is<br />
stored as the dataSourceName initialization parameter for the servlet in the<br />
Web deployment descriptor.<br />
206 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: The JNDI name is case sensitive, so make sure you match what is<br />
specified in the code. If you have a connection problem, the messages on<br />
the server console will give you enough information to correct the problem.<br />
The option at the bottom to use the data source in container-managed<br />
persistence (CMP) is not relevant for <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express since it does not support an EJB environment. Selecting this has no<br />
effect.<br />
Note: In 6.2.7, “Database connections” on page 194, you saw that the<br />
Database Web Pages wizard generated connection code that specified a<br />
user ID and password retrieved from the servlet initiation parameters to<br />
authenticate to the database.<br />
An alternative to this is to define the database connection user ID and<br />
password in a JAAS authentication entry in the server configuration (under<br />
the Security tab) and then specify this entry in the Component-managed<br />
authentication alias field in the data source. See 16.5, “JAAS security” on<br />
page 570, for an example.<br />
11.Click Next. In the next window select the databaseName property. In the<br />
value field, enter SALESAPP.<br />
Chapter 6. Accessing databases 207
Figure 6-41 JDBC connection parameters<br />
12.Click Finish.<br />
The Data sources page should now look like Figure 6-42 on page 209.<br />
208 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 6-42 Data sources page after configuration<br />
13.You used a variable to define the path to the JDBC driver (see Figure 6-37 on<br />
page 203), so you need to switch over to the Variables tab and define the<br />
variable. The variable, DB2_JDBC_DRIVER_PATH, is predefined in the node<br />
settings for you, but the value is empty.<br />
Chapter 6. Accessing databases 209
Figure 6-43 <strong>Server</strong> variables page<br />
14.Find the variable in the list and click Edit.<br />
15.Enter the location of the DB2 driver. In this case, this is relative to the Studio<br />
Site Developer system because we are using the test environment. If we were<br />
working with a remote server, this would need to be the path the server uses<br />
to locate the driver.<br />
Figure 6-44 Setting the variable value<br />
16.Click OK to close the window.<br />
17.Close the configuration.<br />
210 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
18.Start (or restart) the server.<br />
Note: If you do not define a resource reference in the Web deployment<br />
descriptor, you may see message J2CA0122I on the server console when you<br />
access the database, indicating that default values are being used for the<br />
resource references. This does not affect execution but can be avoided by<br />
defining the resource reference using the procedure outlined in 6.2.8,<br />
“Defining a resource reference for the data source (optional)” on page 197.<br />
Oracle users<br />
The process for Oracle is similar to DB2. For example, to create a data source<br />
using the Oracle thin driver:<br />
1. Create a JDBC driver:<br />
a. Database type = Oracle<br />
b. JDBC Provider = Oracle Thin<br />
c. Implementation class name =<br />
oracle.jdbc.pool.OracleConnectionPoolDataSource<br />
d. Class path = ${ORACLE_JDBC_DRIVER_PATH}/classes12.zip<br />
2. Create a data source:<br />
a. JDBC Provider = Oracle JDBC Thin Driver<br />
b. Data source type = Version 5.0<br />
c. Name = database_name<br />
d. JNDI Name = jdbc/database_name<br />
e. Data source helper class name =<br />
com.ibm.websphere.rsadapter.OracleDataStoreHelper<br />
f. databaseName property = database_name<br />
g. URL = jdbc:oracle:thin:server_name:1521:database_name<br />
3. Update the ORACLE_JDBC_DRIVER_PATH variable, for example,<br />
c:\oracle\ora81\jdbc\lib\.<br />
6.2.10 Building SQL statements using the SQL Query Builder<br />
We have seen how you can create SQL statements during the Database Web<br />
Pages wizard. But there are going to be times when you want to create SQL<br />
statements outside of the wizard or to work with statements you have created<br />
and saved. This is where the SQL Query Builder comes in handy.<br />
1. Make sure you have created a connection to the database and imported the<br />
design to your project.<br />
2. In the Data Definition view, find the Web<br />
Content/WEB-INF/databases/database_name/Statements folder under your<br />
project. Right-click the Statements folder, select New, then select the type of<br />
Chapter 6. Accessing databases 211
SQL statement you want to build from the context menu. In this case we want<br />
to create a select statement.<br />
3. In the wizard, enter a descriptive name for the statement. For example,<br />
SelectAllItems. You can save and reuse SQL statements you build so give it a<br />
name that will identify its purpose. Click OK.<br />
4. The SQL Query Builder will open. The new statement is initialized with a<br />
Select * statement.<br />
Figure 6-45 SQL Query Builder<br />
5. The first step is to choose a table to select from. You can do this in several<br />
ways, depending on your preference:<br />
– You can drag and drop the table from the Data Definition view into the SQL<br />
Source view.<br />
– You can open the context menu from the query in the Outline view and<br />
select Add Table.<br />
– You can use the context menu in the Tables view.<br />
We prefer the drag-and-drop method, so we locate the DB2ADMIN.ITEM<br />
entry in the database design and drag it to the SQL Source window.<br />
212 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
6. To add particular columns to the SQL query, select the columns in the Item<br />
table in the Tables view.<br />
Figure 6-46 Create a query statement<br />
As you select the columns, you will see the SQL being created in the SQL<br />
Source view.<br />
7. Use the Statement view at the bottom to add conditions, change the sort<br />
order, etc.<br />
8. Close and save the new statement.<br />
Tip: Saved SQL statements can be tested by selecting Execute from their<br />
context menu. Make sure that you are connected to the database.<br />
Chapter 6. Accessing databases 213
214 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 7. Working with servlets<br />
Servlets are server-side Java classes that are deployed, managed, and executed<br />
on a J2EE-compliant server. Servlets are invoked from a URL and the output can<br />
be dynamically generated HTML, XML, or text. <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express supports the Java Servlet 2.3 specification. This specification can be<br />
found at:<br />
http://java.sun.com/products/servlet/<br />
7<br />
If you are not familiar with servlets, this chapter will introduce you to the<br />
necessary concepts. These concepts are also important in understanding Java<br />
<strong>Server</strong> Pages (JSPs). If you are familiar with servlets, read on to find out how to<br />
build servlets with Studio Site Developer. The following topics are discussed in<br />
this chapter:<br />
► Servlet overview<br />
► Studio Site Developer and servlets<br />
► Using servlets in the Online Catalog sample<br />
Important: This chapter only outlines and illustrates <strong>WebSphere</strong> Studio Site<br />
Developer support for servlets. If you would like information on Java support,<br />
please see the <strong>WebSphere</strong> Studio <strong>Application</strong> Developer Version 5<br />
Programming Guide (SG24-6957) redbook.<br />
© Copyright <strong>IBM</strong> Corp. 2003 215
7.1 Servlet overview<br />
The servlet mechanism is based on the request/response paradigm, shown in<br />
Figure 7-1.<br />
Client<br />
Figure 7-1 Request/response flow for a servlet call<br />
A client makes an HTTP request to a Web server. This Web server manages that<br />
request and sends it to a servlet container within an application server. The<br />
servlet container calls the servlet, passing objects representing the request and<br />
the response to it. The servlet then uses the request object to get the information<br />
submitted by the user and executes its business logic, generating a response to<br />
be sent back to the client.<br />
Typically, there is only one instance of a servlet class loaded in the servlet<br />
container at any time. Clients of the same application asking for the servlet will all<br />
deal with the same instance of the object, unless the servlet was reloaded<br />
previously.<br />
Servlets are protocol-independent. They are mainly used with the HTTP protocol,<br />
but their functionalities can be extended to other protocols. A servlet’s output can<br />
be XML content or any other type. However, we will focus on servlets dealing with<br />
Web clients in our examples.<br />
7.1.1 A servlet’s life cycle<br />
request<br />
response<br />
Web<br />
<strong>Server</strong><br />
Note: The terms servlet container and Web container are used<br />
interchangeably in this publication. Both containers serve the same purpose,<br />
in that they provide the support classes and context for servlets and JSPs.<br />
Web containers, however, also provide an environment to deploy and run Web<br />
applications.<br />
A servlet’s life cycle is defined in the Java Servlet specification. The different<br />
states of a servlet are shown in Figure 7-2 on page 217.<br />
216 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
request<br />
response<br />
<strong>Application</strong> <strong>Server</strong><br />
Servlet Container<br />
Servlet
Initial state<br />
Figure 7-2 A servlet’s life cycle<br />
Loading<br />
Initialization<br />
Service<br />
handling<br />
Destruction<br />
Final state<br />
All along its life, a servlet interacts closely with its container. Following the J2EE<br />
specification, the container is in charge of providing a runtime execution for the<br />
components. It is also responsible for handling a set of services such as<br />
concurrency, administration, and security.<br />
The servlet container is implied in all the steps through the servlet’s life cycle:<br />
1. Loading: The servlet container uses a classloader to locate the class file of<br />
the servlet and to instantiate it. This operation follows the Java class loading<br />
process. An instance of the servlet class (and only one) is then available at<br />
the end of this step.<br />
2. Initialization: The container activates the servlet by calling one of its<br />
methods, the init() method. The init() method must be implemented by a<br />
servlet class. This method is called once by the container and is used to<br />
initialize a set of parameters for the servlet instance. The servlet is then ready<br />
to handle requests from clients.<br />
3. Service handling: Each client request generates a call to the service() method<br />
of the servlet class. This method can either generate the response and<br />
transfer it to the Web server (via the servlet container) or dispatch the request<br />
to another component within the container.<br />
Chapter 7. Working with servlets 217
The service() method is called with two parameters:<br />
– Request: This object encapsulates all the data coming from the client and<br />
must implement the ServletRequest interface (the HttpServletRequest<br />
interface for Web clients).<br />
– Response: This object encapsulates all the data that must be sent back to<br />
the client. It implements the ServletResponse interface (the<br />
HttpServletResponse interface for Web clients).<br />
Multiple threads may be running the service handling (that is to say the<br />
service method) at the same time unless the servlet class implements the<br />
SingleThreadModel interface. It could be useful to manage persistency, and in<br />
that case the container may use multiple instances of the same servlet class.<br />
4. Destruction: The servlet container calls the destroy() method of the servlet to<br />
shut down the servlet. The method can be used to release resources. Any<br />
request to the servlet then cannot be handled.<br />
Many vendors provide an implementation of the servlet container in their<br />
application server. In Express <strong>Application</strong> <strong>Server</strong>, the servlet container is called<br />
the Web container.<br />
7.1.2 The servlet’s environment<br />
In this section, we discuss the environment surrounding the servlet.<br />
The servlet container<br />
The servlet container acts as a fundamental layer between the Web server and<br />
the servlets. It interacts with the Web server from which it receives requests. The<br />
container then creates an object implementing the HttpServletRequest interface<br />
and delegates the request to the servlet instance. The servlet instance executes<br />
its business logic (through a service method call). The container then transmits<br />
the response to the Web server.<br />
For each request on the same servlet instance, the container is responsible for<br />
creating and managing a new thread to serve the request.<br />
The servlet container provides the same services regardless of the platform it is<br />
operating on. This allows the servlet developer to focus on the logic of the<br />
component, without considering deployment issues. A servlet container must at<br />
least support the HTTP 1.0 protocol. To provide its services, a servlet container<br />
interacts with other Java objects, such as the servlet configuration and the servlet<br />
context objects.<br />
218 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The servlet configuration<br />
This object must implement the ServletConfig interface and is provided by the<br />
servlet container as a parameter of the init method of the servlet. The servlet<br />
container is responsible for providing a ServletConfig object.<br />
The servlet container uses this object to pass configuration information to its<br />
servlet instances, such as the name and the value of a parameter located in the<br />
servlet container. The ServletConfig object is accessible to the servlet through its<br />
getServletConfig() method. Moreover, a ServletConfig object allows the access<br />
to a ServletContext object.<br />
The servlet context<br />
This object implements the ServletContext interface and is provided to the servlet<br />
within the ServletConfig object. During its life cycle, a servlet can access its<br />
servlet context through the getServletContext() method.<br />
The servlet container is also responsible for providing an implementation of this<br />
interface.<br />
The servlet context provides information about its environment to a servlet. It can<br />
be shared by a group of servlets and provides access to the following:<br />
► A set of attributes: a set of name/object pairs that can be shared between<br />
servlets and other components to maintain persistency. A servlet can either<br />
add or remove an attribute or simply change its content. A servlet can also<br />
access its init parameters, which are name/value pairs.<br />
► Resources: servlets sharing the same context can also share resources such<br />
as files. They can access these resources via their servlet context.<br />
► A log file: a servlet can write a set of events to a log file.<br />
► A request dispatcher: this object, created and managed by the servlet<br />
container, allows a servlet to forward its request to another servlet or to<br />
include the content of another servlet into its own response. It allows servlets<br />
sharing the same context to communicate with each other.<br />
There can be several servlet context objects in a servlet container at the same<br />
time, each managing its pool of servlets. Each servlet instance is running in one<br />
of these contexts and all the servlet instances running in the same context will<br />
share the same resources. Following that, a servlet class may have more than<br />
one instance in a container, with each of these instances attached to a different<br />
servlet context.<br />
Finally, the servlet context is the way for the servlet to interact with its<br />
environment (its container, but also other resources) without having to reconsider<br />
its own logic. Every servlet container has at least a default servlet context.<br />
Chapter 7. Working with servlets 219
7.1.3 Servlets in an enterprise application<br />
An enterprise application contains many components. It is important to specify<br />
the role of each of the components to understand how to use them in an<br />
application. Earlier, in 2.3, “Determine the application-flow architecture” on<br />
page 26, we discussed the architecture models for application design.<br />
Depending on the architecture you choose, it is important to understand the roles<br />
that servlets should play.<br />
The role of servlets in a Model 1 architecture<br />
You will generally see Model 1 architecture used in the more simple,<br />
straightforward applications. The bulk of the application is consumed with<br />
presenting data to the user. JSPs are well suited for this and simpler to use than<br />
servlets, so it follows that you will see more JSP use in a Model 1 type application<br />
than you will servlets. There may be situations when servlets are more<br />
appropriate due to the complexity of a task but you will probably not make<br />
extensive use of servlets in a Model 1 application.<br />
Of course, you have to remember that eventually a JSP becomes a servlet at<br />
execution time.<br />
The role of servlets in a Model 2 architecture<br />
If you remember back to the discussion of Model 2 architecture, the application<br />
components were divided into three categories: Model, view, and controller.<br />
Servlets in the controller layer<br />
The role of a servlet is to handle a request from a client and to generate the<br />
output. To do these tasks, a servlet will communicate with other components<br />
such as EJBs for the business logic and JSPs for the presentation of the output.<br />
Servlets are the link between the client request and the model. They must<br />
interface with the components performing the business logic of the application.<br />
Typically, a servlet will have to transform a client request in an object that is<br />
understandable for the model. It also determines which components are required<br />
to perform the request and call these components.<br />
Once the business logic is performed, the servlet will have to interface with the<br />
presentation layer, providing an object used to generate the output. So the<br />
servlet also manages the link between the model and the presentation and may<br />
decide to delegate the output to an HTML page.<br />
220 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The first role of a servlet is to act as a controller. A servlet is responsible for<br />
taking parameters from the client. It then gives these parameters to the<br />
appropriate components that handle the business logic. Finally, the servlet takes<br />
the results back and uses them to give a response to the user. The servlet can<br />
either return an HTML page to the user or forward the presentation task to a JSP.<br />
7.2 Studio Site Developer and servlets<br />
7.2.1 Wizards<br />
Studio Site Developer provides the necessary tools to build servlets, including:<br />
► Wizards<br />
► Web perspective<br />
► Deployment descriptor editor<br />
Studio Site Developer provides wizards that aid in the development of servlets.<br />
One is a Servlet wizard and the other is a Package wizard. The Package wizard<br />
is not required to create a servlet since the servlet wizard will place the servlet in<br />
the default package. If you would like to create your own package for<br />
organizational purposes, use the Package wizard.<br />
Package wizard<br />
To create new Java packages in the Package Explorer:<br />
1. Navigate to the JavaSource folder in your project.<br />
2. Right-click the JavaSource folder and select New > Other from the context<br />
menu.<br />
3. From the New dialog, select Java from the left pane and then select Package<br />
from the right pane.<br />
4. Click Next.<br />
5. Edit the Source Folder field to indicate in which container you want the new<br />
package to reside. You can either type a path or click Browse to find the<br />
container. If a folder was selected when you chose to create the new<br />
package, that folder appears in the Source Folder field as the container for the<br />
new package.<br />
6. In the Name field, type a name for the new package.<br />
Chapter 7. Working with servlets 221
Figure 7-3 Package wizard<br />
7. Click Finish to create the package.<br />
Servlet wizard<br />
The Servlet wizard takes you step-by-step through the process of creating a Java<br />
servlet and provides you with output files you can use or modify for your Web<br />
application.<br />
Note: See 7.3, “Using servlets in the Online Catalog sample” on page 232 for<br />
an example of a servlet being created.<br />
To create a servlet, do the following:<br />
1. To launch the Servlet wizard, from the Web perspective select File > New ><br />
Servlet.<br />
2. In the Create a new Servlet page, supply the following information.<br />
– Specify the folder where the servlet class will be placed, the package that<br />
the class will belong to (it is added into a default package if you do not<br />
specify one), and a name for the servlet.<br />
222 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: Specifying a value in the Java package field of the servlet wizard<br />
will automatically create and add the servlet to the package.<br />
– The Class Name value should be the class name of the servlet.<br />
Note: The servlet should be placed in a package in the JavaSource<br />
folder of your project.<br />
– Specify a superclass for the servlet class. A servlet created by this wizard<br />
can have HttpServlet, or any class that has HttpServlet in its hierarchy, as<br />
its superclass. Click Browse to choose from the available superclasses.<br />
3. Click Next.<br />
4. Select a modifier to specify whether your servlet class is public, abstract, or<br />
final (classes cannot be both abstract and final).<br />
5. Specify whether the servlet you create implements the SingleThreadModel<br />
interface by selecting the Use Single Thread Model option. This guarantees<br />
that there will not be simultaneous access to the same servlet instance, which<br />
has a tendency to stabilize thread execution ordering.<br />
6. The javax.servlet.Servlet is provided as the default Interface. You can also<br />
add additional interfaces to implement. Click Add... to open the Interface<br />
Selection dialog. In this dialog, as you type the name of the interface that you<br />
are interested in adding in the Choose interfaces field, the list of available<br />
interfaces listed in the Matching types list box updates dynamically to display<br />
only the interfaces that match the pattern. Choose an interface to see the<br />
Qualifier and click Add. Click OK when you are finished.<br />
7. Select any appropriate method stubs to be created in the servlet file. The<br />
stubs created by selecting the Inherited abstract methods option must be<br />
implemented if you do not intend to create an abstract servlet. This is not true<br />
for Constructors from superclass.<br />
8. Click Next.<br />
9. If you select the Add to web.xml check box, the servlet, along with its display<br />
name, and any URL mappings and initialization parameters associated with<br />
the servlet, will be automatically included in the Web project web.xml file.<br />
Note that the Class Name value provided in the first page of the wizard is<br />
automatically mapped on this page. The mapping is updated if you change<br />
the value in the Servlet Name field.<br />
10.Click Finish.<br />
Chapter 7. Working with servlets 223
7.2.2 Web perspective<br />
The Web perspective is the main perspective used for editing the source of<br />
servlets. If you double-click a servlet from the Project Navigator view, the servlet<br />
will be opened in the Java editor. While editing the source of the servlet in the<br />
Java editor, the Outline view can be used to view the structure of the servlet.<br />
Java editor<br />
The Java editor is used to edit the source code of your servlet. It is similar in<br />
nature to Page designer.<br />
Java editor<br />
Figure 7-4 Java editor<br />
The Java editor also provides specialized features for editing Java code. The<br />
editor includes the following features:<br />
► Syntax highlighting<br />
► Content assist<br />
► Code formatting<br />
► Quick Fix<br />
224 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Syntax highlighting<br />
Within the Java source, the different elements of the source are shown with<br />
different colors. Examples of Java source elements that are rendered differently<br />
are:<br />
► Regular comments<br />
► Javadoc comments<br />
► Keywords<br />
► Strings.<br />
Strings<br />
Figure 7-5 Syntax highlighting<br />
Keywords<br />
Comments<br />
Content assist tool<br />
Content assist you with the coding process for your servlets. Pop-up windows are<br />
provided and suggest possible text choices to complete a phrase. You can select<br />
these choices for insertion in the text.<br />
Chapter 7. Working with servlets 225
Figure 7-6 Content assist<br />
Content assist<br />
Code formatting<br />
The Java editor supports the formatting of Java code according to your personal<br />
preferences.<br />
1. From the workbench menu bar, select Window -> Preferences. The<br />
Workbench Preferences page opens.<br />
2. In the left pane, expand the Java category and select Code Formatter. The<br />
Code Formatter Preferences page opens.<br />
226 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 7-7 Code formatter<br />
3. In the New Lines, Line Splitting, and Style tabs, select the code formatting<br />
conventions that you want the formatter to follow.<br />
4. Note that at the bottom of the page, you can observe an example effect of<br />
each individual code formatting option and see a preview of what your<br />
formatted code will look like.<br />
5. Click OK when you are done.<br />
Quick Fix<br />
The Java editor offers corrections to problems found while typing and after<br />
compiling. To show that correction proposals are available for a problem or<br />
warning, a “light bulb” is visible on the editor's annotation bar.<br />
Left-clicking the light bulb or invoking Ctrl+1 (Edit / Quick Fix) brings up the<br />
proposals for the problem at the cursor position. To select one of the proposals,<br />
double-click it from the pop-up window and it will be inserted into your source<br />
code.<br />
Chapter 7. Working with servlets 227
Figure 7-8 Quick Fix<br />
Outline view<br />
Associated with the Java editor is the Java-specific Outline view, which shows the<br />
structure of the active Java compilation unit (for example, the servlet). It is<br />
updated as the user edits the compilation unit.<br />
Figure 7-9 Outline view<br />
Clicking the different elements of the structure will position your cursor in the<br />
Java editor to the element location in the compilation unit. This can be very useful<br />
if your compilation unit contains many elements and you wish to navigate to a<br />
specific one.<br />
228 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Quick Fix
7.2.3 Deployment descriptor editor<br />
The Servlets page in the Web deployment descriptor editor lets you add an<br />
existing servlet or JSP file to the deployment descriptor or remove the selected<br />
servlet of JSP file from the deployment descriptor.<br />
To work with the Servlets page of the Web deployment descriptor editor:<br />
1. Open a Web project in the Project Navigator.<br />
2. Double-click the Web project's Web Deployment Descriptor file in the Project<br />
Navigator. The Web deployment descriptor editor opens.<br />
3. Click the Servlets tab to open the Servlets page.<br />
Figure 7-10 Servlets page<br />
4. You can edit settings in the following sections of the Servlets page:<br />
– Servlets and JSPs - list servlets and JSPs used in this application. You<br />
can add, edit or remove servlets and JSPs from the list.<br />
– Details - lists details about the selected servlet or JSP. Details listed<br />
include the servlet class, the display name, and a description.<br />
Chapter 7. Working with servlets 229
Figure 7-11 Details<br />
– URL Mappings - lists URLs mapped to the selected servlet.<br />
When using the Servlet wizard, the servlet will automatically be<br />
mapped if the add to web.xml feature was selected.<br />
URL mappings are used to provide an alias for a servlet or JSP. This<br />
allows the developer to avoid hard-coding the exact path of a resource<br />
in other resources. If the location of a resource changes, the developer<br />
only needs to modify the URL mapping.<br />
Figure 7-12 URL mappings<br />
– Initialization - lists the initialization parameters that are configured for the<br />
selected servlet or JSP file. Initialization parameters could include the user<br />
ID, password, URL, and driver properties for a database connection.<br />
Figure 7-13 Initialization<br />
230 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
– Security role references - list the security roles referenced in the Web<br />
application and lets you edit the security roles that are authorized to<br />
access the servlet. You can add, remove, or edit security roles. If you add<br />
a security role reference, you specify the role name, role link, and a<br />
description. See 16.4, “Securing applications with role-based security” on<br />
page 556 for additional information.<br />
Figure 7-14 Security role references<br />
– Run as - lists details of the selected servlet's run-as element. See 16.4,<br />
“Securing applications with role-based security” on page 556 for additional<br />
information.<br />
Figure 7-15 Run as<br />
– Icons - lets you view or change icons (small or large) used to represent the<br />
selected servlet or JSP file.<br />
Figure 7-16 Icons<br />
– <strong>WebSphere</strong> Extensions - list and lets you change the details of the Servlet<br />
Extension for the selected servlet. You can add a new extension by<br />
clicking Add. The Add Markup Language entry wizard appears.<br />
Chapter 7. Working with servlets 231
Figure 7-17 <strong>WebSphere</strong> extensions<br />
7.3 Using servlets in the Online Catalog sample<br />
To illustrate the creation of a servlet using Studio Site Developer we will start the<br />
process of creating an administration login function for our site using servlets.<br />
The entire process of the login function will not be illustrated here.<br />
Important: If you are downloading the Online Catalog sample from the<br />
additional material section of the Redbook site, it will not have the servlet login<br />
process linked up. The servlet in this example (along with other servlets) will<br />
be located in the common package. Any JSPs or HTML pages associated with<br />
the example will be located in the servlet_login folder in the WebContent<br />
directory.<br />
The login function in the sample will use a JSP to verify that the username and<br />
password submitted are valid by referencing a table in the SALESAPP<br />
database.<br />
The first step in the login process is login.html. This page collects the user name<br />
and password from the user and passes control to LoginServlet. LoginServlet<br />
captures the user name and password from the login.html form, verifies them<br />
using additional database connection wizards, and then forwards the user to the<br />
site administration selection page; admin.html.<br />
232 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 7-18 Servlet login process<br />
7.3.1 Creating a servlet<br />
USER table of SALESAPP<br />
Database connection servlets<br />
login.html LoginServlet.java admin.html<br />
Note: The servlet login function included with the Online Catalog sample uses<br />
four servlets, one HTML file, and two properties files. The four servlets<br />
(LoginServlet, LogWriter, DBConnection, and DBDriver) can be located in the<br />
common package under the JavaSource folder. The two properties files can<br />
be located in the root of JavaSource and the single HTML file is located in the<br />
servlets_login folder under WebContent.<br />
This section will take you through the process of creating the LoginServlet servlet<br />
using the Servlet wizard.<br />
1. Open the Web perspective.<br />
2. Expand the OnlineCatalog project in the Project Navigator view.<br />
3. Right-click the JavaSource directory and click New -> Servlet from the<br />
context menu to start the Servlet wizard.<br />
4. On the first page verify that the Folder field value is<br />
/OnlineCatalog/JavaSource, enter common for the Java package, and enter<br />
LoginServlet as the Class name. Everything else should be left as default.<br />
Chapter 7. Working with servlets 233
Figure 7-19 Servlet wizard - screen 1<br />
5. Click Next.<br />
6. The Servlet page asks you to specify Modifiers, Interfaces, and method stubs.<br />
We are only concerned with having the doPost() method created at this time,<br />
so uncheck the doGet() and Inherited abstract methods checkboxes. The<br />
other options can be kept as is.<br />
234 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 7-20 Servlet wizard - screen 2<br />
7. Click Next.<br />
8. The Deployment Descriptor allows you to add any information to the<br />
deployment descriptor related to the servlet being created. Select the Add to<br />
web.xml check box to add a URL mapping for the servlet. This is optional but<br />
we recommend it. You can also specify and initialization parameters if you<br />
wish. For example, you could specify database connection properties here if<br />
you required.<br />
Chapter 7. Working with servlets 235
Figure 7-21 Servlet wizard - screen 3<br />
9. Click Finish. Upon creation, the LoginServlet servlet will be opened in the<br />
Java editor.<br />
236 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
LoginServlet servlet<br />
Figure 7-22 Working with servlets in the workbench<br />
The final code for the LoginServlet servlet can be seen in the example below.<br />
Example 7-1 LoginSerlvet.java<br />
package common;<br />
import javax.servlet.http.*;<br />
import javax.servlet.*;<br />
import java.io.*;<br />
import java.sql.*;<br />
public class LoginServlet extends HttpServlet {<br />
/**<br />
* Process incoming HTTP POST requests<br />
*<br />
* @param request Object that encapsulates the request to the servlet<br />
* @param response Object that encapsulates the response from the servlet<br />
*/<br />
public void doPost(HttpServletRequest request, HttpServletResponse response)<br />
throws ServletException, IOException {<br />
Chapter 7. Working with servlets 237
Get data from HTML form<br />
String user = request.getParameter("username").trim();<br />
String pass = request.getParameter("password").trim();<br />
// Verify that user exists<br />
if (hasPriv(user, pass)) {<br />
// Send user to admin page<br />
response.sendRedirect(response.encodeRedirectURL("/OnlineCatalog/administration<br />
/admin.html"));<br />
}<br />
else {<br />
PrintWriter pw = response.getWriter();<br />
pw.println("LOGIN ERROR - Invalid user or<br />
password");<br />
pw.println("Click here to Try<br />
Again");<br />
}<br />
}<br />
private boolean hasPriv(String user, String pass) {<br />
boolean result = false;<br />
try {<br />
// Connect to the database<br />
DBConnection dbConnection = new DBConnection();<br />
// Query database<br />
ResultSet rs = dbConnection.getFromDB("SELECT password, username FROM<br />
users WHERE username = '" + user + "'");<br />
if (!rs.next()) {<br />
try {<br />
common.LogWriter.getInstance().writeToLog("Login Error: Invalid<br />
username " + user);<br />
} catch (InterruptedException ex) {}<br />
return false;<br />
}//if<br />
// Get password for user from database<br />
String realPass = rs.getString("password").trim();<br />
238 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
If password matches one in database, then successful login<br />
if (realPass.equals(pass)) {<br />
result = true;<br />
} else {<br />
try {<br />
common.LogWriter.getInstance().writeToLog("Login Error: Invalid<br />
password entered for " + user);<br />
} catch (InterruptedException ex) {}<br />
}//if<br />
}<br />
}<br />
// Close the connection<br />
rs.close();<br />
dbConnection.close();<br />
return result;<br />
} catch (Throwable e) {<br />
try {<br />
common.LogWriter.getInstance().writeToLog("Login Exception: " + e);<br />
return false;<br />
} catch (InterruptedException ex) {<br />
return result;<br />
}<br />
}<br />
Note: The login component illustrated in this section is only mentioned here to<br />
show the use of servlets in Studio Site Developer. The login component is not<br />
a proper Web site security solution and is not recommended for “real-life”<br />
situations. To reiterate, when the user logs in, a servlet will verify that the user<br />
and password exist in a database table and forward the user to a new page.<br />
No session information is used in the process, therefore if the user knew the<br />
full path of the location he or she could get there without using the login.<br />
Chapter 7. Working with servlets 239
7.4 References<br />
Some additional references you may find handy are:<br />
► <strong>WebSphere</strong> Studio <strong>Application</strong> Developer Version 5 Programming Guide,<br />
SG24-6957 (Chapter 5)<br />
► Programming J2EE APIs with <strong>WebSphere</strong> Advanced, SG24-6124 (Chapter 8)<br />
► Servlet and JSP Programming with <strong>IBM</strong> <strong>WebSphere</strong> and VisualAge for Java,<br />
SG24-5755 (Chapter 4)<br />
► Building Java <strong>Application</strong>s for the iSeries <strong>Server</strong> with VisualAge for Java 3.5,<br />
SG24-6245 (Chapter 1)<br />
► Core Servlets and Java<strong>Server</strong> Pages, ISBN 0-13-089340-4<br />
► SAMS Teach Yourself Java2 in 21 Days, 2nd Edition, ISBN 0-672-31958-6<br />
240 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 8. Working with JSPs<br />
8<br />
This chapter discusses how Java<strong>Server</strong> Pages (JSPs) can act as the<br />
presentation mechanism for dynamic data in your Web application. We will start<br />
with a brief introduction to the technology, and then concentrate on the elements<br />
that make a JSP. We will then see how JSPs can be used to implement the<br />
display of account data in our sample application. In this chapter, the following<br />
topics are discussed:<br />
► JSP overview<br />
► Studio Site Developer support for JSPs<br />
► Using JSPs in the Online Catalog sample<br />
© Copyright <strong>IBM</strong> Corp. 2003 241
8.1 JSP overview<br />
In the early days of Java development it soon became apparent that, while<br />
servlets provided an excellent mechanism for the handling of requests for<br />
dynamic content, they did not provide a useful way of displaying the response.<br />
The hard-coding of presentation within the servlet code meant that changing the<br />
“look and feel” of the presentation layer required changes to the Java files that<br />
also provided the business logic, and the resultant recompiling, testing, and<br />
deploying. The roles of Web designer and Java programmer were not distinct,<br />
leading to development process problems.<br />
Using JSPs offers the following advantages:<br />
► Separation of dynamic and static content<br />
This allows for separation of application logic and Web page design reducing<br />
the complexity of Web site development and making the site easier to<br />
maintain.<br />
► Platform independence<br />
Because JSPs are Java-based, they are platform independent. JSPs can run<br />
on any Web application server. JSPs can be developed on any platform and<br />
be viewed by any browser because the output of a compiled JSP page is<br />
HTML.<br />
► Component reuse<br />
Using JavaBeans and tag libraries, JSPs leverage the inherent reusability<br />
offered by these technologies. This enables code sharing among developers,<br />
thus speeding development efforts.<br />
► Scripting and tags<br />
JSPs support both embedded JavaScript and tags. JavaScript is typically<br />
used to add page-level functionality to the JSP. Tags provide an easy way to<br />
embed and modify JavaBean properties and to specify other directives and<br />
actions.<br />
The JSP level mandated by J2EE 1.3 is JSP 1.2.<br />
8.1.1 JSP execution model<br />
In order to effectively use JSPs, it is first important to understand how they work.<br />
Essentially, a JSP file can be thought of as an HTML page with embedded<br />
segments of Java code that are executed at runtime. As such, a JSP file looks<br />
mostly like normal HTML, and can be edited by a Web designer who maintains<br />
responsibility for the look and feel of the site.<br />
242 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
However, more interesting to the reader of this publication is what actually<br />
happens when a JSP page is invoked. Figure 8-1 shows the invocation routine.<br />
Request 1 - foo.jsp<br />
Request 2 - foo.jsp<br />
Response<br />
Figure 8-1 JSP invocation<br />
Request phase Translation phase<br />
JSP Container<br />
Does<br />
foo.class<br />
exist?<br />
foo.class<br />
Yes<br />
Has source<br />
.jsp changed?<br />
No<br />
Compile Java<br />
Source<br />
foo.jsp<br />
Generate<br />
Java Source<br />
foo.java<br />
There are two distinct phases in JSP invocation, the translation and the request<br />
phase. Central to this is the fact that within the Web container, requests for<br />
individual JSPs result in the creation of a Java class. This class is actually a<br />
servlet. That is, it implements the javax.servlet.Servlet interface. The two phases<br />
represent the creation of the servlet class and its subsequent invocation.<br />
Phase 1: Translation<br />
In Figure 8-1, Request 1 represents the first request for foo.jsp since the JSP<br />
was deployed to the server. In this case, there is no existing servlet class for the<br />
JSP. The first step in this phase is to translate the JSP source file into a Java<br />
source file, which can then be compiled into a servlet, known as the JSP page<br />
implementation class.<br />
No<br />
Yes<br />
Chapter 8. Working with JSPs 243
In fact, in <strong>WebSphere</strong>’s JSP implementation, the foo.jsp file is translated into two<br />
files: A .java file containing the Java code for the servlet, and a .dat file containing<br />
the static elements of the JSP. The .dat file actually contains a serialized array of<br />
byte arrays, with each byte array containing the static page elements before the<br />
next JSP tag. The .java file is then compiled to create a .class file, which<br />
represents the compiled servlet.<br />
The .class and .dat files are stored on the file system. The .java file may or may<br />
not be retained after the translation stage. This translation phase is performed<br />
once per JSP. If a compiled class file already exists on the file system, then the<br />
request for the JSP proceeds directly to phase 2.<br />
Phase 2: Request processing<br />
Phase 2 represents the actual invocation of the compiled servlet—the JSP page<br />
implementation class—to provide a response to the initial request.<br />
For Request 1, this phase is entered immediately after phase 1. If the servlet is<br />
not already loaded, it is brought into memory and the request serviced.<br />
For Request 2, the Web container knows of the existence of an already compiled<br />
servlet class loaded in memory, and directly services the request.<br />
By default, the JSP implementation in <strong>WebSphere</strong> also checks the source .jsp<br />
file for changes. If it has been modified it will enter the translation phase. Each<br />
subsequent request is handled by the servlet until the servlet is unloaded from<br />
memory, for instance, when the application server is stopped. This load/service<br />
request/unload life cycle is exactly the same as for servlets.<br />
8.1.2 Syntax for coding Java<strong>Server</strong> Pages<br />
Java<strong>Server</strong> Pages can be coded using two alternative methods: JSP syntax or<br />
XML syntax. The two cannot be mixed within a page. Beginning with JSP 1.2,<br />
JSP pages written in XML (referred to as JSP documents) can be delivered to the<br />
Web container for processing.<br />
The traditional JSP syntax looks like that shown in Example 8-1.<br />
Example 8-1 JSP syntax<br />
<br />
<br />
<br />
<br />
Example 8-2 JSP document<br />
session="true"<br />
%><br />
<br />
<br />
<br />
<br />
AddNewItemProcess.jsp<br />
<br />
<br />
Place AddNewItemProcess.jsp's content here.<br />
<br />
<br />
The same JSP as an XML document would look like that shown in Example 8-2.<br />
<br />
<br />
]]><br />
]]><br />
<br />
<br />
<br />
<br />
<br />
<br />
AddNewItemProcess.jsp<br />
<br />
<br />
Place AddNewItemProcess.jsp's content here.<br />
<br />
<br />
<br />
A JSP document has jsp:root as its root element. The root element has one<br />
mandatory attribute, the version of JSP specification it is using. The root can<br />
contain xmlns elements, which enable the use of the standard elements, for<br />
example tag libraries.<br />
Chapter 8. Working with JSPs 245
8.1.3 JSP 1.2 elements<br />
The JSP 1.2 specification defines the following set of basic page elements:<br />
► Directives<br />
► Scripting elements<br />
► Actions<br />
Each of these elements is described below, but first we introduce some common<br />
objects available to every JSP page.<br />
Implicit object variables<br />
From the earlier discussion you will remember that JSPs are actually executed as<br />
servlets at runtime. During this execution, a number of implicit objects are<br />
available to the JSP page. Table 8-1 summarizes the role of these objects, and<br />
the variable used to access these from the page.<br />
Table 8-1 JSP implicit objects<br />
Object variable Role<br />
request The request that initiated the invocation of the JSP. For an HTTP<br />
request, it is a subtype of javax.servlet.HttpServletRequest.<br />
response The response to the request. For an HTTP request, it is a subtype<br />
of javax.servlet.HttpServletResponse.<br />
pageContext A platform-independent utility object that provides access to the<br />
vendor-specific implementations of other implicit objects. Also<br />
provides accessor methods to objects stored within the page<br />
scope.<br />
session Provides access to any available javax.servlet.http.HttpSession<br />
object associated with the requestor.<br />
application Provides accessor methods to objects stored within the<br />
javax.servlet.ServletContext object for the Web application.<br />
out Provides the mechanism for writing to the Response<br />
OutputStream, an instance of javax.servlet.jsp.JspWriter.<br />
config Provides access to the javax.servlet.ServletConfig object for the<br />
JSP page.<br />
page Analogous to the Java implicit object.<br />
exception Available when the JSP is acting as an error page. Allows access<br />
to the exception object thrown from the calling page.<br />
246 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: These objects are also available directly in the Bean Scripting<br />
Framework (BSF) server-side JavaScript.<br />
For more information about servlets, see Chapter 7, “Working with servlets” on<br />
page 215.<br />
Object scope<br />
Each implicit object belongs to a particular scope within the Web application.<br />
Indeed, the same scopes also become important when using JavaBeans within<br />
JSPs. Table 8-2 lists the available scopes.<br />
Table 8-2 JSP object scopes<br />
Scope Description Applies to<br />
page Objects are available from the<br />
javax.servlet.jsp.PageContext for the current JSP page.<br />
References to the objects are discarded upon<br />
completion of the _jspService() method.<br />
request Objects are available from the<br />
javax.servlet.http.HttpServletRequest object for the<br />
current request. Objects are discarded at the<br />
completion of the current request.<br />
session Objects are available from the<br />
javax.servlet.http.HttpSession object associated with<br />
the current client. Objects are discarded when the<br />
HttpSession is invalidated.<br />
application Objects are available from the<br />
javax.servlet.ServletContext object associated with the<br />
Web application. Objects are discarded when the<br />
ServletContext object is reclaimed.<br />
► response<br />
► pageContext<br />
► out<br />
► config<br />
► page<br />
► exception<br />
request<br />
session<br />
application<br />
The implicit objects available through the pageContext, request, session, and<br />
application variables each provide getAttribute() and setAttribute() methods,<br />
which allow objects to be stored and retrieved within the particular scope they are<br />
associated with. As such, objects stored using the pageContext.setAttribute()<br />
method have the most limited scope: They exist only for the duration of that page<br />
invocation. Conversely, objects stored using the application.setAttribute() method<br />
have the widest scope: They exist for as long as the Web application is running.<br />
Chapter 8. Working with JSPs 247
Directives<br />
Directives give a way to provide information to the Web container, which can be<br />
used to determine the behavior and composition of the JSP page. JSP 1.2<br />
defines three types of directive: page, include, and taglib. The taglib directive is<br />
covered in detail in Chapter 9, “Using tag libraries” on page 275. For now, we will<br />
take a look at the page and include directives.<br />
All directive tags have the same syntax:<br />
<br />
Or, in XML syntax:<br />
<br />
In both cases, directive represents either page, include, or taglib.<br />
The page directive<br />
The page directive tag allows for the definition of a number of attributes that are<br />
passed to the Web container. As the name suggests, page directives apply to the<br />
JSP page as a whole. Multiple attributes can be specified within a single page<br />
directive tag, or attributes can be specified in individual page directive tags.<br />
However, each attribute can only be specified once within a JSP. The exception<br />
to this rule is the import attribute. Multiple import attributes can be declared on a<br />
single JSP.<br />
A full list of valid attributes is defined in Table 8-3.<br />
Table 8-3 Valid page directive attributes<br />
Attribute Description<br />
language Defines the scripting language to be used by scripting elements. JSP<br />
1.2 defines the value “java” as the only supported scripting language.<br />
If no language attribute is specified, “java” is defaulted to. <strong>WebSphere</strong><br />
3.5.2 later also supports scripting languages that in turn support the<br />
<strong>IBM</strong> Bean Scripting Framework (BSF). Currently this is limited to<br />
Netscape’s Rhino JavaScript implementation. For more details on BSF,<br />
refer to the Web site at:<br />
http://oss.software.ibm.com/developerworks/projects/bsf<br />
extends Allows the JSP page implementation class to extend a class other than<br />
the Web container’s implementation of javax.servlet.jsp.JspPage.<br />
248 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Attribute Description<br />
import Allows the definition of classes and packages that will be available to<br />
scripting elements within the JSP. Classes within the following<br />
packages are available by default:<br />
► java.lang.*<br />
► javax.servlet.*<br />
► javax.servlet.jsp.*<br />
► javax.servlet.http.*<br />
session If true, the implicit object variable session will refer to a session object<br />
either already existing for the requesting user, or explicitly created for<br />
the page invocation. If false, then any reference to the session implicit<br />
object within the JSP page results in a translation-time error. The<br />
default is true.<br />
buffer Defines the buffering model for the JspWriter underlying the out implicit<br />
object variable. The default is an 8-kb buffer. It can be set to a value of<br />
xkb, or none.<br />
autoFlush If true, the buffered output is flushed when full. If false, an exception is<br />
thrown should the buffer fill up. A value of false, if the value of the buffer<br />
is set to none, will result in a translation-time error. The default is true.<br />
isThreadSafe If true, the JSP page implementation class will implement the<br />
javax.servlet.SingleThreadModel interface, and requests for the JSP<br />
will be handled sequentially in the order in which they were received.<br />
If false, then requests will be dispatched to the page on arrival and<br />
handled by individual threads. The default value is false.<br />
info Allows a String object to be defined, which can be returned by calling<br />
the getServletInfo() method of the JSP page implementation class.<br />
This will override any description provided at deployment time.<br />
isErrorPage Specifies if the page acts as an error page for other JSPs. If true, then<br />
the exception implicit object variable is available for use. If false, any<br />
reference to exception will result in a translation-time error. The default<br />
is false.<br />
errorPage Defines a URL to which any uncaught exceptions thrown during page<br />
execution can be directed. The URL must specify a JSP page that has<br />
isErrorPage set to true. The exception class is placed in the request<br />
object sent to the JSP acting as the error page where it is made<br />
available through the exception implicit object variable.<br />
contentType Defines the encoding of the JSP page and the response content.<br />
Chapter 8. Working with JSPs 249
A point of note concerns the session attribute. As explained, if the session<br />
attribute is set to true, or not specified at all, then the session implicit object<br />
variable will reference the HttpSession object for the requesting client. If there is<br />
no HttpSession object available, then one will be created explicitly. This can<br />
create a performance overhead if your JSP page is not intended to interact with<br />
session objects. If this is the case, then you should ensure that the directive tag is included within your JSP.<br />
The list in Example 8-3 shows a snippet of JSP source code containing example<br />
page directives.<br />
Example 8-3 Page directive example<br />
<br />
<br />
Date and time<br />
<br />
<br />
<br />
<br />
The current date and time is: <br />
<br />
<br />
The include directive<br />
The include directive allows content held in other files on the server file system to<br />
be included within the JSP page source at translation time. That is, the contents<br />
of the included file will be included in the JSP source at the point where the tag is<br />
defined and therefore processed by the JSP page compilation procedure. The<br />
included file may contain both static content and other JSP tags. The include<br />
page directive takes one attribute: file.<br />
The file attribute defines a relative URL, or URI, to the file to be included within<br />
the JSP page. This URI may be either page or context relative.<br />
The included file may contain any valid JSP tags. These tags will be translated to<br />
Java source and included in the JSP page compilation class. The rules regarding<br />
page directives stated in “The page directive” on page 248 still apply to page<br />
directive tags within the included file. A page directive tag contained within the<br />
included file will apply to the whole JSP at translation time. Any page directives<br />
within the included file that conflict with tags contained in the “including” JSP<br />
source will cause compilation time errors. For instance, if a JSP file contains a<br />
page directive specifying session=“false”, and then includes another file<br />
containing a JSP scripting element referencing the session attribute, a error will<br />
occur.<br />
250 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
One consequence of the fact that the file referenced within the include directive is<br />
included during the translation phase is that subsequent changes to the included<br />
file will not be picked up by the Web container on subsequent invocations of the<br />
JSP. The changes will only be visible when the JSP containing the include<br />
directive is itself updated, or its JSP page compilation class is deleted, forcing the<br />
translation phase to be carried out. If this behavior is not desirable, you can use<br />
the include action tag instead (see “The include action tag” on page 255).<br />
Example 8-4 shows an example of using an include directive.<br />
Example 8-4 file2.jsp<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
File2.jsp<br />
<br />
<br />
<br />
Place File2.jsp <br />
<br />
<br />
The contents of the file to be included, file1.jsp, are shown Example 8-5.<br />
Example 8-5 file1.jsp<br />
<br />
<br />
BODY><br />
First File Contents.<br />
<br />
<br />
Chapter 8. Working with JSPs 251
Note: After deployment to a server, changes to file1 are not seen by the server<br />
until file2 is recompiled.<br />
Scripting elements<br />
Scripting elements allow the insertion of code into the JSP. Technically the actual<br />
code is defined by the scripting language. As mentioned in Table 8-3 on<br />
page 248, the only scripting language required by the JSP 1.2 specification is<br />
Java. In addition, <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express provides support for<br />
JavaScript and <strong>IBM</strong>’s Bean Scripting Framework.<br />
Let us take a look at how the scripting elements can be used to insert segments<br />
of Java code into your JSPs.<br />
There are three forms of scripting element:<br />
► Declarations<br />
► Scriptlets<br />
► Expressions<br />
Each of the types is described below.<br />
Declarations<br />
Declarations allow us to perform the declaration of variables and methods within<br />
our JSP source. We can then use these variables and methods within other<br />
scripting elements on our page. The syntax for a declaration element is:<br />
<br />
Or, in XML syntax:<br />
<br />
declaration(s)<br />
<br />
For example, to declare a variable, we can use the tag:<br />
<br />
To declare a method:<br />
Note that all variables declared within declaration elements will become class<br />
instance variables within the JSP page implementation class. Therefore they<br />
should not be used to store any invocation-specific data, for example, counters or<br />
data relating to a specific client.<br />
Scriptlets<br />
A scriptlet is the most general purpose JSP element, but also the element to use<br />
with the most caution. They can contain any valid Java code that you could<br />
normally place within the body of a Java method, including variable declarations,<br />
method calls, and so on. The contents of any scriptlet expressions within a JSP<br />
will be included within the jspService() method of the JSP page compilation<br />
class. The syntax of a scriptlet tag is:<br />
<br />
Or in XML syntax:<br />
scriptlet <br />
Individual scriptlets do not have to contain a complete piece of Java syntax, they<br />
can interleave themselves with other page elements, allowing you to build up a<br />
conditional display of static page elements. However, if the combination of the<br />
scriptlets at translation time does not yield valid Java syntax, then a<br />
translation-time error will occur.<br />
As you can imagine, excessive use of scripting elements in a confusing manner<br />
can make JSP source code hard to read. If you refer back to the start of this<br />
chapter you will remember that one of the problems that led to the evolution of<br />
JSPs was the presence of presentation elements making Java logic hard to<br />
understand. Now with JSPs containing excessive scriptlet use, we could have the<br />
opposite: Our presentation logic is hard to understand and develop because it is<br />
cluttered with Java code.<br />
One way to avoid this cluttered programming is to evaluate how taglibs can be<br />
used instead of hand-coding Java. The Jakarta Web site (http://jakarta.com),<br />
among others, has many tag libraries that can be used for common tasks. More<br />
on this will be covered in Chapter 9, “Using tag libraries” on page 275.<br />
Another way is to create a bean and then reference it in the JSP page.<br />
Expressions<br />
Expressions attempt to convert the result of the expression evaluation to a String.<br />
Expressions take advantage of the fact that the object within Java can be<br />
represented as a String, either through implementing a toString() method, or<br />
inheriting one from a parent class or, ultimately, java.lang.Object. Primitive types<br />
can also be directly output.<br />
Chapter 8. Working with JSPs 253
The syntax for expression tags is:<br />
<br />
Or in XML syntax:<br />
expression <br />
Use of implicit object variables in scripting elements<br />
All of the available implicit object variables, as described in Table 8-1 on<br />
page 246, are available for use from within scriptlets and expressions. For<br />
example, objects placed within the HttpServletRequest object or within the<br />
HttpSession object can be retrieved and used within scriptlets and expressions<br />
via the request and session variables, respectively.<br />
Actions<br />
The third type of JSP element is the set of action tags. We will only briefly<br />
introduce the standard action tags defined within the JSP 1.2 specification here.<br />
The standard action tags are listed in Table 8-4.<br />
Table 8-4 Standard action tags<br />
Action tag Description<br />
Allows access to a Java object, usually a<br />
JavaBean, retrieved from a given scope or<br />
newly instantiated through a named<br />
identifier.<br />
Sets the value of a bean property.<br />
Outputs a Bean property, converted to a<br />
String.<br />
Allows inclusion of static and dynamic<br />
content within the current JSP page.<br />
Forwards the responsibility for request<br />
handling to another static or dynamic<br />
resource.<br />
Enables the generation of<br />
browser-specific HTML to enable use of<br />
the Java plug-in with applets or other Java<br />
components.<br />
Used in connection with the include,<br />
forward, and plug-in action tags to supply<br />
parameters in key/value pairs.<br />
254 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Action tag Description<br />
Used to enclose template data in XML<br />
representation. The interpretation of it to<br />
pass its content through to value of out.<br />
For now we will concentrate on the param, include, and forward tags.<br />
All action tags use the same tag syntax, which, unlike the previous tags, is XML<br />
compatible. Action tags have two forms, either an open or closed body tag. The<br />
exception is the param action, which only appears in the form of a closed body<br />
tag.<br />
The param action tag<br />
The param tag usually appears within the body of one of the other tags, and<br />
allows the inclusion of a key/value type attribute. For example, to set a parameter<br />
named foo with the value bar, the following tag may be used:<br />
<br />
The value attribute may be an expression tag that is evaluated at runtime. For<br />
example:<br />
<br />
The include action tag<br />
The include action tag provides a way to include static and dynamic content<br />
within the output produced by the JSP page containing the tag. The content<br />
included by an include action tag is parsed at request-time. This contrasts with<br />
the include directive, which is parsed at translation time.<br />
The syntax of the tag is:<br />
<br />
Or as an open-bodied tag:<br />
<br />
<br />
<br />
The page attribute specifies the relative URL, or URI, for the resource to include.<br />
The resource may be a static file, JSP, or servlet. The value of the page attribute<br />
may be specified via a JSP expression tag. The flush attribute specifies a<br />
boolean value indicating whether the page buffer should be flushed before the<br />
inclusion.<br />
Chapter 8. Working with JSPs 255
The include action tag works in fashion equivalent to the include() method of the<br />
javax.servlet.RequestDispatcher class defined in the Servlet 2.2 specification.<br />
The request object and any parameters defined are passed to the resource<br />
specified in the page attribute. The included resource then takes over<br />
responsibility for producing output. Once finished, the responsibility returns to the<br />
calling JSP.<br />
If the resource specified in the page attribute is a JSP, then that JSP undergoes<br />
the normal life cycle of translation processing/request processing. As it is being<br />
included in a runtime context, any change to the included JSP will cause it to go<br />
through the translation phase again. If we refer back to our example of the<br />
include directive and re-code it to use an include action tag instead, then any<br />
changes we make to file1.jsp between invocations of file2.jsp will be reflected in<br />
the next invocation.<br />
The forward action tag<br />
Just as the include action tag works like the include() method of<br />
javax.servlet.RequestDispatcher, so the forward action tag works in the same<br />
way as the forward() method. The syntax of the tag is:<br />
<br />
Or as an open-bodied tag:<br />
<br />
<br />
<br />
When a JSP page uses a forward action tag, it terminates its own execution and<br />
hands responsibility to the resource specified in the page attribute. If the output<br />
buffer contains any output written before the forward action tag is processed,<br />
then the buffer is cleared before the forward takes place. The resource specified<br />
in the page attribute will provide all of the output, including headers.<br />
The JSP 1.2 specification states that any output written to the page buffer will be<br />
cleared when the forward tag is called. Therefore, that output will not appear.<br />
However, if output has already been flushed from the buffer, or a page directive<br />
specifies a buffer size of none and output has been written, the attempt to clear<br />
the buffer will result in a request-time exception being thrown.<br />
8.2 Building JSP pages with Studio Site Developer<br />
Studio Site Developer provides a wide variety of tools, wizards, and aids to assist<br />
you in building JSP pages. JSP development takes place primarily in the Web<br />
perspective.<br />
256 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
8.2.1 Preferences and properties<br />
Within the workbench preferences and project properties dialogs, there are<br />
several options available to you for customization.<br />
Preferences<br />
The Preferences dialog can be opened by selecting Window -> Preferences<br />
from the workbench main menu. The JSP Files page can be displayed by<br />
expanding Web and XML Files from the left pane and clicking JSP Files. The<br />
JSP Annotations, JSP Macros, and JSP Styles pages can be found by exanding<br />
the JSP Files option.<br />
JSP files<br />
► Allows you to select line delimiters for the operating system that applies to<br />
your development. Line delimiters are used to indicate the start of a new line.<br />
► Allows you to use the workbench encoding when creating files, or you can<br />
specify another one from the Encoding drop-down list.<br />
8.2.2 Web perspective<br />
JSP annotations<br />
Allows you to specify the annotation colors for the default JSP editor.<br />
JSP macros<br />
This page allows you to create, delete, or edit macros available to you when<br />
creating JSPs.<br />
JSP styles<br />
You can specify the syntax highlighing colors for the default JSP editor.<br />
Properties<br />
The Properties dialog can be opened by right-clicking your project and selecting<br />
Properties from the context menu. Select JSP Fragment from the left pane to<br />
display the page properties.<br />
JSP fragments<br />
You can specify the encoding, language, and content type for the JSPs in the<br />
project.<br />
There are many aids to use when adding code to a JSP in the Web perspective.<br />
You can see some of these in Figure 8-2 on page 258. This looks a little messy<br />
but it is done for illustrative purposes.<br />
Chapter 8. Working with JSPs 257
Note: You would not have the content assist menu and the JSP toolbar<br />
drop-down open at the same time.<br />
The basic use of the Web perspective when working with JSPs is very similar to<br />
working with HTML pages as described in “Using the Web perspective” on<br />
page 78. The difference being, some of the views have specific support related to<br />
JSPs.<br />
Outline view<br />
Figure 8-2 Aids for adding JSP content<br />
Content assist<br />
JSP toolbar menu<br />
Page designer<br />
Snippets view<br />
Page designer<br />
Page designer is the default JSP editor and is used in the same fashion as when<br />
editing HTML pages. For more information about Page designer, please see<br />
“Editing with the Page Designer” on page 90.<br />
258 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Palette view
JSP toolbar menu<br />
The JSP option on the toolbar contains helpful tools to add dynamic content. You<br />
can see the current list of options in Figure 8-2 on page 258. If you select an<br />
option that needs further clarification, such as parameters, a name, options, etc.,<br />
a window will pop up allowing you to enter the necessary information. For<br />
example, if you select Insert Include from the JSP pull-down, you will see a<br />
window (such as Figure 8-3) allowing you to name the file to include and to pass<br />
parameters to it.<br />
Figure 8-3 Inserting a JSP include<br />
The resulting code added to the JSP would look like Example 8-6.<br />
Example 8-6 JSP include code<br />
<br />
<br />
<br />
For all the options you see, the processing is intelligent. For example, if you<br />
select Insert Results from Bean but have not defined a useBean, then you will<br />
get a message saying that the useBean needs to be defined first.<br />
Content assist<br />
The content assist menu can be used to select code or tags to enter. You can<br />
open the content assist menu by using Ctrl+spacebar, or by right-clicking the<br />
editor window and selecting Content Assist.<br />
Chapter 8. Working with JSPs 259
The list you see is relevant to the position of the cursor in the editor. This makes<br />
the content assist particularly useful when working with tags. Placing the cursor<br />
within the tag will limit the options you see to the tag options. For example, if you<br />
have placed the cursor within a custom taglib tag, you will only see options that<br />
are valid for that location. Figure 8-4 shows the content assist menu when you<br />
have the cursor immediately after the sql: tag. You see a list of all valid tag<br />
options to choose from.<br />
Figure 8-4 Using the content assist menu<br />
If you move the cursor over a few spaces so that it follows the sql:statement, then<br />
you only see a list of what is expected next. In this case, the id attribute is<br />
expected and that is your only choice.<br />
Figure 8-5 Narrowing down the choices<br />
260 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Snippets view<br />
The Snippets view contains reusable JSP objects. The JSP options are shown in<br />
Figure 8-6. To use the ojects, simply drag and drop them from the drawer onto<br />
the JSP in the source view of Page designer. Opting to insert one of the options<br />
places the template for the code in the file at the cursor location.<br />
Figure 8-6 JSP snippet view objects<br />
Outline view<br />
The Outline view gives you an overview of the structure of the JSP. Clicking an<br />
item in the outline highlights that element in the editor window.<br />
Chapter 8. Working with JSPs 261
Figure 8-7 Outline view<br />
Palette view<br />
The Palette view Java<strong>Server</strong> Pages drawer contains items very similar to the JSP<br />
toolbar menu options. When using Page designer to edit the JSPs, simply drag<br />
and drop the items from the drawer into the source code of the JSP.<br />
262 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
8.2.3 JSP wizard<br />
Figure 8-8 Palette view<br />
The JSP wizard takes you step-by-step through the process of creating a JSP. To<br />
create a new JSP file, do the following:<br />
1. To launch the New JSP File wizard, select File -> New -> JSP File.<br />
2. Select the appropriate container for the file from the list of project folders (and<br />
subfolders). The folder that you choose should be under the WebContent<br />
folder of the Web project. If a JSP file is not under this folder, then it will not be<br />
included in the WAR file that is deployed to the server. In addition, link<br />
validation will not encompass files that are not under the WebContent folder.<br />
3. Type a file name into the appropropriate field.<br />
4. Ensure that the appropriate option is displayed in the Markup Language<br />
drop-down list. In addition, if you select the Create as JSP Fragment check<br />
box, this file will be created as a fragment that can be added to another JSP<br />
file. Other JSP files can include JSP fragments using a JSP include directive.<br />
Creating a fragment causes the resulting file to end in a .jspf or .jsf extension.<br />
You will not be prompted for DOCTYPE information, because a fragment<br />
cannot stand alone as a Web page, and it would invalidate any JSP file that<br />
included it. Also, depending which markup language you select, you can<br />
select the Use XML Style Syntax option to create a JSP file that adheres to<br />
XML style tagging.<br />
Chapter 8. Working with JSPs 263
5. You have three options for proceeding:<br />
a. If you want to accept the defaults associated with a new JSP file, leave<br />
Model as None and make sure the Configure advanced options is<br />
unchecked.<br />
b. If you want to apply a page template to your new file, select Page<br />
Template in the Model field and click Next.<br />
i. If you want to use one of the sample templates provided, select<br />
Sample Page Template and then choose one of the templates shown<br />
in the Thumbnail box.<br />
ii. If you want to use a template of your own, select User-defined Page<br />
Template and then click Browse to select the template from the file<br />
system.<br />
c. If you want to specify or customize the file options, select the Configure<br />
advanced options check box and click Next.<br />
i. You can add tag libraries from a variety of sources by clicking the Add<br />
button to locate a TLD file or a JAR file that contains a TLD file. Tag<br />
library Universal Resource Identifier (URIs) can be located in one of the<br />
following places:<br />
Defined in the web.xml file<br />
Within a JAR file located in the project lib directory that contains<br />
/META-INF/taglib.tld<br />
Within a JAR file external to the project<br />
In a “loose” TLD anywhere in the project<br />
As you add tag libraries, the Available Custom Tags window displays<br />
the declaration of the tag along with the tag library directive. If the<br />
selected TLD file hasn't been registered in the web.xml file, it will be<br />
added automatically.<br />
ii. In the Select a tag library dialog, either select one of the available tag<br />
libraries or click the Import button to locate and add a tag library to the<br />
list, and then select it. The dialog will automatically populate the<br />
informational fields that describe the tag library and its contents. You<br />
must specify a Prefix value. Click OK to add the tag library.<br />
iii. Click Next.<br />
iv. If you want to select an encoding type, deselect the Use workbench<br />
encoding check box to select a new encoding attribute. Select the<br />
appropriate encoding value to add to the file's HTML declaration from<br />
the Encoding drop-down list. The default is the value set in the HTML<br />
Files preferences page, which is accessed by selecting Window -><br />
264 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Preferences, and then expanding the Web and XML Files<br />
preferences.<br />
v. Ensure that the proper content type is selected in the Content Type<br />
drop-down list. The default depends on the markup language.<br />
vi. Select the Document Type that you wish to associate with the JSP file.<br />
The default depends on the markup language.<br />
vii. Specify a cascading style sheet (CSS) file to to be referenced by the<br />
new JSP file. Typically, CSS files are located in the theme folder under<br />
the WebContent folder. You can use Add to choose a style sheet from<br />
the file system. Use Remove to delete a style sheet from the list, or<br />
use the arrow buttons to rearrange the order in which the file<br />
references the style sheets. If a style sheet is already associated with<br />
the project in which you are creating the new file, that style sheet is the<br />
default.<br />
viii.Click Next to select specific method stubs and add deployment<br />
information to the Web project's web.xml file. Select any appropriate<br />
method stubs to be created in the servlet that is deployed for this JSP<br />
file. If you select the Add to web.xml check box, the JSP file, along<br />
with its display name, and any URL mappings and initialization<br />
parameters associated with the JSP file will be automatically included<br />
in the Web project deployment descriptor file. Note that the File Name<br />
value provided in the first page of the wizard is automatically mapped<br />
to the Servlet Name value on this page, as well the URL Pattern<br />
mappings. These mappings are not updated if you change the original<br />
value in the File Name field.<br />
6. Click Finish to create the file in the project that you have selected. As a<br />
default, the new file opens in Page Designer, in the Design page.<br />
8.3 Using JSPs in the Online Catalog sample<br />
Now that you have seen some of the aids, try using them to build a JSP. Much of<br />
the coding that you do will probably end up to be straight typing, but remember<br />
that there are many aids to ease the process. It will take practice to become<br />
familiar with what is available.<br />
Chapter 8. Working with JSPs 265
In this example, we will be building a page called AddNewItemProcess.jsp. The<br />
entry point into this process is an HTML page called AddNewItem.html. This<br />
page basically consists of a form with input fields. The fields are used to collect<br />
data about the new item that is to be added. When the user clicks the Submit<br />
button, AddNewItemProcess.jsp is called to take those fields and add a record to<br />
the database based on them. The basic flow of this process is shown in<br />
Figure 8-9.<br />
*<br />
Add Item<br />
Required fields are indicated by an asterisk<br />
Item Number<br />
Item Name<br />
Description<br />
Quantity<br />
Price (US)<br />
Featured Item?<br />
Reset<br />
Submit<br />
AddNewItem.html<br />
Figure 8-9 Add new item process<br />
get request parameters<br />
validate item #<br />
Look for duplicate items in db<br />
If this item is a featured item, unmark<br />
others<br />
Add item to the database<br />
AddNewItemProcess.jsp<br />
Creating a new JSP<br />
To create a new JSP:<br />
1. From the Web perspective and Project Navigator view, select the folder where<br />
you want to put the JSP. This can be directly in the Web Content folder of the<br />
Web project or in a user-defined folder under it. In this case, we will select the<br />
Web Content/administration folder.<br />
2. Right-click the folder and select New -> JSP file. A wizard will begin.<br />
3. On the first page, set the File Name field to AddNewItemProcess.<br />
266 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Database
Figure 8-10 Location of JSP file<br />
4. Click Next. You will be prompted for tag libraries you want to use. We have not<br />
discussed tag libraries yet, but for now just be aware that we will be using a<br />
tag library to access the application database.<br />
5. Click Add taglib. You will be able to select from a list of tag libraries that have<br />
been included in your Web project.<br />
Chapter 8. Working with JSPs 267
Figure 8-11 Adding tag files<br />
For our example, we used the tag libraries listed in Table 8-5.<br />
Table 8-5 Taglibs for sample code<br />
URI Prefix<br />
http://coldjava.hypermart.net/servlets/validtag if<br />
http://coldjava.hypermart.net/servlets/backtag go<br />
jspsql dab<br />
In each case, we will scroll down to the taglib and select it. A prefix (of your<br />
choice) is needed to identify the tag library within the JSP. The prefixes we<br />
use in the sample code are shown in Table 8-5.<br />
268 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: The only tag library in Table 8-5 that is included with Studio Site<br />
Developer is the JSPSQL tag library. The others would need to be<br />
downloaded and imported to the project. If you are following along with our<br />
sample, these libraries are available because they have already been<br />
imported into the sample project for your use. Importing tag libraries will be<br />
discussed in more detail in 9.2.1, “JSP wizard” on page 288.<br />
6. Click OK and then Next.<br />
7. Click Next. This page allows you to select options that affect the way the page<br />
is coded.<br />
Figure 8-12 Specify options to be included in the page<br />
In this case, all the defaults fit our needs, so click Next.<br />
8. The next page allows you to add a servlet entry for the JSP in the Web<br />
deployment descriptor. This is optional, but saves you time if you find that you<br />
need to do this later. One prime reason for doing this would be to add URL<br />
pattern mappings to make it easier to refer to the JSP in the code. Another<br />
reason would be to add initialization parameters.<br />
Chapter 8. Working with JSPs 269
Figure 8-13 Add the JSP to web.xml<br />
Select the Add to web.xml box. This will add a corresponding servlet entry in<br />
the Web deployment descriptor. You may or may not need this later but it is<br />
always a good practice to do so.<br />
9. Click Finish.<br />
A JSP file with the minimal JSP and HTML framework is generated using<br />
information we provided before and is opened in the editor area. With the JSP<br />
created, you can add the following code to it to complete the process of creating<br />
a JSP. Manually enter the code below to see the different tools available in Studio<br />
Site Developer.<br />
Example 8-7 AddNewItemProcess.jsp<br />
<br />
<br />
<br />
<br />
270 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
SELECT<br />
DB2ADMIN.ITEM.ITEM_NUMBER<br />
FROM<br />
DB2ADMIN.ITEM<br />
WHERE<br />
DB2ADMIN.ITEM.ITEM_NUMBER = :itemNumber<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Chapter 8. Working with JSPs 271
<br />
<br />
<br />
<br />
<br />
INSERT INTO<br />
DB2ADMIN.ITEM(<br />
ITEM_NUMBER,<br />
ITEM_SHORT_DESC,<br />
ITEM_LONG_DESC,<br />
QUANTITY,<br />
PRICE,<br />
SOTD_FLAG<br />
)<br />
VALUES(<br />
:item_number,<br />
:item_short_desc,<br />
:item_long_desc,<br />
:quantity,<br />
:price,<br />
:sotd_flag<br />
)<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Thank you<br />
272 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Item number has been added!<br />
Do you wish to add additional items<br />
or would you like to return to the site<br />
administration function menu?<br />
<br />
In our sample, we use the following line of code to include a file into our JSP. This<br />
file contains the database connection information and is referenced by the<br />
connectionSpec parameter in the dab tags.<br />
<br />
We did not hard-code the connection information into the JSP because we were<br />
concerned with session data issues related to our Wishlist feature of the site. If<br />
we had inserted the connection information into the JSP, we would have lost the<br />
connection parameters when the wishlist page was viewed. This occurs because<br />
we remove the database session object from the wishlist page. The wishlist page<br />
simply uses session attributes to display the users item selections.<br />
Chapter 8. Working with JSPs 273
274 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 9. Using tag libraries<br />
9<br />
Custom tag libraries provide an abstraction of Java code as opposed to<br />
scriptlets, which require Java programming experience. For a Web developer in<br />
charge of writing JSPs, using custom tags eliminates the need for in-depth Java<br />
knowledge and makes it easy to reuse code.<br />
This chapter provides information on using tag libraries in Web applications. It<br />
introduces the concepts of custom tag libraries (taglibs) and gives information on<br />
how to use them.<br />
► Tag library concepts<br />
► Studio Site Developer and tag libraries<br />
► Using tag libraries in the Online Catalog sample<br />
We will focus mainly on understanding the content of tag libraries and how to<br />
incorporate existing tag libraries into a Web application. If you are interested in<br />
creating tag libraries, please refer to Programming J2EE APIs with <strong>WebSphere</strong><br />
Advanced <strong>Server</strong> - Express V5.0.2 Developer Handbook SG24-6124.<br />
© Copyright <strong>IBM</strong> Corp. 2003 275
9.1 Custom tag library (taglibs) concepts<br />
taglibs gives programmers a way of including functions coded in Java without<br />
having to code them. By including a custom tag library with existing functions in<br />
the application and defining a way to reference these functions, Web site<br />
developers can take advantage of the functions they provide with little effort.<br />
Taglibs can be developed by the programmer, but more often are downloaded<br />
from existing sources. For example, the following sites contain tag libraries for<br />
download:<br />
► Open-source utility tag libraries available from the Apache Group’s Jakarta<br />
project:<br />
http://jakarta.apache.org/taglibs<br />
Note: The Jakarta Tag Library project is an open-source repository for JSP<br />
custom tag libraries and associated projects. Detailed information for each<br />
of the Jakarta tag libraries below can be found at:<br />
► Other sources we used during this project:<br />
http://coldjava.hypermart.net<br />
http://jsptags.com/tags/<br />
9.1.1 Motivation for custom tags<br />
http://jakarta.apache.org/taglibs/index.html<br />
JSPs are borne out of the desire to leave application logic free of presentation<br />
logic. However, we have seen that although JSPs provide such separation, if not<br />
used sensibly they can introduce the opposite problem, where the JSP becomes<br />
too cluttered with Java code, especially scriptlets. Such intrusion of Java code<br />
into the JSP makes the development and maintenance difficult for a number of<br />
reasons, among them are:<br />
► The use of scriptlets requires Java programming experience; they cannot be<br />
made much easier to create by programming tools, such as Studio Site<br />
Developer.<br />
► Scriptlets are useful for applying conditional logic to the page element display,<br />
but doing so makes the markup language hard to understand.<br />
► More Java code within a JSP means that there is increased likelihood of<br />
errors occurring in the JSP page compilation class.<br />
► Although we can access beans within our JSPs, if changes need to be made<br />
to that bean’s interface, we may need to make coding changes in every JSP<br />
that uses it.<br />
276 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Advantages<br />
Beginning with JSP 1.1 we have the ability to hide much of this complexity and<br />
reduce these problems by abstracting out much of the Java code within our JSPs<br />
into a custom tag. By doing this, we can overcome a lot of the problems<br />
mentioned above:<br />
► Our JSP authors may find it easier to work with a custom tag that looks like<br />
other JSP action tags, rather than to program Java code directly within a<br />
scriptlet. Programming tools like Studio Site Developer can automate a lot of<br />
the work involved in using the tag.<br />
► The reduced Java code within the JSP makes it much easier to understand.<br />
This may be important when trying to maintain other peoples’ JSPs.<br />
► The custom tags can include much more exception and error handling logic<br />
without exposing this to the JSP author or clogging up the JSP page. Custom<br />
tags can be developed and tested in isolation from the actual JSPs they will<br />
be used in.<br />
► We can wrap access to JavaBeans within custom tags. The properties and<br />
methods of the bean can be accessed through use of custom tags. Therefore,<br />
we can maintain and develop the bean without changing the interface the JSP<br />
uses. We can also add new features to our tags while maintaining backwards<br />
compatibility, something that is not always easy to do when accessing a Java<br />
API directly.<br />
By using custom tags, we can harness the possibility of making our JSP pages<br />
quicker and easier to develop, and also more maintainable. What is more, by<br />
using them to wrap common tasks, we can also take advantage of portability by<br />
reusing custom tags across Web applications. Whole libraries of third-party<br />
custom tags are freely available.<br />
There are also advantages possible only by using custom tags. The most notable<br />
is the ability to post-process JSP output before it is written. This is a potentially<br />
powerful piece of functionality that is not achievable using scriptlets.<br />
Disadvantages<br />
Despite the obvious potential advantages to their use, custom tags should not be<br />
viewed as a remedy for the problems associated with JSP development. Overuse<br />
of custom tags can lead to other problems:<br />
► Creation of meta-languages: By forcing a multitude of custom tags onto the<br />
JSP authors we also force them to learn the syntax of all the tags. Effectively<br />
we create another language, which may have a simpler interface than Java,<br />
but still needs learning. In any case, custom tags should always be supplied<br />
with sufficient documentation and examples.<br />
Chapter 9. Using tag libraries 277
9.1.2 When to use<br />
► Controller logic: Many custom tag libraries are available to access APIs, such<br />
as JDBC, JNDI, and so forth. Although the tags provide a simple and powerful<br />
way to use such services (for example, to access a database), so their use<br />
leads to the presence of controller and business logic within the JSP.<br />
► Performance: The runtime work involved in handling custom tags within the<br />
Web container does have an overhead. If performance of the Web application<br />
is critical then custom tags may not be appropriate.<br />
Given the advantages and disadvantages listed above, the question of when<br />
custom tag usage is appropriate arises. The simple answer to this is that the<br />
primary consideration when deciding should be: Will the tag remove the need to<br />
put Java code within the JSP? The critical word in that question is need. If you<br />
need to implement some functionality within a JSP that will require some<br />
non-trivial Java code, then it is probably a good candidate for a custom tag. This<br />
is especially true when the same Java code is present within more than one JSP<br />
for the reasons of maintainability.<br />
By basing the decision to implement a custom tag on the need to have the<br />
functionality, you reduce the temptation to implement some function that really<br />
should go elsewhere. The custom tags you implement should stay true to the<br />
overall application architecture and design. For some designs (for example, those<br />
based on the page-centric model of JSP usage) custom tags for database<br />
access and the like may well be necessary. However, if a database tag is used<br />
within an MVC-based design, then this suggests that the functionality is<br />
implemented in the wrong place.<br />
If we decide that a piece of JSP functionality is a suitable candidate for a custom<br />
tag, then there are other questions that arise. The nature of the functionality<br />
should be considered. Custom tags can generally be thought of as either generic<br />
or domain specific. Generic tags have wide ranging uses. Can you pick up an<br />
existing tag for this purpose? Domain tags are more specific, and therefore their<br />
scope for reuse may be limited and the effort in creating the functionality within a<br />
custom tag may not be paid back if the function is only used on one or two JSPs<br />
within your application.<br />
You should also give consideration to the factors surrounding the authoring of the<br />
JSPs. If the JSP authors are confident with Java, then they may prefer scripting<br />
to using custom tags. Conversely, if the JSP authors are non-Java programmers,<br />
then a custom tag interface will be better suited. Custom tags are also useful<br />
when the dialog between the JSP author and Java programmer is limited by<br />
physical distance or communication factors.<br />
278 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
In practice, it is often best to provide the JSP author with choice. By<br />
implementing the logic of the tag within a bean and providing the custom tag as a<br />
wrapper to the bean’s interface, then you may be able to provide the author with<br />
the choice of scripting or using custom tags.<br />
9.1.3 Common custom tag usages<br />
9.1.4 How they work<br />
When custom tags are used, they often perform a function that falls into one of<br />
the following categories:<br />
► Markup generation: Generation of markup language output, for example, to<br />
create an HTML form.<br />
► Scripting generation: Generation of client-side scripting code such as<br />
JavaScript, for example, to perform client-side data validation. This is<br />
illustrated in the Online Catalog sample.<br />
► Environment access: Providing access to and modification of implicit objects.<br />
► API access: Simplifying access to APIs such as JDBC, JNDI, and JavaMail.<br />
This is illustrated in the Online Catalog sample.<br />
► Content manipulation: Manipulating content before output, and caching of<br />
generated content.<br />
In order for the Web container to understand and execute a custom tag, the code<br />
implementing the tag and information on how to translate the tag and find and<br />
invoke the code must be available to the container. Tags for a particular function<br />
are normally aggregated into a tag library.<br />
Tag libraries, or taglibs, are normally packaged as JAR files. The taglib is made<br />
up of the following elements:<br />
► Tag library definition (TLD): An XML file containing elements that describe<br />
each tag in the library. The TLD will be used by the Web container during<br />
translation time to interpret each tag, and at request time to find and invoke<br />
the tag code.<br />
► Tag handler: A Java class that provides the Web container with access to the<br />
functionality of the tag. However, this does not necessarily mean that the tag<br />
handler implements the tag functionality. As we hinted, this may be contained<br />
within other classes/JavaBeans. The taglib will contain a tag handler class for<br />
each custom tag.<br />
► Supplemental classes: The implementation of a custom tag may include<br />
some optional files that, if used, need to be included within the taglib.<br />
Chapter 9. Using tag libraries 279
These are:<br />
– TagExtraInfo: Provides additional information, over and above that<br />
contained within the TLD, about a custom tag.<br />
– BeanInfo class: Tag handlers are themselves JavaBeans, and the Web<br />
container will inspect them to obtain properties and methods. This can be<br />
aided by a BeanInfo class for each tag handler.<br />
The programmer downloads these files and puts them where they will be<br />
available to the application. A directive is added to the JSP that refers to the<br />
library and assigns it a prefix. In the JSP code, the prefix is used to invoke tags<br />
within the library. The Web application deployment descriptor (web.xml) provides<br />
the link between the directive used in the application and the actual JAR file<br />
containing the classes that execute the function.<br />
9.1.5 An inside look at a taglib<br />
Let us take a look at a simple tag that displays a hello message. The elements of<br />
a taglib include:<br />
► An implementation bean<br />
► A tag handler class<br />
► A tag library descriptor<br />
It is important to note that if you are simply using an existing taglib, the only thing<br />
you really need to know is that these things exist. We want to show you a quick<br />
example to take the mystery out of taglibs.<br />
Implementation bean<br />
The actual tag implementation is contained within a JavaBean called HelloBean,<br />
shown in Example 9-1. The bean supplies one method, hello(), which accepts a<br />
String argument. The method outputs a message.<br />
Example 9-1 Simple custom tag example: HelloBean.java<br />
//Simple custom tag example: HelloBean.java<br />
package com.ibm.itso.j2eebook.tagexamples.beans;<br />
/**<br />
* JavaBean which displays a Hello message.<br />
*<br />
* @author: Adrian Spender<br />
*/<br />
public class HelloBean {<br />
/**<br />
* HelloBean default constructor.<br />
280 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
}<br />
*/<br />
public HelloBean() {<br />
super();<br />
}<br />
/**<br />
* Returns a string saying hello to the name argument.<br />
*<br />
* @return A hello message<br />
* @param name java.lang.String The name to say hello to<br />
*/<br />
public String hello(String name) {<br />
return "Hello " + name;<br />
}<br />
Now we have the syntax for our tag defined, and the bean that provides the<br />
implementation. The rest of the steps are best described as cookbook code. That<br />
is, the code is largely the same whatever tag you are implementing. The classes<br />
and methods you need to define are always the same. The first few times you go<br />
through these steps will perhaps seem tedious, but creating them soon becomes<br />
relatively trivial.<br />
Tag handler class<br />
The tag handler class extends the javax.servlet.jsp.tagext.TagSupport class, and<br />
provides an endTag() method that will be executed when our tag has been<br />
parsed by the Web container. We also need to create an instance variable called<br />
name that will hold the value of our tag’s attribute. Our tag handler class is shown<br />
in Example 9-2. Important sections of code are in bold, and comments are<br />
provided to explain what is happening.<br />
Example 9-2 Simple custom tag example: HelloTag.java<br />
//Simple custom tag example: HelloTag.java<br />
package com.ibm.itso.j2eebook.tagexamples;<br />
import java.io.IOException;<br />
import javax.servlet.jsp.*;<br />
import javax.servlet.jsp.tagext.*;<br />
import com.ibm.itso.j2eebook.tagexamples.beans.*;<br />
/**<br />
* Handles the hello tag.<br />
*<br />
* @author: Adrian Spender<br />
*/<br />
public class HelloTag extends javax.servlet.jsp.tagext.TagSupport {<br />
Chapter 9. Using tag libraries 281
This variable will store the name attribute of the tag<br />
private java.lang.String name;<br />
/**<br />
* HelloTag default constructor.<br />
*/<br />
public HelloTag() {<br />
super();<br />
}<br />
/**<br />
* Called when the end of the tag is reached. Here we simply<br />
* call our bean to get our output and then write it out.<br />
*<br />
* Note that we have access to the pageContext implicit object.<br />
*<br />
* At the end of the method we return an integer that tells the<br />
* Web container whether the rest of the JSP page should be<br />
* executed. If set to SKIP_PAGE then the JSP execution will<br />
* stop. If set to EVAL_PAGE, execution will continue.<br />
*<br />
* @return indication to continue page execution<br />
* @exception javax.servlet.jsp.JspException<br />
*/<br />
public int doEndTag() throws JspException {<br />
}<br />
int result = EVAL_PAGE;<br />
// Here we call our bean to get our message<br />
HelloBean hb = new HelloBean();<br />
String mess = hb.hello(name);<br />
try {<br />
// and here we write the message back out<br />
pageContext.getOut().write(mess);<br />
} catch (IOException e) {<br />
// whoops<br />
e.printStackTrace();<br />
}<br />
release();<br />
return result;<br />
... as our tag is a bean, we also provide accessor and setter methods<br />
}<br />
282 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Tag library descriptor (TLD)<br />
The hello tag is packaged in a taglib. The TLD provides the Web container with<br />
the information it needs about the taglib, including the tag handler class<br />
information and the attributes of the tag. The TLD for hello is shown in<br />
Example 9-3.<br />
Example 9-3 Simple custom tag example: j2eebook.tld<br />
<br />
<br />
<br />
<br />
1.0<br />
1.1<br />
j2eebook<br />
Tag examples from ITSO J2EE Redbook<br />
<br />
hello<br />
com.ibm.itso.j2eebook.tagexamples.HelloTag<br />
empty<br />
<br />
Takes a name and says hello<br />
<br />
<br />
name<br />
true<br />
<br />
<br />
<br />
The TLD is an XML document that describes the contents of a tag library to the<br />
Web container. It helps the container identify custom tags within a JSP page, find<br />
the tag handler, recognize the attributes of the tag, and in combination with any<br />
TEI, validate the tag.<br />
Note: The JSP container uses the TagExtraInfo (TEI) class at translation time<br />
to provide information over and above that provided by the TLD.<br />
The structure of the TLD is pretty self-explanatory. As an XML file, the TLD<br />
contains a standard XML root element and DTD statement.<br />
Chapter 9. Using tag libraries 283
The TLD contains two main elements, taglib and tag. The taglib element defines<br />
details of the tag library as a whole. It also contains a tag element for each<br />
custom tag within the library. Table 9-1 defines possible subelements within a<br />
taglib element.<br />
Table 9-1 Subelements of the TLD element<br />
Sub-element Description<br />
Defines the version of this tag library.<br />
Defines the version of the JSP<br />
specification that the tags within the library<br />
need.<br />
Defines a name for the tag library.<br />
Defines a unique reference to the tag<br />
library.<br />
A String describing the contents of the tag<br />
library.<br />
A tag element defines the details for a<br />
particular custom tag in the library.<br />
Of these, the URI element is the most important. It ties the taglib directive defined<br />
within a JSP page with a specific tag library. Alternatively, the URI may be<br />
defined in the web.xml file for the Web application.<br />
The tag element defines most of the information needed by the Web container for<br />
a particular tag. The subelements of the tag element are listed in Table 9-2.<br />
Table 9-2 Sub elements of the TLD element<br />
Sub element Description<br />
The name by which the tag will be referred<br />
to in a JSP page.<br />
The tag handler class.<br />
If the tag has a TEI (TagExtraInfo), then its<br />
class is referred here.<br />
Attempts to define the contents of the tag<br />
body.<br />
A sting describing the function of the tag.<br />
The attribute element defines the details<br />
of a tag attribute.<br />
284 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
There is one tag element for each custom tag within the library. The bodycontent<br />
element is, according to the JSP specification, primarily for use by authoring<br />
tools. It may take one of three values: tag dependent, JSP, or empty. In practice, it<br />
is most often used to define tags that will have no body content by specifying<br />
empty.<br />
The tag element will include an attribute element for each attribute of the tag. The<br />
attribute element has three subelements:<br />
► Name: A required element and defines the name of the attribute<br />
► Required element: If true, tells the Web container that a translation-time error<br />
should occur if the attribute is not specified within a given tag instance<br />
► rtexprvalue: If true, specifies that the Web container should allow the attribute<br />
value to be expressed using a JSP expression tag<br />
9.1.6 Using tag libraries<br />
Now that you have seen what a taglib is, you can see how simple it is to use it<br />
within an application. The key to using a tag library is to make the TLD available<br />
to the Web container. This usually involves three steps:<br />
► Identifying the location of the TLD using a taglib directive in the JSP where<br />
the taglib is to be used. The taglib directive can point directly to the TLD, or it<br />
can use a URI that maps to a deployment descriptor entry.<br />
► An entry in the Web application deployment descriptor that identifies the TLD<br />
location and URI.<br />
► Invoking the taglib in the code.<br />
Taglib directive<br />
The taglib directive tells the Web container how to find the TLD for the taglib and<br />
the identifier (prefix) that will be used in the application to signal that the taglib is<br />
to be used. The format for the taglib directive is:<br />
<br />
The URI we specify can be abstracted from the physical location of the TLD,<br />
allowing us more flexibility and portability when deploying our Web applications.<br />
For example:<br />
<br />
The URI specified here is absolute, that is, it specifies a protocol, host, and uri.<br />
Within the web.xml file for our Web application, we must provide a taglib element<br />
to map this to a particular location. The location specifies a relative URI for the<br />
location of the TLD.<br />
Chapter 9. Using tag libraries 285
It is possible to avoid the need to specify a mapping within web.xml by making<br />
the uri attribute of the taglib directive a relative URI to the TLD itself. For example,<br />
in Example 9-5 on page 287, we specified:<br />
<br />
In this case, the Web container still looks for such a URI within the taglib<br />
elements of the web.xml descriptor for the Web application. If we do not specify<br />
one then it will use the relative URI to attempt to find the TLD directly.<br />
Finally, the taglib directive may specify a JAR file for the URI. For example:<br />
<br />
In this case, the TLD must be located within the META-INF directory of the<br />
booktags.jar file.<br />
Although these latter two techniques can be useful in taglib development, in<br />
production absolute URIs ideally should be used to aid portability and<br />
maintenance.<br />
Taglib entries in web.xml<br />
The classes and TLD that make up a tag library are packaged as a JAR file for<br />
deployment to the application server. A taglib entry in the Web deployment<br />
descriptor, web.xml, associates a URI to a TLD location. An example entry is<br />
shown below:<br />
<br />
<br />
<br />
uri<br />
<br />
<br />
location<br />
<br />
<br />
An example is shown in Example 9-4.<br />
Example 9-4 Taglib entry in web.xml<br />
<br />
http://jakarta.apache.org/taglibs/application-1.0<br />
/WEB-INF/lib/application.jar<br />
<br />
The URI refers to the uri attribute of a taglib directive on the JSP page on which<br />
the tag library is used. The Web container uses the information provided in<br />
web.xml to map this uri to a physical TLD defined by the location attribute.<br />
286 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Invoking the taglib within the application<br />
To continue the example of the hello tag, we have seen that the tag accepts one<br />
attribute, called name. The syntax of the tag is:<br />
<br />
The code used to invoke the tag is shown in Example 9-5. First, the taglib is<br />
declared with a taglib directive, giving it a prefix, book, which we will use to<br />
identify the tags. Then the prefix is used to invoke the taglib function.<br />
Example 9-5 Simple custom tag example: helloSample.html<br />
<br />
<br />
<br />
<br />
Simple custom tag example<br />
<br />
<br />
<br />
Simple custom tag example.<br />
<br />
<br />
<br />
The result of executing the HTML is shown in Figure 9-1.<br />
Figure 9-1 Simple custom tag example: Results<br />
Chapter 9. Using tag libraries 287
9.2 Studio Site Developer and tag libraries<br />
9.2.1 JSP wizard<br />
<strong>WebSphere</strong> Studio Site Developer contains serveral tools to help with the<br />
importing and consumption of tag libraries:<br />
► JSP wizard<br />
► Insert custom tag dialog<br />
► Snippets view<br />
As described in “Using a tag library in the Online Catalog sample” on page 301,<br />
the steps to using tag libraries are listed below. Notice that in addition to the<br />
steps, some of the tools above are listed. This indicates that these tools can be<br />
used to complete a step.<br />
1. Create a JSP (JSP wizard).<br />
2. Add a taglib directive to the JSP (JSP wizard or Insert custom tag dialog or<br />
Snippets view).<br />
3. Add the appropriate taglib tags to the JSP (Insert custom tag dialog).<br />
4. Insert the final JSP scriptlet and HTML code into the JSP; this step is<br />
optional.<br />
For step two, all three tools are listed. When using the JSP wizard, you can select<br />
the tag libraries that you wish to use in the JSP. If a tag library is selected, a taglib<br />
directive will be added to the JSP for that tag library. Likewise, in order to use the<br />
Insert custom tag dialog, you must first select the tag library; if a tag library is not<br />
listed, you can add it. In doing so, a taglib directive will be added to the JSP. The<br />
Snippets view simply adds a page directive. Each of these tools is described in<br />
greater detail in the following sections.<br />
When you create a JSP using the JSP wizard, you have the option of adding<br />
taglib directives. If the tag library that you want is not in the provided list, you can<br />
import a new tag library into the project and use it. The process of adding taglib<br />
directives and importing a new tag library is illustrated below. For the illustration,<br />
we have downloaded a validation tag library (validtag) from:<br />
http://coldjava.hypermart.net<br />
1. Switch to the Web perspective.<br />
2. Right-click the Web Content folder and select New -> JSP File from the<br />
context menu to start the JSP wizard.<br />
3. On the first page, specify your JSP File Name and click Next.<br />
288 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
4. On the Tag Libraries page, you will notice that two tag libraries (html and<br />
bean) have been alreay added for you.<br />
5. Click Add to open the Select a Tag Library dialog. This dialog displays a full<br />
list of all of the tag libraries already included in the project.<br />
Figure 9-2 Included tag libraries<br />
a. You can select a tag library from the list by selecting the check box beside<br />
the taglib entry.<br />
i. Once the tag library is selected, you must specify a Prefix to be used.<br />
ii. Click OK to add the tag library to the list of included tag libraries for<br />
your JSP.<br />
b. If the tag library you want is not displayed in the list, you can click Import<br />
to open the Import JSP Tag Library dialog.<br />
Chapter 9. Using tag libraries 289
Figure 9-3 Importing a tag library<br />
i. Click Browse to locate the tag library .jar file.<br />
ii. Verify that the Add alias URI to deployment desciptor option is<br />
checked. If you wish, you can specify a different URI then the default<br />
one.<br />
iii. Click Finish to add the tag library to the list of available tag libraries.<br />
iv. Locate the tag library and select the check box beside the tag library<br />
entry, then specify the Prefix to be used.<br />
v. Click OK to add the tag library to the list of included tag libraries for<br />
your JSP.<br />
290 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 9-4 Included tag libraries<br />
6. Click Finish to create the JSP. If you open the JSP, you will notice that the<br />
taglib directives have been added to the top of your JSP.<br />
Alternative way of importing a tag library<br />
If you wish to import a tag library into your project but you do not wish to create a<br />
new JSP at the same time, you can import the tag library .jar file separately and<br />
then update the Web deployment descriptor.<br />
For the illustration below, we have downloaded a validation tag library (validtag)<br />
from:<br />
http://coldjava.hypermart.net<br />
Assuming you have downloaded the taglib you want to use into a temporary<br />
directory, you are ready to import it to your Web application. To import a tag<br />
library into your project:<br />
1. Switch to the Web perspective.<br />
2. Right-click your project and click Import from the drop-down menu.<br />
Chapter 9. Using tag libraries 291
3. From the first Import window select File system from the list of import<br />
sources and click Next.<br />
4. In the next window, you must specify the taglib location, select the taglib, and<br />
specify the destination directory where the selected taglib will be imported<br />
(see Figure 9-5).<br />
Figure 9-5 Importing a tag library<br />
The tag library should be imported to the Web Content/WEB-INF/lib folder.<br />
5. Click Finish.<br />
Updating the Web module deployment descriptor<br />
Next we will update the Web deployment descriptor, web.xml, to add a new taglib<br />
reference to the validtag taglib we just imported.<br />
1. Open the deployment descriptor by double-clicking web.xml or Web<br />
Deployment Descriptor in the Navigator view.<br />
292 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
2. Select the References tab and then click the JSP tag libraries tab from the<br />
upper tab menu (see Figure 9-6).<br />
Figure 9-6 Updating the JSP tag library references in web.xml - References view<br />
3. Click Add.<br />
4. A window will open with a list of tag libraries in the WEB-INF/lib folder. Select<br />
the Validtag tag library from the window. The URI will be filled in for you and a<br />
list of tags in the tag library will appear in the bottom screen.<br />
Chapter 9. Using tag libraries 293
Figure 9-7 Adding the Validtag taglib<br />
5. Click Finish.<br />
6. Save and close the deployment descriptor.<br />
Viewing the TLD file<br />
Hopefully, the site that provided the taglib will also provide information on how to<br />
use it, but viewing the TLD file is a quick shortcut into finding out what valid tags<br />
and attributes exist.<br />
You will find that when downloading a taglib, the JAR file is all that you are<br />
required to download. The JAR file contains the classes required to implement<br />
the tag library and the TLD file. However, you usually have the option to<br />
download a separate TLD file also.<br />
If you choose to download the TLD file to your file system, you can use a text<br />
editor to view it. You can also import it to your project as a separate file, though<br />
this is not necessary if it exists in the JAR file.<br />
If you open a TLD file in Studio Site Developer, it will open with the XML editor.<br />
294 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
9.2.2 Using the Insert custom tag dialog<br />
The Insert custom tag dialog allows you to insert a tag from a tag library into your<br />
JSP. If the tag library you want is not listed, you can add one from a list of<br />
available tag libraries in the project. As with the JSP wizard, if the tag library has<br />
not been added to the project, you may import a new one.<br />
To insert a tag library tag into your JSP, complete the following steps:<br />
1. Click a spot in your JSP where you wish to place the the tag library tag and<br />
select JSP -> Insert Custom... from the main menu. The Insert Custom Tag<br />
dialog will open.<br />
Figure 9-8 Insert custom tag<br />
2. The left pane of the dialog contains a list of the tag libraries that are found in<br />
the JSP. The right pane contains the tags that belong to the selected tag<br />
library from the right. Locate the tag you wish to insert and click Insert. The<br />
tag will be added to your JSP.<br />
3. If the tag library you want has not been included with the JSP being edited,<br />
click Add.... This will open the Select a Tag Library page as shown in 9.2.1,<br />
“JSP wizard” on page 288. If you add an incorrect tag library, select the tag<br />
library from the left pane and click Remove.<br />
Chapter 9. Using tag libraries 295
9.2.3 Snippets view<br />
The Snippets view contains an item to add a taglib directive to your JSP. Select<br />
the taglib directive item from the JSP drawer and drag it onto your JSP. A dialog<br />
will open that requires you to enter in the uri and prefix for the directive. Once you<br />
are finished, click Insert and the taglib directive will be added to the top of your<br />
JSP.<br />
Figure 9-9 Insert taglib directive<br />
9.2.4 Tag libraries included with Studio Site Developer<br />
Studio Site Developer includes tag libraries, both from <strong>IBM</strong> and from Jakarta.<br />
One way to include some of these in your application is to select an option at<br />
Web project creation time (see 4.3.2, “Creating a Web project” on page 66).<br />
Table 9-3 on page 297 shows these options and what you get. If you did not<br />
select an option when you created the Web project, you can add these options<br />
later from the Web projects Web property menu. Just right-click the Web project<br />
in the Project Navigator view, select Properties, then select Web.<br />
296 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Table 9-3 Tag library options for Web projects<br />
Option Tag libraries<br />
JSP standard tag library ► jaxen-full.jar<br />
► jaxp-api.jar<br />
► jdbc2_0-stdext.jar<br />
► jstl.jar<br />
► sax.jar<br />
► saxpath.jar<br />
► standard.jar<br />
► xalan.jar<br />
► xerceslmple.jar<br />
Tag libraries for accessing JSP objects ► <strong>Application</strong><br />
► Page<br />
► Request<br />
► Response<br />
► Session<br />
Tag libraries for database access JSPSQL<br />
Tag libraries for internationalization I18n<br />
Utility tag libraries ► DateTime<br />
► Utility<br />
► String<br />
► Mailer<br />
Struts tag libraries - these tag libraries are<br />
added only if Struts support is added to<br />
the project.<br />
► bean<br />
► html<br />
► logic<br />
► nested<br />
► template<br />
► tiles<br />
Let us take a look at some of these tag libraries.<br />
<strong>Application</strong> tag library (from Jakarta)<br />
The <strong>Application</strong> custom tag library contains tags that can be used to access<br />
information contained in the ServletContext for a Web application.<br />
Tags are provided to access information in “application”-scoped attributes and<br />
Web application initialization parameters, which are defined in the<br />
/WEB-INF/web.xml file.<br />
Chapter 9. Using tag libraries 297
Page tag library (from Jakarta)<br />
The Page custom tag library contains tags that can be used to access all the<br />
information about the PageContext for a JSP page.<br />
Tags are provided to access information in "page"-scoped attributes.<br />
Request tag library (from Jakarta)<br />
The Request custom tag library contains tags that can be used to access all the<br />
information about the HTTP request for a JSP page.<br />
Tags are provided to access information in the HTTP request for HTTP input<br />
parameters from a POST or GET, HTTP headers, cookies, request attributes,<br />
and session information related to this request.<br />
Response tag library (from Jakarta)<br />
The Response custom tag library contains tags that can be used to set all the<br />
information for an HTTP response for a JSP page.<br />
This includes creating cookies and setting their values, setting HTTP headers,<br />
returning back an HTTP error, or sending an HTTP redirect.<br />
Session tag library (from Jakarta)<br />
The Session JSP tag library provides tags for reading or modifying client<br />
HttpSession information.<br />
A servlet container uses an HttpSession to store information about a client’s<br />
session on the server. By default, a JSP page will create a session for a user.<br />
The user is tied to the session using either a cookie or URL rewriting. This is how<br />
you can tie information to a user between multiple HTTP requests to your server.<br />
Session attributes are what makes it possible to store information about a client’s<br />
session between multiple HTTP requests. A session attribute consists of a name<br />
and value. To save information about a user’s session on your server, use the<br />
setattribute tag.<br />
Jspsql tag library (from <strong>IBM</strong>)<br />
<strong>IBM</strong> provides a tag library of JSP actions for database access. The tag library<br />
uses a provided set of beans (dbbeans.jar) that offers an easy alternative to<br />
direct use of the JDBC interface for database access. The beans themselves are<br />
implemented using the JDBC interface, and are therefore able to access any<br />
database that has a JDBC driver.<br />
298 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The tag library provides functions that you would otherwise have to implement<br />
separately in each JDBC application, such as caching the rows of a result set in<br />
memory, and executing updates or deletes on rows of the result set.<br />
I18N tag library (from Jakarta)<br />
The I18N custom tag library contains tags that help manage the complexity of<br />
creating internationalized Web applications.<br />
DateTime tag library (from Jakarta)<br />
The DateTime custom tag library contains tags that can be used to handle<br />
date-and time-related functions. Tags are provided for formatting a date for<br />
output, generating a date from HTML forum input, using time zones, and<br />
localization.<br />
Mailer tag library (from Jakarta)<br />
This custom tag library is used to send e-mail.<br />
String tag library (from Jakarta)<br />
This custom tag library is used to manipulate Strings.<br />
Utility tag library (from Jakarta)<br />
The utility custom tag library contains examples of some basic tags. It illustrates<br />
several custom tag library code techniques.<br />
JSP standard tag library (from Jakarta)<br />
JSTL is the standardized set of custom tag libraries that are slated to become<br />
part of the JSP standard. JSTL will replace many of the current Jakarta tag<br />
libraries. Examples of such features are listed below. However, there are many<br />
additional features available.<br />
► Basic logic and flow control tags (if, choose, forEach, etc.)<br />
► Access to implicit server objects (params, session, etc.)<br />
► Reduced scriptlets and use of scoped variables<br />
► Date formatting tags<br />
9.2.5 Tag libraries used in the example sample applications<br />
In addition to the tag libraries you can select when you create a Web project,<br />
Studio Site Developer also includes a few tag libraries in the sample projects. If<br />
you see one you want to use, you can load the sample and import the JAR file<br />
from the WEB-INF/lib directory.<br />
Table 9-4 on page 300 shows the tag libraries used in the examples applications.<br />
Chapter 9. Using tag libraries 299
Tip: If you want to see how the taglibs are used in the example applications, a<br />
quick way to find them is to use the search facility. Start by loading the<br />
application to the workspace. Open the web.xml file and use the References<br />
tab to find the URI. Then select Search from the toolbar and enter the URI as<br />
the search argument. This will give you a list of files that have the URI,<br />
presumably in a taglib directive. Click an entry to open the file to that location.<br />
Note the prefix used for the taglib in the code and scan the code for instances<br />
of where it is used.<br />
Table 9-4 Tag libraries used in example applications<br />
Example Tag library<br />
Document management example DateTime<br />
Page<br />
Request<br />
Response<br />
Session<br />
String<br />
Fileserv<br />
FileIO<br />
Filter<br />
Utility<br />
Customer service example JSP standard tag library<br />
Page<br />
Request<br />
Response<br />
Session<br />
DateTime<br />
Mailer<br />
Filter<br />
Sslext<br />
Custom home page example DateTime<br />
Request<br />
Response<br />
Session<br />
Scrape<br />
Survey example DateTime<br />
I18n<br />
Page<br />
Request<br />
Response<br />
Session<br />
300 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Example Tag library<br />
Your company example DateTime<br />
FileIO<br />
Filter<br />
Fileserv<br />
I18n<br />
Page<br />
Request<br />
Response<br />
Session<br />
FileIO Tag Library (from <strong>IBM</strong>)<br />
Basic file operations. This library implements a file rename and file delete action<br />
on the file system.<br />
Filter tag library (from <strong>IBM</strong>)<br />
This filters HTML markup for presentation of user-entered data. That is, a user<br />
enters the following in a text entry field: Hello World. The filter tag is<br />
used when data is to be presented on a page. It keeps the HTML markup from<br />
being processed and printed as bold text.<br />
SSLext tag library (from <strong>IBM</strong>)<br />
The SSLext tag library provides seamless integration of SSL into the Web<br />
application, allowing secure transmission of Web pages between the Web<br />
browser and Express <strong>Application</strong> <strong>Server</strong>. Information on using this tag library can<br />
be found in the readme file for the customer service example application.<br />
Scrape tag library<br />
The Scrape tag library can scrape or extract content from Web documents and<br />
display the content in your JSP. For example, you could scrape stock quotes from<br />
other Web sites and display them in your pages.<br />
9.3 Using a tag library in the Online Catalog sample<br />
Within the Online Catalog sample, tag libraries are used extensively. This section<br />
illustrates the use of the Mailer tag library. We will use this tag library in the<br />
Online Catalog sample application to process the input from an information<br />
request form.<br />
Chapter 9. Using tag libraries 301
Each taglib is different and will have different attributes and naming conventions.<br />
You will have to locate the documentation for the taglib you are using to find<br />
these. For this example, the documentation for the Mailer taglib can be located<br />
at:<br />
http://jakarta.apache.org/taglibs/doc/mailer-doc/mailer-1.1/index.html<br />
Figure 9-10 shows how tag libraries are used in a Web application.<br />
1<br />
2<br />
WEB-INF/lib/taglibs-mailer.jar<br />
...<br />
mail.class<br />
setrecipient.class<br />
from.class<br />
message.class<br />
send.class<br />
mailer.jsp<br />
<br />
or<br />
3<br />
taglib.tld<br />
...<br />
<br />
<br />
<br />
<br />
<br />
4<br />
Name:<br />
Message:<br />
<br />
web.xml<br />
<br />
<br />
http://jakarta.apache.org/taglibs/mailer-1.1<br />
/WEB-INF/lib/taglibs-mailer.jar<br />
<br />
Figure 9-10 Using custom tag libraries<br />
The Online Catalog application allows visitors to request information (or<br />
comment) about products by sending an e-mail. To do this, the application uses<br />
an HTML page called inforequest.html to solicit input from the user. It then calls<br />
mailer.jsp to retrieve the contents of the form and send an e-mail to the company<br />
using the Mailer taglib.<br />
302 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
inforequest.html mailer.jsp<br />
.<br />
.<br />
.<br />
Figure 9-11 Example process<br />
We will assume at this point that the inforequest.html page has already been<br />
created and that the values to, server, cc, name, from, subject, and message are<br />
the names of the parameters that will be sent to the mailer.jsp when the form is<br />
submitted.<br />
The steps in this example are as follows:<br />
1. Create a JSP<br />
2. Add a taglib directive to the JSP<br />
3. Add the appropriate taglib tags to the JSP<br />
4. Insert the final JSP scriptlet and HTML code into the JSP<br />
9.3.1 Step 1: Creating a JSP<br />
to, server, cc,<br />
name,<br />
from, subject,<br />
message<br />
<br />
<br />
<br />
<br />
<br />
<br />
Name: <br />
Message: <br />
<br />
<br />
The following errors occured<br />
<br />
<br />
<br />
Please back up a page, fix the error and resubmit.<br />
<br />
<br />
Thank you<br />
<br />
Your message has been successfully sent.<br />
The first step in this example is to create a JSP called mailer.jsp. This file should<br />
be placed in the info_request folder under the WebContent directory.<br />
1. Open the Web perspective.<br />
2. Navigate to the WebContent/info_request folder of the OnlineCatalog project,<br />
right-click it, and select New -> JSP File from the context menu. The New<br />
JSP File wizard opens.<br />
3. Specify the File Name as mailer.jsp.<br />
4. Click Next.<br />
5. On the Tag Libraries page, we could add the tab library that we require, but<br />
we will do this later on in the example. Click Finish. The mailer.jsp is created<br />
and opened in Page designer.<br />
.<br />
.<br />
.<br />
Chapter 9. Using tag libraries 303
9.3.2 Step 2: Adding a taglib directive<br />
With the JSP created, we can now add a taglib directive to our page that will<br />
allow us to use the tags and functions of the taglib. The taglib that we will be<br />
using is the Mailer tag library.<br />
1. With the mailer.jsp still open in Page designer, select Window -> Show View<br />
-> Snippets from the main menu of the workbench. This opens the Snippets<br />
view to the right of the editor<br />
2. Expand the JSP drawer in the Snippets view and locate the taglib directive<br />
item.<br />
Figure 9-12 Snippets view<br />
3. Select taglib directive and drag it to the mailer.jsp; drop it in a location just<br />
after the bean taglib directive.<br />
4. The Insert Template:taglib directive dialog opens. Set the uri value to<br />
/WEB-INF/ib/taglibs-mailer.tld and the prefix value to mt.<br />
304 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Important: By default, the taglibs-mailer.tld will not be located in the<br />
WEB-INF/lib folder. You will have to import it into the project. The tld file for the<br />
tag library can be found at the Jakarta site or it can be found in the<br />
taglibs-mailer.jar file. In either location, it will probably be named tablig.tld, so it<br />
will have to be renamed.<br />
There is no problem setting the URI to taglibs-mailer.jar, but in the next<br />
section, we wish to use the Insert Custom tool in Studio and the tld file for the<br />
taglib must be used or the tags will not be displayed in the dialog. Using the<br />
taglibs-mailer.jar file would require us to know all of the tags used in the tag<br />
library.<br />
Figure 9-13 Adding a taglib directive<br />
5. Click Insert. The mailer taglib directive is added to the mailer.jsp.<br />
9.3.3 Step 3: Adding the taglib tags<br />
We can now add our Mailer tags to the JSP so that we can process the user input<br />
and send an email.<br />
1. With the mailer.jsp still open in Page designer, highlight the Place<br />
content here. line of code located between the tags and delete<br />
it.<br />
Chapter 9. Using tag libraries 305
2. Select JSP- > Insert Custom... from the main menu of the workbench to<br />
open the Insert Custom Tag dialog.<br />
3. Select the mailer tag library from the left pane and then select the mail tag<br />
from the right pane.<br />
Figure 9-14 Inserting a tag<br />
4. Click Insert. The mail tag is added to the mailer.jsp.<br />
5. Click Close.<br />
6. Set the server attribute of the mail tag to<br />
. This will set the server attribute<br />
value to the server parameter when it is received from the input form.<br />
7. Inside the mail tag, insert the following tags in this order:<br />
– setrecipient with the type attribute set to to<br />
– from<br />
– setrecipient with the type attribute set to cc<br />
– subject<br />
– message<br />
– send<br />
– error with the id attribute set to err; the error tag must be located inside<br />
the send tag<br />
306 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
8. Your code should look something like the following example.<br />
Example 9-6 Mailer taglib tags inserted into mailer.jsp<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
9.3.4 Step 4: Inserting the final code<br />
Unlike the mail tag, the two setrecipient, from, subject and message tags have<br />
not received any values from the inforequest.html page. In addition, there is no<br />
output to the user to let them know whether or not the submit was successful.<br />
The following example displays the final mailer.jsp. Notice the getParameters<br />
inside the mailer tags. Also notice the error and success output that is added.<br />
Example 9-7 mailer.jsp code<br />
<br />
<br />
<br />
<br />
<br />
<br />
Name: <br />
Message: <br />
<br />
<br />
The following errors occured<br />
<br />
<br />
<br />
Please back up a page, fix the error and resubmit.<br />
<br />
<br />
Thank you<br />
<br />
Your message has been successfully sent.<br />
Chapter 9. Using tag libraries 307
As you are working with taglib code, remember that the content assist menu can<br />
be valuable in building the code.<br />
9.4 For more information<br />
For more information, see the following:<br />
► Programming J2EE APIs with <strong>WebSphere</strong> Advanced, SG24-6124<br />
► Tag library sources:<br />
http://jakarta.apache.org/taglibs<br />
http://coldjava.hypermart.net<br />
http://jsptags.com/tags/<br />
308 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 10. Working with XML<br />
10<br />
eXtensible Markup Language (XML) is a markup language for the exchange of<br />
structured documents. It is a meta-language, meaning a language for defining<br />
other languages. XML by itself does not define any tags; it provides a facility to<br />
define custom tags and the structural relationships between them.<br />
This chapter describes XML use in applications and the support provided in<br />
Studio Site Developer.<br />
► XML overview<br />
► Working with XML in Studio Site Developer<br />
► Using XML in the Online Catalog sample<br />
We will not go into detail on how to build and use XML documents in this<br />
publication. For detailed information, see The XML Files: Development of<br />
XML/XSL <strong>Application</strong>s Using <strong>WebSphere</strong> Studio Version 5, SG24-6586.<br />
© Copyright <strong>IBM</strong> Corp. 2003 309
10.1 XML overview<br />
10.1.1 XML markup<br />
XML is derived from the Standard Generalized Markup Language (SGML),<br />
whose predecessor GML was invented by <strong>IBM</strong> in the 1960s for describing<br />
documents in a device-independent fashion. XML is a subset of SGML and<br />
compatible with it. Initial focus is on serving structured documents over the Web.<br />
XML documents are text-based and composed of markup and content:<br />
► Markup instructs XML processors about how to treat the content, and how it is<br />
organized.<br />
► Content is the character data you would see on a printed or displayed page.<br />
There are six kinds of markups that can occur in an XML document:<br />
Elements Elements are the most common form of<br />
markup. Elements identify the content they<br />
surround: 17.07.2002.<br />
Elements begin with a start tag and<br />
end with an end tag .<br />
Non-empty elements contain child elements or<br />
character data. Empty elements have no<br />
content and can be written in one of two<br />
forms: or<br />
.<br />
Attributes Attributes are name-value pairs that occur<br />
inside element tags after the element name,<br />
such as the Price element has a currency<br />
attribute:<br />
1000.<br />
All attribute values must be enclosed in single<br />
or double quotation marks. These specify the<br />
characteristics of an element.<br />
Entity references Entity references insert reserved characters or<br />
arbitrary unicode, refer to repeated or varying<br />
text, or include the content of external files:<br />
310 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
' <br />
℞ <br />
Entity references begin with the ampersand<br />
and end with a semicolon.
The XML specification predefines five<br />
reserved entity references < > &<br />
" and ' representing the<br />
characters , &, “, and ‘ respectively.<br />
Custom entities can be declared.<br />
Comments Comments are not part of the textual content<br />
of an XML document. They begin with :<br />
<br />
An XML processor is not required to pass<br />
comments along to an application.<br />
Processing instructions (PIs) PIs are an escape hatch to provide<br />
information to an application. Data that follows<br />
the PI target is for the application that<br />
recognizes the target:<br />
<br />
PIs are not textually part of the XML<br />
document, but the XML processor is required<br />
to pass them to an application. The targets<br />
XML and xml are reserved for future XML<br />
standardization efforts.<br />
CDATA sections CDATA sections instruct the parser to ignore<br />
most markup characters. They start with<br />
.<br />
<br />
This CDATA section wraps some source code.<br />
& and < do not have to be entity references as<br />
elsewhere in the document.<br />
Figure 10-1 on page 312 shows the basic elements of an XML document.<br />
Chapter 10. Working with XML 311
<br />
<br />
Welcome to the ITSO SG24-6555<br />
<br />
<br />
<br />
<strong>WebSphere</strong> Express & <strong>IBM</strong> WSAD<br />
<br />
<br />
17<br />
07<br />
2002<br />
<br />
<br />
17<br />
08<br />
2002<br />
<br />
redbook@us.ibm.com<br />
<br />
<br />
<br />
Figure 10-1 XML file<br />
The example in Figure 10-1 spawns the following content structure shown in<br />
Figure 10-2.<br />
Document Object Model (DOM)<br />
welcome<br />
message book-info<br />
book-title<br />
date<br />
date<br />
email<br />
filename<br />
Figure 10-2 XML document structure<br />
312 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
day<br />
month<br />
year<br />
day<br />
month<br />
year<br />
Processing Instruction<br />
Root Element<br />
Child element<br />
Character data<br />
Entity reference<br />
Begin tag<br />
End tag<br />
Attribute<br />
Empty element
10.1.2 Well-formed XML documents<br />
Although XML does not have any predefined tags, there are certain rules that<br />
each XML document has to follow in order to be well formed. By definition, if a<br />
document is not well formed, it is not XML. The rules are:<br />
► Tags cannot be inferred; they must be explicit.<br />
► A document must contain one root element.<br />
► All beginning tags and ending tags match up.<br />
► Empty tags must end with />.<br />
► Tags must nest correctly.<br />
► An entity cannot contain a reference to itself.<br />
► Entities must be declared before they are used.<br />
► Element names are case sensitive.<br />
► All attribute values must be enclosed in single or double quotation marks.<br />
► No attribute may appear more than once on the same start tag or empty tag.<br />
Note: Similar rules exist for HTML; the XHTML specification defines them.<br />
However, HTML browsers also accept HTML documents that are not well<br />
formed.<br />
10.1.3 Document type definitions (DTDs)<br />
Well-formed documents offer many of the advantages of XML, such as<br />
extensibility and adding structure to a set of data. However, exchanging<br />
information through XML documents requires additional functionality: It must be<br />
possible to build a common grammar for a set of documents and to check<br />
compliance automatically.<br />
Document type definitions (DTDs) address these needs. A DTD defines:<br />
► The allowed sequence and nesting of tags<br />
► Elements and their attributes including multiplicity<br />
► Attribute values and their types and defaults<br />
► Entities and notation<br />
DTDs express meta-information about a document's content. With a DTD, an<br />
XML parser can verify the DTD compliance of an XML document. A DTD can be<br />
used in one or more XML documents.<br />
Document types can be declared externally:<br />
<br />
Or internally:<br />
<br />
Chapter 10. Working with XML 313
10.1.4 Validation<br />
A DTD identifies the root element of the document and may contain additional<br />
declarations. It must be the first item in the document after PIs and comments. A<br />
mix of external and internal DTD elements is possible.<br />
Here is an excerpt of the DTD of our example from Figure 10-1 on page 312:<br />
<br />
<br />
<br />
Because DTDs are superseded by XML schemas, we do not go into more detail<br />
here.<br />
A well-formed document is valid only if it contains a proper document type<br />
declaration and if the document obeys the constraints of that declaration.<br />
All valid documents are well formed; not all well-formed documents are valid.<br />
10.1.5 XML namespaces<br />
<strong>Application</strong>s associate the content of a document with its element names (tags).<br />
<strong>Application</strong>s might process two documents with elements using the same tag;<br />
however, it is possible that this tag has a different meaning in each of the two<br />
documents. Hence, the namespace concept is introduced in order to eliminate<br />
naming collisions.<br />
Tag names should be globally unique, but for performance reasons they also<br />
should be short; in order to resolve this conflict, the W3C namespace<br />
recommendation defines an attribute xmlns, which can amend any XML element.<br />
If it is present in an element, it identifies the namespace for this element.<br />
The xmlns attribute has the following syntax:<br />
xmlns=localQualifier:"globallyUniqueName"<br />
The globally unique name uses URI syntax, but it is not a real URI that can be<br />
accessed with a browser through HTTP. Predefined global names exist, for<br />
example, for the data types defined in XML schema and in the SOAP standard.<br />
In the following customer element definition, an accounting namespace is<br />
defined in order to be able to distinguish the element tags from those appearing<br />
in customer records created by other business applications:<br />
<br />
Corporation<br />
<br />
314 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
10.1.6 XML schema<br />
invoice<br />
<br />
The namespace definition in the first line assigns the global name<br />
http://www.my.com/acct-REV10 to the local qualifier acct. This qualifier is used<br />
on the element names such as name in order to attach them to the namespace.<br />
A second application, for example, a fulfillment system, can assign a different<br />
namespace to its customer elements:<br />
<br />
Corporation<br />
<br />
shipped<br />
<br />
An application processing both data structures is now able to treat the<br />
accounting and the fulfillment data differently.<br />
There is a default namespace. It is set if no local name is assigned in the<br />
namespace definition:<br />
It is worth noting that XSDs can be imported into XML files. At processing time,<br />
the imported schemas must be accessible (for example, using HTTP).<br />
In this section we will introduce the more common XML schema concepts that<br />
you will need. There are numerous tutorials available on the Internet. A good<br />
starting point is the following Web site:<br />
http://www.w3.org/XML/Schema<br />
Elements of a schema definition<br />
The following artifacts can be defined in an XML schema:<br />
Declarations Declarations enable elements and attributes with specific<br />
names and types to appear in document instances.<br />
Declarations contain definitions.<br />
Definitions Definitions create new types, either simple or complex. They<br />
can include facades constraining the defined types.<br />
Simple types Simple types cannot have element content. They cannot<br />
carry attributes.<br />
Complex types Complex types have elements in their content and may carry<br />
attributes.<br />
As a first example, we use the simpleType element to define and name a new<br />
simple type:<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
The restriction element indicates the existing base type and specifies two facets,<br />
minInclusive and maxInclusive. These facets constrain the permitted value range<br />
of the new type.<br />
Note that we have defined the default namespace for our schema as the<br />
standard XML schema namespace http://www.w3.org/2001/XMLSchema; we<br />
have also defined our own schema-specific namespace, http://www.ibm.com.<br />
316 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The second part of our example shows several element declarations and two<br />
complex type definitions. The resulting schema is suited to represent a list of<br />
address records:<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
sequence is a reserved XSD keyword, defining the inner structure of a complex<br />
type (its content model). The other two XSD content models are choice and all.<br />
The type attribute is optional; it contains a reference to the type definition, which<br />
is either defined in an XSD file such as ours (for example,<br />
TestSchema:ZipCodeType) or a predefined standard data type (for example,<br />
string in the default XSD namespace).<br />
Assuming that the XSD defined above is saved as C:\temp\TestSchema.xsd. A<br />
sample XML file that validates against this schema is:<br />
<br />
<br />
<br />
x:Pesona Khayangan<br />
16411<br />
x:Jakarta<br />
<br />
<br />
x:Margonda Raya<br />
16423<br />
x:Depok<br />
Chapter 10. Working with XML 317
<br />
Note that the XSD file has to be accessible through HTTP. In the example,<br />
file:///C:/temp/TestSchema.xsd is a true URL pointing to a location. Namespaces<br />
such as http://www.ibm.com, on the other hand, just use the URI notation to be<br />
globally unique. Assuming that noProtocol://www.ibm.com is globally unique, it<br />
would be a valid namespace name as well.<br />
The syntax of the schema location attribute defined by XML standards is:<br />
xsi:schemaLocation="targetnamespaceURI locationURI"><br />
This is a quite tricky notation because it is not obvious that two different entities<br />
with a similar syntax but different semantics appear in the same attribute. Even<br />
worse, the locationURI is often not a full network address, but a simple local file<br />
name.<br />
Target namespace<br />
Several of the XSD elements introduced above can define a target namespace,<br />
which is either absent or a namespace name.<br />
The target namespace serves to identify the namespace within which the<br />
association between the element and its name exists. In the case of declarations,<br />
this association determines the namespace of the elements in XML files<br />
conforming to the schema. An XML file importing a schema must reference its<br />
target namespace in the schemaLocation attribute. Any mismatches between the<br />
target and the actual namespace of an element are reported as schema<br />
validation errors.<br />
In our example, the target namespace is http://www.ibm.com; it is defined in the<br />
XSD file and referenced twice in the XML file. Any mismatch between these three<br />
occurrences of the namespace lead to validation errors.<br />
10.1.7 Schema and style using XSLT and XSL<br />
The extensible style language (XSL) is a language defined by the W3C for<br />
expressing style sheets. It has three parts:<br />
► XSL transformations (XSLT), which is used for transforming XML documents.<br />
► The XML path language (XPath), which is a language used to access or refer<br />
to parts of an XML document.<br />
► XSL-FO, which is a vocabulary for specifying formatting semantics.<br />
A transformation in XSLT must be a well-formed document and must conform to<br />
the namespaces in XML, which can contain elements that may or may not be<br />
318 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
10.1.8 XPath<br />
defined by XSLT. XSLT-defined elements belong to a specific XML namespace. A<br />
transformation in XSLT is called a style sheet.<br />
XSL uses an XML notation and works on two principles: pattern matching and<br />
templates. It operates on an XML source document and parses it into a source<br />
tree; it applies the transformation of the source tree to a result tree, then outputs<br />
the result tree to a specified format. In constructing the result tree, the elements<br />
can be reordered or filtered, and other structures can be added also. The result<br />
tree can be completely different from the source tree.<br />
The XML path language (XPath) is used to address parts of an XML document.<br />
An XPath expression can be used to search through an XML document, and<br />
extract information from the nodes (any part of the document, such as an<br />
element or attribute) in it. There are four different kinds of XPath expressions:<br />
► Boolean: Expression type with two possible values<br />
► Node set: Collection of nodes that match an expression's criteria, usually<br />
derived with a location path<br />
► Number: Numeric value, useful for counting nodes and for performing simple<br />
arithmetic<br />
► String: Text fragment that may come from the input tree, processed or<br />
augmented with general text<br />
An XPath expression returns a certain node set, which is a collection of nodes.<br />
The following is a sample XPath expression:<br />
/ACCOUNT_TABLE/ACCOUNT/ACCID<br />
This expression selects any elements named ACCID (account ID), which are<br />
children of ACCOUNT elements, which are children of ACCOUNT_TABLE elements,<br />
which are children of the document root.<br />
Note: Studio Site Developer provides tools for creating and working with<br />
XPath files, but they are not covered in the following section. Please refer to<br />
the product help for more information.<br />
10.2 Working with XML in Studio Site Developer<br />
Studio Site Developer provides the tools necessary to work with XML, including a<br />
perspective designed just for XML and the necessary editors. Among the many<br />
features for working with XML you will find in Studio Site Developer it can:<br />
Chapter 10. Working with XML 319
► Create XML documents from DTDs, XML schema, or scratch.<br />
► Create the following XML applications from XML files:<br />
– XML validation<br />
– SAX2 parser<br />
– SOAP message<br />
– SOAP message with attachments<br />
► Generate DTDs from scratch, XML, or XML schema files.<br />
► Generate XML schema from scratch, XML, or DTDs.<br />
► Generate XSLs from scratch<br />
► Generate JavaBeans to create an instance document for a DTD or XML<br />
schema.<br />
► Define mappings between XML documents and generate XSLT scripts that<br />
transform documents.<br />
► Create an HTML or XML document by applying an XSL style sheet to an XML<br />
document.<br />
► Map XML files to create an XSL transformation script and to visually step<br />
through the XSL file.<br />
► Define mappings between relational tables and DTD files, or between SQL<br />
statements and DTD files, to generate a document access definition (DAD)<br />
script used by <strong>IBM</strong> DB2 XML Extender. This can be used to either compose<br />
XML documents from existing DB2 data or decompose XML documents into<br />
DB2 data.<br />
► Generate XML artifacts from SQL statements.<br />
► Generate a JavaBean that executes an SQL statement.<br />
► Convert HTML and JSP files to XHTML.<br />
XML options are available from the context menus of the appropriate files types<br />
in the navigators, wizards, and the XML perspective.<br />
Important: This chapter does not go into detail for every tool listed above. For<br />
detailed information, see The XML Files: Development of XML/XSL<br />
<strong>Application</strong>s Using <strong>WebSphere</strong> Studio Version 5, SG24-6586 or refer to the<br />
product help.<br />
This chapter covers only a few XML tools of Studio Site Developer. The following<br />
topics are discussed:<br />
► XML perspective<br />
► Creating a new XML file<br />
320 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► Creating an XML schema<br />
► Creating a DTD<br />
► Creating an XSL file<br />
► Generating XML from SQL<br />
► XML editor<br />
► XSL schema editor<br />
► DTD editor<br />
► XSL editor<br />
10.2.1 The XML perspective<br />
You can work with XML in almost any perspective, but the XML perspective is<br />
designed for it. It contains the views, icons, and toolbar options that assist you in<br />
building XML, XML schemas, XSD, DTD, and integration between relational data<br />
and XML.<br />
Note: Open the XML perspective by selecting Window -> Open Perspective<br />
-> XML from the workbench main menu.<br />
Figure 10-3 on page 322 shows the default layout for the XML perspective and<br />
some of the tools available for XML development. The XML editor is specifically<br />
designed for working with XML files. As with other editors you have both a Design<br />
view and a Source view. The Outline view contains a hierarchical view of the XML<br />
tags in the document. You can also see the options in the XML toolbar<br />
drop-down.<br />
Chapter 10. Working with XML 321
10.2.2 Wizards<br />
Figure 10-3 XML perspective<br />
Outline view<br />
Several wizards are provided for you for the creation of XML-related files. In this<br />
section, we will look at the XML, XML Schema, DTD, and XSL wizards. For<br />
information on the additional XML wizards provided in Studio Site Developer,<br />
please see the product help.<br />
XML wizard<br />
Studio Site Developer provides the Create XML File wizard to take you through<br />
the process of creating a new XML file. This can be invoked in either of the<br />
following ways:<br />
► Select File -> New -> Other -> XML -> XML File (or use the icon).<br />
► From the context menu of a DTD (.dtd) file or an XML schema (.xsd) file in the<br />
Navigator, select Generate -> XML file.<br />
The wizard gives you the following options for creating the XML file:<br />
– From scratch<br />
– From a DTD<br />
– From an XML schema<br />
322 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Editor toolbar menu<br />
Editor
When you create an XML file from a DTD or XML schema file, you will have to<br />
select a root element. With an XML schema, you also select a namespace.<br />
XML schema wizard<br />
Studio Site Developer provides the Create XML Schema wizard to take you<br />
through the process of creating a new XSD file. To create a new XML schema<br />
file, you have the following options:<br />
► To generate it from scratch, select File -> New -> Other -> XML -> XML<br />
Schema (or use the icon).<br />
► To generate it from an existing DTD or XML file:<br />
– From the context menu of a DTD (.dtd) file or an XML (.xml) file in the<br />
Navigator, select Generate -> XML Schema.<br />
– From within a DTD file open in the editor, select DTD -> Generate XML<br />
Schema.<br />
From within an XML file open in the editor, select XML -> Generate XML<br />
Schema.<br />
DTD wizard<br />
A Document Type Definition (DTD) has two purposes:<br />
► To serve as a framework and provide a set of elements and attributes that will<br />
be used in the XML “templates” used by the application to generate XML<br />
documents from raw data retrieved from the back end.<br />
► To validate incoming XML documents sent by the supplier in reply to outgoing<br />
purchase orders generated by the customer application.<br />
Studio Site Developer provides the Create DTD wizard to take you through the<br />
process of creating a new DTD file.<br />
To create a new DTD file, you have the following options:<br />
► To generate it from scratch, select File -> New -> Other -> XML -> DTD (or<br />
use the icon).<br />
► To generate it from an existing XML schema or XML file:<br />
– From the context menu of an XML schema (.xsd) file or an XML (.xml) file<br />
in the Navigator, select Generate -> DTD.<br />
– From within an XML schema file open in the editor, select XSD -><br />
Generate DTD.<br />
– From within an XML file open in the editor, select XML -> Generate DTD.<br />
Chapter 10. Working with XML 323
XSL wizard<br />
This is a tool for creating XSL files. To create a new file from scratch, use the<br />
New XSL wizard as follows:<br />
1. Select File -> New -> XSL to launch the New XSL wizard.<br />
2. In the File name field, type your XSL file name.<br />
3. Click Finish. The XSL file is created and the XSL editor is automatically<br />
opened for you.<br />
XML and SQL Query wizard<br />
This wizard allows you to create an XML file with the results from an SQL query.<br />
Before you can use the wizard, you must first create a SQL query using the SQL<br />
Query builder (see “Building SQL statements using the SQL Query Builder” on<br />
page 211).<br />
Once you have created your query, you can also start the wizard from any<br />
perspective. Follow these steps to start the XML from SQL query wizard:<br />
1. Select File -> New -> Other -> XML -> XML and SQL Query, then click<br />
Next.<br />
2. Select the Create XML from SQL query radio button, then click Next.<br />
3. On the Select SQL Statements page, expand your project and select your<br />
SQL statement. Click Next.<br />
4. Complete the wizard using the options described below.<br />
5. When you have finished selecting your options, click Finish to run the XML<br />
from SQL query wizard.<br />
Specify mapping patterns<br />
The wizard allows you to choose from a number of different default patterns<br />
when mapping your relational data to an XML format. They include:<br />
► Mapping table columns as elements.<br />
► Mapping table columns as attributes.<br />
► Mapping table columns as elements using primary keys as attributes.<br />
► Mapping using foreign keys as links.<br />
The presence of foreign keys specifies a relationship between two tables. When<br />
generating XML files from a table that has a foreign key, there are two options<br />
that you can choose from:<br />
► Select Foreign keys as links only. If you select this option, the tool will map<br />
all the foreign key relationships into a single XML document. This will create a<br />
hierarchical document that reflects the foreign key relationship.<br />
324 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
10.2.3 Editors<br />
► Select Foreign keys as links, and select Recurse though foreign keys. If<br />
you select both options, the tool will map each foreign table into a separate<br />
XML document.<br />
Generate schema definition<br />
If you would like to generate a schema definition that will contain information<br />
about the structure of your XML file, select either XML Schema or DTD. If you do<br />
not need a schema definition, select None.<br />
Generate a template file<br />
Once you have unit-tested your query and the output XML documents, you may<br />
wish to generate them dynamically when running your application within the<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong>. To do this, you can save your query in a template<br />
file. For more information about using this file to dynamically create your XML<br />
documents, see “Using XML in the Online Catalog sample” on page 332.<br />
Select the Output folder<br />
Specify the folder in which you want to store the generated files. Click Browse to<br />
browse to a folder.<br />
Studio Site Developer provides you with numerous XML editors for working with<br />
XML-related files. This section will look at XML, XML schema, DTD, and XSL<br />
editors.<br />
Important: This section simply describes the different editors. For detailed<br />
information on how to use the different editors, please refer to the product<br />
help.<br />
XML editor<br />
The XML editor is a tool for creating and viewing XML files. You can use it to<br />
create new XML files, either from scratch or from existing DTDs or XML<br />
schemas. You can also use it to edit XML files, associate them with DTDs or<br />
schemas, and validate them.<br />
Chapter 10. Working with XML 325
Figure 10-4 XML editor<br />
The XML editor can be opened by double-clicking an XML file (*.xml). The XML<br />
editor provides two views for editing:<br />
► Source view: Enables you to view and work directly with the source code file.<br />
Many of the XML editing features in the XML editor Source view are very<br />
similar to those available in the Source view of Page Designer.<br />
The Source view has several text editing features, such as syntax<br />
highlighting, unlimited undo/redo, and user-defined macros. Another helpful<br />
feature is content assist, which uses the information in a DTD or schema<br />
content model to provide a list of acceptable continuations, depending on<br />
where the cursor is located in an XML file, or what has just been typed.<br />
The XML editor Source view also includes a “smart” double-clicking behavior.<br />
If your cursor is placed in an attribute value, one double-click selects that<br />
value, another double-click selects the attribute-value pair, and a third<br />
double-click selects the entire tag. This makes it easier to copy and paste<br />
commonly used pieces of XML.<br />
326 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
XML toolbar<br />
XML editor area
► Design view: Represents the XML file simultaneously as a table and a tree.<br />
This makes navigation and editing easier for you. Content and attribute<br />
values can be edited directly in the table cells, while pop-up menus on the<br />
tree nodes give alternatives that are valid for that location. For example, the<br />
Add Child menu item will list only those elements from a DTD or XML schema<br />
that would be valid children at a given point.<br />
The Design view is especially helpful if you are new to XML, or need to do<br />
form-oriented editing. For example, you could use the Create XML File wizard<br />
to create a template XML file for a job description form from a job description<br />
DTD. After those steps are completed, you would only have to fill in the form<br />
data using the Design view.<br />
Validating an XML file<br />
It is also a good idea to validate new documents created from a DTD or XML<br />
schema to make sure it is well-formed. You can do this using the options in the<br />
XML drop-down in the toolbar if the file is open. If not, you can validate it using<br />
the context menu of the .xml file in the Navigator view.<br />
XML schema editor<br />
The XML schema editor is a tool for creating, viewing, and validating XML<br />
schemas. You can use it to perform tasks such as creating XML schema<br />
components, importing and viewing XML schemas, generating DTDs and<br />
relational table definitions from XML schemas, and generating JavaBeans for<br />
creating XML instances from an XML schema.<br />
Chapter 10. Working with XML 327
Figure 10-5 Using the XML schema editor<br />
XML Schema editor area<br />
The XML schema editor can be opened by double-clicking an XML schema file<br />
(*xsd). The XML schema editor has three main views:<br />
► Graph view: You can use the Graph view to add, remove, or rearrange<br />
components in your schema.<br />
► Design view: When you select an object in the Graph view, the Design view<br />
will display the properties that are associated with that schema component<br />
object. You can use the Design view to enter values for the selected object.<br />
Tip: By default, the Design view is combined with the Source and Graph<br />
views. This can be changed by editing the XML Schema attributes in the<br />
Preferences dialog. To open the dialog, select Window -> Preferences<br />
from the main menu and then expand the XML option in the left pane and<br />
select XML Schema.<br />
► Source view: You can switch to the Source view to edit the schema source<br />
directly. The XML schema editor uses the Task view for error reporting.<br />
328 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
XML Schema toolbar<br />
Design view<br />
Source and Graph tabs
Note: For information on how to use the views mentioned above, see the<br />
<strong>WebSphere</strong> Studio Site Developer product help.<br />
The content assist (available in the Source view) will use associated XML<br />
schema, DTD, or content model information to provide intelligent assistance.<br />
Validating an XML schema file<br />
An XML schema open in the editor can be validated using the XSD drop-down<br />
menu. You can also validate an XML schema file (open or not) using the context<br />
menu of the .xsd file in the Navigator view.<br />
DTD editor<br />
The DTD editor is a tool for creating and viewing DTDs. Using the DTD editor,<br />
you can create DTDs, generate XML schema files, and generate JavaBeans for<br />
creating XML instances of an XML schema. You can also use the DTD editor to<br />
generate default HTML forms based on the DTDs you create. The DTD editor<br />
can be opened by double-clicking a DTD file (*.dtd).<br />
Figure 10-6 The DTD editor<br />
DTD toolbar<br />
DTD editor area<br />
Chapter 10. Working with XML 329
When you first create a new DTD from scratch, there are no elements in it. The<br />
DTD will open in the editor but will look blank. To work with the DTD, switch to the<br />
Design view. You will use the Outline view and Design view to build the DTD<br />
elements.<br />
Validating DTDs<br />
A DTD open in the editor can be validated using the DTD drop-down menu. You<br />
can also validate a DTD file (open or not) using the context menu of the .dtd file<br />
in the Navigator view.<br />
XSL editor<br />
The XSL editor provides a text editor to handle the source code of the XSL file. It<br />
has several text editing features, such as content assist and syntax highlighting.<br />
The content assist feature helps you in writing your XSL code, since it is aware of<br />
the proper XSL grammar rules. When editing the XSL document, content assist<br />
can be invoked to prompt you with a list of possible XSL constructs to use.<br />
Concerning the syntax highlighting feature, you will notice that whenever you<br />
select any of the XSL file components listed in the Outline view, the<br />
corresponding XSL code for that component will be selected, and vice versa.<br />
Figure 10-7 XSL editor<br />
330 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Validating the XSL file<br />
Another useful feature of the XSL editor, as in the rest of the editors, is the<br />
incremental validation feature. At any point during your development of an XSL<br />
file, you can invoke the Validate process to validate the file. Just right-click the file<br />
name in the Navigator view and select the Validate XSL File option. In addition<br />
to the manual invocation of the validation process, the validation is also<br />
automatically run when you save the document. Any validation errors will be<br />
reported in the Task view with a little red marker for the corresponding line in the<br />
source code of the XSL file.<br />
10.2.4 XML sample applications in Studio Site Developer<br />
If you are new to working with XML, an excellent way to become familiar with the<br />
process is to try out some of the sample applications shipped with Studio Site<br />
Developer.<br />
You can import the samples to your workspace with the New File wizard. Simply<br />
select New -> File -> Other -> Examples. Select the XML folder on the left and<br />
choose one of the samples.<br />
Figure 10-8 XML sample applications<br />
Chapter 10. Working with XML 331
10.3 Using XML in the Online Catalog sample<br />
To illustrate the use to XML in the Online Catalog sample, we will create a<br />
featured item page that will display all the items in the ITEM table of the<br />
SALESAPP database that have the SOTD_FLAG field set to Y. To do this, we will<br />
use the XML and SQL Query wizard and the SQLtoXML Java class.<br />
The XML and SQL Query wizard results in a single execution of the database<br />
query with the results stored in a static HTML page. This example will illustrate<br />
the use of the SQLtoXML Java class shipped with Studio Site Developer in a<br />
servlet to create dynamic content that is executed upon user request. The XML<br />
and SQL Query wizard is used first to generate the XSL and XST files used by<br />
the servlet.<br />
To create the featured item page, we will step through the following process:<br />
1. Create an SQL statement.<br />
2. Generate XSL and XST (query template) files using the SQL to XML wizard.<br />
3. Set the classpath variables for the project.<br />
4. Add the required libraries to the project build path.<br />
5. Create a servlet that will be used to dynamically create our page content.<br />
6. Add a page to the Web site diagram.<br />
When everything is complete, the user will simply click a link on the index.html<br />
page that will open the Featured Item page and display all the featured items in<br />
our database. The diagram below illustrates the flow of the different components<br />
in this process.<br />
home page<br />
XST file<br />
calls<br />
Servlet<br />
ITEM table<br />
requests queries<br />
creates<br />
Figure 10-9 Flow diagram for XML component of sample<br />
332 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
XML and XSL strings<br />
transforms<br />
HTML string<br />
(output to user)
1. To begin, the user will click a link from the home page (index.html) that will<br />
invoke the servlet.<br />
2. The servlet will request the XST file query and database connection<br />
information.<br />
3. With this information, the servlet will connect to the ITEM table and query the<br />
required data.<br />
4. The servlet will then use the queried information to generate an XML and XSL<br />
string.<br />
5. Using the data in these strings, the servlet transforms it to an HTML string<br />
and then displays the HTML string to the user via an HTML page.<br />
Step 1: Creating an SQL statement<br />
To start, we need to create an SQL statement to retrieve all the items for the<br />
database that have the SOTD_FLAG field set to Y. This statement will be used by<br />
the SQL to XML wizard to create the XML related files.<br />
Note: These instructions assume that you have connected to the SALESAPP<br />
database from Studio Site Developer and have imported the design to the<br />
project. This was done in Chapter 6, “Accessing databases” on page 153. If<br />
you have not made this connection yet, you can still go through the example,<br />
though the step-by-step instructions will not match exactly.<br />
If your project doesn’t have a database folder yet (no database connection has<br />
been made), you can right-click the Web project and select New -> Other -><br />
Data -> SQL Statement. This wizard will also give you the option to create the<br />
database connection. When asked for a folder for the statement, browse to the<br />
WEB-INF folder. The databases folder will be created under this folder for you.<br />
The method to build the statement will vary somewhat from these instructions,<br />
but the wizards make it easy to follow.<br />
1. Open the Data perspective and navigate to the<br />
OnlineCatalog/WebContent/WEB-INF/databases/SALESAPP/Statements<br />
folder in the Data Definition view. Right-click the Statements folder and click<br />
New -> Select Statement from the context menu.<br />
2. In the New Select Statement dialog, enter FeaturedItem as the statement<br />
name.<br />
3. Click OK. The SQL Query Builder opens.<br />
4. Use the SQL Query Builder tools (see 6.2.10, “Building SQL statements using<br />
the SQL Query Builder” on page 211) to build the following SQL statement, or<br />
simply type it in to the Source window.<br />
Chapter 10. Working with XML 333
Example 10-1 FeaturedItem SQL statement<br />
SELECT<br />
DB2ADMIN.ITEM.ITEM_SHORT_DESC AS NAME,<br />
DB2ADMIN.ITEM.ITEM_LONG_DESC AS DESCRIPTION,<br />
DB2ADMIN.ITEM.PRICE AS PRICE<br />
FROM<br />
DB2ADMIN.ITEM<br />
WHERE<br />
DB2ADMIN.ITEM.SOTD_FLAG = 'Y'<br />
ORDER BY<br />
PRICE ASC<br />
The statement above selects the item_short_desc, item_long_desc, and price<br />
fields from the item table and sets the field names as Name, Description, and<br />
Price respectively. The items are selected on the condition that they have the<br />
sotd_flag field set to Y. This field is an indicator to us that the item has been<br />
entered or modified in the table as a featured item.<br />
5. With the SQL statement entered in the SQL Source window, the editor should<br />
look something like the following figure.<br />
334 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 10-10 SQL statement editor with SQL inserted<br />
6. Close the builder and save the statement.<br />
Step 2: Using the XML and SQL Query wizard<br />
With the SQL statement completed, we can now use the SQL to XML wizard to<br />
create the XSL and XST files that we will need later in the sample.<br />
1. Open the Web perspective and switch to the Project Navigator view.<br />
2. Navigate to the WebContent folder, right-click it, and select New -> Folder<br />
from the context menu.<br />
3. Enter featured_item as the folder name and click Finish.<br />
4. Navigate to the featured_item folder, right-click it, and select New -> Other<br />
from the context menu.<br />
5. In the left pane of the New dialog, select XML and then select XML and SQL<br />
Query from the right pane.<br />
6. Click Next.<br />
Chapter 10. Working with XML 335
7. On the next page, select the Create XML from SQL query radio button and<br />
click Next.<br />
8. On the next page, navigate to the<br />
OnlineCatalog/WebContent/WEB-INF/databases/SALESAPP/Statements<br />
folder and select the FeaturedItem file. This is the SQL statement that we<br />
created in the previous step.<br />
Figure 10-11 Select SQL Statements page<br />
9. Click Next.<br />
10.On the next page:<br />
– Verify that the Elements radio button has been selected as the Show table<br />
columns as option.<br />
– Verify that the None radio button has been selected as the Generate<br />
schema definition as option.<br />
– Ensure the Generate query template file check box is selected and the<br />
output folder is set to /OnlineCatalog/WebContent/featured_item.<br />
336 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 10-12 XML From an SQL Query page<br />
11.Click Finish. Four files will be added to the featured_item folder:<br />
– FeaturedItem.html - This file will not be used in the sample and can be<br />
deleted.<br />
– FeaturedItem.xml - This file will not be used in the sample and can be<br />
deleted.<br />
– FeaturedItem.xsl - This file will be used within a servlet to dynamically<br />
create the XSL output. It contains the data on how the HTML output<br />
should be rendered.<br />
Example 10-2 FeaturedItem.xsl<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Chapter 10. Working with XML 337
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
NAME<br />
DESCRIPTION<br />
PRICE<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
– FeaturedItem.xst - This file is requested by the servlet to retrieve the SQL<br />
query. It is a query template file that contains the logon and query<br />
information from the SQL statement we created earlier; see the example<br />
below.<br />
Example 10-3 FeaturedItem.xst<br />
<br />
<br />
338 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
<br />
db2admin<br />
<br />
COM.ibm.db2.jdbc.app.DB2Driver<br />
jdbc:db2:SALESAPP<br />
<br />
<br />
<br />
<br />
<br />
GENERATE_AS_ELEMENTS<br />
FALSE<br />
<br />
<br />
Step 3: Setting the classpath variables for the project<br />
The SQLTOXML, WAS_V5_XALAN, and XERCES classpath variables need to<br />
be set for the project. Switching to the XML perspective automatically initializes<br />
these variables.<br />
To verify that the classpath variables have been set:<br />
1. Switch to the XML perspective.<br />
2. Select Window -> Preferences from the main menu.<br />
3. Select Java -> Classpath Variables.<br />
4. Scroll down the displayed list and locate the three variables.<br />
Step 4: Adding the required libraries to the project build path<br />
The SQLTOXML, WAS_V5_XALAN, and XERCES libraries need to be added to<br />
the Java build path for the OnlineCatalog project. Since the libraries are already<br />
variables in the classpath, you can simply add the variable to the libraries list for<br />
the project. This method of adding JAR files means that the paths are not hard<br />
coded and therefore can be relocated.<br />
1. Open the Web perspective.<br />
2. In the Project Navigator view, right-click the OnlineCatalog project and select<br />
Properties from the context menu.<br />
3. Click the Java Build Path node from the menu on the left to display the Java<br />
Build Path options on the right.<br />
4. Select the Libraries tab. Any libraries already in the project build path are<br />
listed here.<br />
Chapter 10. Working with XML 339
Figure 10-13 Libraries tab<br />
5. Click Add Variable....<br />
6. Scroll down until you see the SQLTOXML variable and select it.<br />
Figure 10-14 New variable classpath entry dialog<br />
340 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
7. Click OK. Repeat this process for the XERCES and WAS_V5_XALAN<br />
variables.<br />
8. Now all the libraries you need have been added to the Java Build Path for the<br />
OnlineCatalog project.<br />
9. Click OK.<br />
Step 5: Creating the servlet<br />
With the classpath variables and Java build paths in place, we can create the<br />
servlet that will be used to dynamically create the featured item page. To begin,<br />
we will use the Servlet wizard to create a generic servlet and then we will add<br />
some code to it.<br />
1. Open the Web perspective and navigate to the JavaSource folder of the<br />
OnlineCatalog project.<br />
2. Right-click the folder and select New -> Servlet from the context menu.<br />
3. Enter featureditem as the Java package FeaturedItemXMLServlets as the<br />
class name.<br />
Figure 10-15 Servlet wizard - 1<br />
4. Click Next.<br />
Chapter 10. Working with XML 341
5. Verify that the Public modifier is the only one selected and that no method<br />
stubs are selected. Remove the javax.servlet.Servlet interface by selecting it<br />
from the Interfaces listbox and clicking Remove.<br />
Figure 10-16 Servlet wizard - 2<br />
6. Click Next.<br />
7. Select the Add to web.xml check box and verify that the URL Mapping value<br />
is set to /FeaturedItemXMLServlet.<br />
8. Click Finish. The FeaturedItemXMLServlet.java file will be opened in the Java<br />
editor.<br />
342 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 10-17 FeaturedItemXMLServlet.java<br />
Notice that the featureditem package has been added to the JavaSource<br />
folder for the project and that the FeaturedItemXMLServlet has been added to<br />
the package.<br />
We are now ready to add some logic to our servlet to enable it to retrieve the<br />
database connect and SQL query information from the FeaturedItem.xst file, and<br />
also add the logic to dynamically create an XML and XSL string, then transform<br />
the content of these two strings into an HTML string which will eventually be<br />
displayed to the user.<br />
1. With the FeaturedItemXMLServlet.java file still opened in the Java editor,<br />
copy the code from the example below into the servlet. There are comments<br />
throughout the code, so please read through it to get a better understanding<br />
of what is being done. Note that you will need to modify the code that points to<br />
the .xst file to reflect the location of your workspace.<br />
Example 10-4 FeaturedItemXMLServlet.java<br />
package featureditem;<br />
import javax.servlet.http.*;<br />
import java.io.*;<br />
Chapter 10. Working with XML 343
import java.util.*;<br />
import java.net.URLEncoder;<br />
import java.sql.Connection;<br />
import com.ibm.etools.sqltoxml.*;<br />
import javax.xml.transform.TransformerFactory;<br />
import javax.xml.transform.Transformer;<br />
import javax.xml.transform.stream.StreamSource;<br />
import javax.xml.transform.stream.StreamResult;<br />
/*<br />
* Sample servlet to show a typical use of SQLToXML runtime library.<br />
* 1. Retrieves query file name (.xst) and optional where clause parameters.<br />
* 2. Builds XML and default XSL streams from the query result.<br />
* 3. Generates HTML response to the client.<br />
*<br />
* In case where the format option is GENERATE_ID_AND_IDREF and RECURSE<br />
* is true, this servlet does some interesting thing so explore.<br />
*<br />
* If you want to use your own connection, then you can create your own<br />
* (possible from a connection pool) and provide it to SQLToXML. As an<br />
* example, see XMLConnectionPoolServlet.java.<br />
*/<br />
public class FeaturedItemXMLServlet extends HttpServlet<br />
{<br />
private String SERVLET = null;<br />
/*<br />
* This method will be called by the servlet engine. It is quite long so<br />
* be prepared but the logic is pretty simple. I could have used instance<br />
variables<br />
* instead to reduce the lines but then I did not what to put too much time<br />
on<br />
* dealing with the thread-safe issues on this sample program.<br />
*/<br />
public void service(HttpServletRequest req, HttpServletResponse res)<br />
throws IOException<br />
{<br />
if (SERVLET == null)<br />
{<br />
String contextPath = req.getContextPath();<br />
SERVLET = contextPath + "/servlet/FeaturedItemXMLServlet";<br />
}<br />
res.setContentType("text/html");<br />
PrintWriter response = res.getWriter();<br />
/*<br />
* Getting the parameters from the request:<br />
* xstFile : Query file name (.xst).<br />
344 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
* params (optional) : Values to be used for where clause in the query.<br />
* query (optional) : Will override the query sting in the xstFile.<br />
*/<br />
//Sets the location of the xst file - the directory path will need to be<br />
changed for you system<br />
String xstFile = "/Documents and Settings/bogers/My<br />
Documents/<strong>IBM</strong>/wasexpress51/workspace/OnlineCatalog/WebContent/featured_item/Fea<br />
turedItem.xst";<br />
if (xstFile == null)<br />
error(response, new Exception("xstFile parameter is not specfied."));<br />
String params = getParameter(req,"params");<br />
String query = getParameter(req,"query"); // if recursive query mode<br />
/*<br />
* Generate XML and XSL streams from the query<br />
*/<br />
try<br />
{<br />
QueryProperties prop = new QueryProperties();<br />
prop.load(xstFile);<br />
if (query != null) // Recursive & ID_AND_IDREF query mode<br />
prop.setStatement(query); // Override the previous query<br />
SQLToXML sql2xml = new SQLToXML(prop);<br />
ByteArrayOutputStream baosXML = new ByteArrayOutputStream();<br />
PrintWriter xmlWriter = new PrintWriter(baosXML);<br />
//ByteArrayOutputStream baosXSL = new ByteArrayOutputStream(); //Not used<br />
in our sample<br />
//PrintWriter xslWriter = new PrintWriter(baosXSL); //Nnot used in our<br />
sample<br />
Connection conn =<br />
getConnection(prop.getLoginId(),prop.getPassword(),response);<br />
if (conn != null)<br />
sql2xml.setConnection(conn); // You are using your own connection<br />
sql2xml.setParameters(params); // null is ok when the query does not<br />
contain where clause<br />
sql2xml.setXMLWriter(xmlWriter); // Generate XML<br />
//sql2xml.setXSLWriter(xslWriter); // Generate default XSL - Not used in<br />
our sample<br />
sql2xml.execute();<br />
Chapter 10. Working with XML 345
Placeholder for xslContent<br />
//<br />
//Adding contents of baoxXML and xslContent to the html string<br />
String html = genHTML(baosXML.toString(),xslContent);<br />
//baosXSL.toString() could be used instead of xslContent if allowing the<br />
servlet to create the XSL string at runtime<br />
/*<br />
* Interesting part begins:<br />
* if we are in Recursive & ID_AND_IDREF query mode, the result html<br />
* string contains one XSLWriter.TITLE_HREF and many<br />
XSLWriter.CONTENT_HREF<br />
* depending on the number of rows found. We need to replace these<br />
strings<br />
* with the actual queries to be used before sending the html to the<br />
client.<br />
*/<br />
if (prop.getRecurse() &&<br />
prop.getFormat().equals(SQLGenerateOptions.GENERATE_ID_AND_IDREF))<br />
{<br />
String base = SERVLET + "?"; // servlet url<br />
base += "xstFile=" + xstFile; // query file<br />
base += "&query="; // query to override in the query file<br />
// Used for HTML table header foreign key column<br />
String queryNextAll = sql2xml.getNextAllQuery();<br />
if (queryNextAll != null)<br />
{<br />
// You need to encode the query string if the client is Netscape.<br />
String headerHref = base + URLEncoder.encode(queryNextAll);<br />
// Used for foreign key column values<br />
Vector queries = sql2xml.getNextQueries();<br />
Vector hrefs = new Vector();<br />
if (queries != null)<br />
{<br />
String q;<br />
String href;<br />
for(int i=0; i
}<br />
}<br />
// Substitute relevant href symbols in html (from the above)<br />
// with the href strings we just built.<br />
html = substitute(html,XSLWriter.TITLE_HREF,headerHref);<br />
for (int i=0; i
if (paramValues != null)<br />
paramValue = paramValues[0];<br />
return paramValue;<br />
}<br />
// Generate a HTML page with the error message.<br />
protected void error(PrintWriter writer, Exception e)<br />
{<br />
writer.println("");<br />
writer.println("Error");<br />
writer.println("");<br />
writer.println(" " + e + "");<br />
writer.println("");<br />
writer.println("");<br />
}<br />
// This method can be overriden if you want to use your own connection.<br />
protected Connection getConnection(String uid, String password, PrintWriter<br />
pw)<br />
{<br />
return null; // Let SQLToXML generate one for us.<br />
}<br />
// Take XML and XSL string to transform and return the result HTML string.<br />
private String genHTML(String xml, String xsl)<br />
throws Exception<br />
{<br />
ByteArrayOutputStream baosHTML = new ByteArrayOutputStream();<br />
TransformerFactory tFactory = TransformerFactory.newInstance();<br />
Transformer transformer =<br />
tFactory.newTransformer(new StreamSource(new StringReader(xsl)));<br />
transformer.transform (<br />
new StreamSource(new StringReader(xml)),<br />
new StreamResult(baosHTML));<br />
String html = baosHTML.toString();<br />
baosHTML.close();<br />
return html;<br />
}<br />
}<br />
2. After you enter the code above into the servlet, you will notice that there is an<br />
error on the page indicating that the variable xslContent cannot be resolved.<br />
This brings us to our next step. We need to insert some code into the servlet<br />
that sets the value of xslContent. This string variable will contain the code<br />
348 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
equired to create the XSL string for creating the HTML. The process of<br />
creating the HTML also requires an XML file, but we allow the servlet to<br />
dynamically create it for us.<br />
ByteArrayOutputStream baosXML = new ByteArrayOutputStream();<br />
PrintWriter xmlWriter = new PrintWriter(baosXML);<br />
If we wanted to, we could have allowed the servlet to create the XSL string at<br />
runtime, but the output of the HTML would have been very basic. You will<br />
notice in the example above that there are a few bolded lines of code. If you<br />
remove the comments on these lines and change String html =<br />
genHTML(baosXML.toString(),xslContent); to read with baosXSL.toString()<br />
instead of xslContent, the servlet will create the XSL for you. For our sample,<br />
we wanted to add some style to our output and therefore are setting the value<br />
of the XSL string.<br />
3. Find the following comments in the servlet:<br />
//Placeholder for xslContent<br />
//<br />
This is the area of the servlet where we are going to add the code to create<br />
the xslContent string.<br />
4. Remove the two comments and add the code from the example below.<br />
Example 10-5 xslContent<br />
//Manually creating the xsl file - the xsl content was taken from an xsl file<br />
created using the Studio wizards<br />
//This is the start of the xsl<br />
String xslContent = "";<br />
xslContent += "";<br />
xslContent += "";<br />
xslContent += "";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
//Adding a link to the blue.css file<br />
xslContent +="";<br />
//Continuation of xsl<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
Chapter 10. Working with XML 349
xslContent += "";<br />
xslContent += "";<br />
xslContent +="Featured Item"; //Title has been added to page with CSS class<br />
associated<br />
xslContent +="";<br />
xslContent +=""; //Added width to table and<br />
removed border<br />
xslContent +="";<br />
xslContent +="NAME"; //Added<br />
width to cell and associated a CSS class<br />
xslContent +="DESCRIPTION";<br />
//Added width to cell and associated a CSS class<br />
xslContent +="PRICE"; //Added<br />
width to cell and associated a CSS class<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent +="";<br />
xslContent += "";<br />
xslContent += "";<br />
If you open the FeaturedItem.xsl file we created earlier, you will notice that the<br />
code above and the XSL code are very similar. We added a link to a CSS file,<br />
a few CSS class references, table enhancements, and text additions<br />
(indicated in bold).<br />
350 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Important: If you are using the Online Catalog sample from the <strong>IBM</strong><br />
<strong>Redbooks</strong> site, you will notice that the FeaturedItemXMLServlet contains<br />
additional lines of code for the xslContent string. We did this because we<br />
wanted to incorporate our template into the HTML output.<br />
Importing the SQLToXML jar file<br />
At runtime, the SQLToXML jar file will be needed to access objects in the servlet.<br />
To be available, it needs to be placed in the WEB-INF\lib folder of the project.<br />
1. Open the Web perspective.<br />
2. While in the Project Navigator view navigate to the<br />
OnlineCatalog/WebContent/WEB-INF directory and select the lib folder.<br />
3. Select File > Import from the main menu and then select File system from<br />
the Import dialog.<br />
4. Click Next.<br />
5. Browse to<br />
\wstools\eclipse\plugins\com.ibm.etools.sqltoxml_5.1\jars.<br />
6. Click OK.<br />
7. Expand the jars tree, then select the sqltoxml.jar check box.<br />
8. Set the destination folder to be OnlineCatalog/WebContent/WEB-INF/lib.<br />
9. Click Finish. The JAR file appears in the<br />
OnlineCatalog/WebContent/WEB-INF/lib directory. Your application server will<br />
need to be restarted before your changes take effect.<br />
Step 6: Adding a page to the Web site diagram<br />
With the FeaturedItemXMLServlet servlet completed, we can add a link to the<br />
index.html page of our application that will call the servlet and then output the<br />
featured item list.<br />
1. Open the Web perspective.<br />
2. Expand the OnlineCatalog project and open the Web site diagram editor by<br />
double-clicking Web Site Configuration.<br />
3. Right-click the index.html page diagram icon and select Add New Page -> As<br />
Child from the context menu. This adds a new page icon to the diagram.<br />
4. Change the Navigation Label from newpage to Featured Item.<br />
5. Double-click the Featured Item page diagram icon and enter the page value of<br />
FeaturedItemXMLServlet. This is the URL mapping value that we specified<br />
when the servlet was created.<br />
Chapter 10. Working with XML 351
Figure 10-18 Web site diagram<br />
6. Close the Web site diagram editor and save your changes.<br />
Summary<br />
Now you are ready to run the application. When the Featured Item link is<br />
selected from the navigation bar, the FeaturedItemXMLServlet will be executed<br />
and you will see a display of the featured items in the item table. The figure below<br />
shows a screenshot of the output with the template applied to it.<br />
352 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 10-19 Featured item output<br />
10.4 For more information<br />
For more information, see the following:<br />
► <strong>WebSphere</strong> Studio <strong>Application</strong> Developer Programming Guide, SG24-6585<br />
► The XML Files: Development of XML/XSL <strong>Application</strong>s Using <strong>WebSphere</strong><br />
Studio V5, SG24-6586<br />
Chapter 10. Working with XML 353
354 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
11<br />
Chapter 11. Working with Web services<br />
Our objective in this chapter is to introduce the Web services technology and the<br />
support provided for it by <strong>WebSphere</strong> Studio Site Developer. This chapter will<br />
discuss the following:<br />
► Web services overview<br />
► Studio Site Developer support for Web services<br />
► Using Web services in the Online Catalog sample<br />
Important: This chapter address the topic of Web service consumption. If you<br />
are looking for information on Web service development, please see the<br />
redbook <strong>WebSphere</strong> Studio <strong>Application</strong> Developer V5 Programming Guide,<br />
SG24-6957.<br />
© Copyright <strong>IBM</strong> Corp. 2003 355
11.1 Web services overview<br />
What is a Web service? As you might already have observed, Web service has<br />
recently become one of the highly overloaded terms in the IT industry. In this<br />
publication, we use the following widely accepted definition: Web services are<br />
self-contained, self-describing, modular applications that can be published,<br />
located, and invoked across the Web.<br />
Let us further explain the information contained in this definition.<br />
Web services are self-contained<br />
On the client side, no additional software is required. A programming language<br />
with XML and HTTP client support is enough to get you started.<br />
On the server side, a Web server and a servlet engine are required. It is possible<br />
to Web service enable an existing application without writing a single line of<br />
code.<br />
Web services are self-describing<br />
Neither the client nor the server knows or cares about anything besides the<br />
format and content of request and response messages (loosely-coupled<br />
application integration).<br />
The definition of the message format travels with the message; no external<br />
metadata repositories or code generation tools are required.<br />
Web services can be published, located, and invoked<br />
Some additional standards that are required to do so are:<br />
► Simple Object Access Protocol (SOAP), also known as service-oriented<br />
architecture protocol, an XML-based remote procedure call (RPC) and<br />
messaging protocol<br />
► Web Service Description Language (WSDL), a descriptive interface and<br />
protocol binding language<br />
► Universal Description, Discovery, and Integration (UDDI), a registry<br />
mechanism that can be used to look up Web services descriptions<br />
In this chapter we introduce each of these technologies.<br />
Web services are language independent and interoperable<br />
Client and server can be implemented in different environments. Existing code<br />
does not have to changed in order to have the Web service enabled.<br />
356 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Web services are inherently open and standards based<br />
XML and HTTP are the technical foundation for Web services. A large part of the<br />
Web service technology has been built using open source projects. Therefore,<br />
vendor independence and interoperability are realistic goals.<br />
Web services are dynamic<br />
Dynamic e-business can become reality using Web services because, with UDDI<br />
and WSDL, the Web service description and discovery can be automated.<br />
Web services build on proven mature technology<br />
There are a lot of commonalities, as well as a few fundamental differences to<br />
other distributed computing frameworks. For example, the transport protocol is<br />
text based and not binary.<br />
Let us now introduce the overall architecture of the Web services technology<br />
framework.<br />
11.1.1 The concept of a service-oriented architecture (SOA)<br />
Each component in a service-oriented architecture can play one (or more) of<br />
three roles: service provider, broker, and requestor, which perform the<br />
operations shown in Figure 11-1 on page 358.<br />
Chapter 11. Working with Web services 357
Service<br />
Requestor<br />
Internet<br />
Figure 11-1 Web services roles and operations<br />
1. The service provider creates a Web service and possibly publishes its<br />
interface and access information to the service registry.<br />
Each provider must decide which services to expose, how to make trade-offs<br />
between security and easy availability, and how to price the services (or, if<br />
they are free, how to exploit them for some other value). The provider also has<br />
to decide what category the service should be listed in for a given broker<br />
service and what sort of trading partner agreements are required to use the<br />
service.<br />
2. The service broker (also known as the service registry) is responsible for<br />
making the Web service interface and implementation access information<br />
available to any potential service requestor.<br />
The implementers of a broker have to make a decision about the scope of the<br />
broker. Public brokers are available all over the Internet, while private brokers<br />
are only accessible to a limited audience, for example, users of a<br />
company-wide intranet. Furthermore, the width and breadth of the information<br />
offered has to be decided. Some brokers will specialize in breadth of listings.<br />
Others will offer high levels of trust in the listed services. Some will cover a<br />
broad landscape of services and others will focus on a given industry. Brokers<br />
358 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
2<br />
3<br />
Service<br />
Broker<br />
1<br />
Legacy<br />
system<br />
Service<br />
Provider
will also arise that simply catalog other brokers. Depending on the business<br />
model, a broker may attempt to maximize look-up requests, number of<br />
listings, or accuracy of the listings.<br />
3. The service requestor locates entries in the broker registry using various<br />
find operations and then binds to the service provider in order to invoke one of<br />
its Web services.<br />
One important issue for users of services is the degree to which services are<br />
statically chosen by designers compared to those dynamically chosen at<br />
runtime. Even though most initial usage is largely static, any dynamic choice<br />
opens up the issues of how to choose the best service provider and how to<br />
assess quality of service. Another issue is how the user of services can<br />
assess the risk of exposure to failures of service suppliers.<br />
11.1.2 Web services approach for an SOA architecture<br />
Web services are a rather new technology that implements the service-oriented<br />
architecture. A major focus during the development of this technology was put on<br />
the goal of making functional building blocks accessible over standard Internet<br />
protocols that are independent from platforms and programming languages.<br />
Web services are self-contained, modular applications that can be described,<br />
published, located, and invoked over a network. Web services perform<br />
encapsulated business functions, ranging from simple request-reply to full<br />
business process interactions.<br />
These services can be new applications or just wrapped around existing legacy<br />
systems to make them network-enabled. Services can rely on other services to<br />
achieve their goals.<br />
The core technologies used for Web services are as follows.<br />
► XML (eXtensible Markup Language) is the markup language that underlies<br />
most of the specifications used for Web services. XML is a generic language<br />
that can be used to describe any kind of content in a structured way,<br />
separated from its presentation to a specific device.<br />
► SOAP (formerly referred to as Simple Object Access Protocol, or<br />
Service-Oriented Architecture Protocol; in fact, like JDBC, it is no longer an<br />
acronym) is a network, transport, and programming language neutral protocol<br />
that allows a client to call a remote service. The message format is XML.<br />
► WSDL (Web services description language) is an XML-based interface and<br />
implementation description language. The service provider uses a WSDL<br />
document in order to specify the operations a Web service provides, as well<br />
as the parameters and data types of these operations. A WSDL document<br />
also contains the service access information.<br />
Chapter 11. Working with Web services 359
► UDDI (universal description, discovery, and integration) is both a client side<br />
API and a SOAP-based server implementation which can be used to store<br />
and retrieve information on service providers and Web services.<br />
Figure 11-2 provides a first glance at the relationship between the core elements<br />
of the SOA.<br />
XSD<br />
XML<br />
Metadata/vocabulary<br />
SOA Runtime<br />
Implementation<br />
Requestor<br />
Figure 11-2 Main building blocks in a SOA approach based on Web services<br />
► All elements use XML, including XML namespaces and XML schemas.<br />
► The service requestor and provider communicate with each other.<br />
► WSDL is one alternative to make service interfaces and implementations<br />
available in the UDDI registry.<br />
► WSDL is the base for SOAP server deployment and SOAP client generation.<br />
11.1.3 An introduction to SOAP<br />
UDDI<br />
(Broker)<br />
SOAP<br />
J2EE other<br />
WSDL<br />
Provider<br />
The current industry standard for XML messaging is SOAP. <strong>IBM</strong>, Microsoft, and<br />
others submitted SOAP to the W3C as the basis of the XML Protocol Working<br />
Group.<br />
360 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Service description<br />
HTTP<br />
other<br />
Runtime<br />
transports
SOAP has the following characteristics:<br />
► SOAP is designed to be simple and extensible.<br />
► All SOAP messages are encoded using XML.<br />
► SOAP is transport protocol independent. HTTP is one of the supported<br />
transports, hence, SOAP can be run over existing Internet infrastructure.<br />
► There is no distributed garbage collection. Therefore, call by reference is not<br />
supported by SOAP; a SOAP client does not hold any stateful references to<br />
remote objects.<br />
► SOAP is operating system independent and not tied to any programming<br />
language or component technology. It is object model neutral.<br />
Due to these characteristics, it does not matter what technology is used to<br />
implement the client, as long as the client can issue XML messages. Similarly,<br />
the service can be implemented in any language, as long as it can process XML<br />
messages.<br />
Overview<br />
Historically, SOAP was meant to be a network and transport neutral protocol to<br />
carry XML messages. SOAP over HTTP became the premier way of<br />
implementing this protocol, to the point that the latest SOAP specification<br />
mandates HTTP support.<br />
However, conceptually there is no limit to the network protocol that can be<br />
utilized. For example, because HTTP is a transport that does not guarantee<br />
delivery and is non-transactional, SOAP messages can also be transferred by a<br />
messaging software such as MQSeries.<br />
SOAP remote procedure call (RPC) is the latest stage in the evolution of SOAP;<br />
the body of a SOAP message contains a call to a remote procedure (expressed<br />
in XML) and the parameters to pass in (again, expressed in XML).<br />
The SOAP standard specifies three aspects of XML-based message exchange.<br />
Overall message format<br />
A SOAP message is an envelope containing zero or more headers and exactly<br />
one body. The envelope is the top element of the XML document, providing a<br />
container for control information, the addressee of a message, and the message<br />
itself.<br />
Headers transport any control information such as quality of service attributes.<br />
The body contains the message identification and its parameters.<br />
Chapter 11. Working with Web services 361
Encoding rules<br />
Encoding rules define a serialization mechanism that can be used to exchange<br />
instances of application-defined data types.<br />
SOAP defines a programming language independent data type scheme based<br />
on XSD, plus encoding rules for all data types defined according to this model.<br />
RPC representation<br />
The RPC representation is a convention suited to represent remote procedure<br />
calls and the related response messages.<br />
The usage of this convention is optional. If the RPC convention is not used, the<br />
communication style is purely message oriented. When working with the<br />
message oriented style, also called document-oriented communication, almost<br />
any XML document can be exchanged.<br />
11.1.4 An introduction to WSDL<br />
If we want to find services automatically, we have to have a way to formally<br />
describe both their invocation interface and their location. The Web services<br />
description language (WSDL) 1.1 provides a notation serving these purposes.<br />
Overview<br />
WSDL allows a service provider to specify the following characteristics of a Web<br />
service:<br />
► Name of the Web service and addressing information<br />
► Protocol and encoding style to be used when accessing the public operations<br />
of the Web service<br />
► Type information: Operations, parameters, and data types comprising the<br />
interface of the Web service, plus a name for this interface<br />
A WSDL specification uses XML syntax, therefore, there is an XML schema for it.<br />
A valid WSDL document consists of two parts:<br />
1. The interface part describing the abstract type interface and its protocol<br />
binding<br />
2. The implementation part describing the service access (location) information<br />
362 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
11.1.5 Web Services Invocation Framework (WSIF)<br />
The Web Services Invocation Framework is a WSDL-oriented Java API that<br />
allows you to invoke Web services dynamically, regardless of what format the<br />
service is implemented in or what mechanism is used to access it.<br />
WSIF is transport agnostic, thus a single WSIF client can support multiple<br />
runtime protocols simultaneously, such as SOAP, a direct HTTP connection, and<br />
a local Java call. For more information on WSIF see:<br />
http://www-106.ibm.com/developerworks/webservices/library/ws-wsif.html<br />
UDDI overview<br />
UDDI stands for universal description, discovery, and integration. UDDI is a<br />
technical discovery layer. It defines:<br />
► The structure for a registry of service providers and services<br />
► The API that can be used to access registries with this structure<br />
► The organization and project defining this registry structure and its API<br />
UDDI is a search engine for application clients rather than human beings;<br />
however, there is a browser interface for human users as well.<br />
UDDI is not a full business-oriented discovery or directory service; it operates on<br />
the technical level. The core information model is defined in an XML schema that<br />
can be found at:<br />
http://www.uddi.org/schema/uddi_v1.xsd<br />
Note that UDDI is an organization currently supported by more than seventy<br />
companies, but not a standards body. It works closely with organizations such as<br />
the W3C, however.<br />
UDDI registry structure<br />
The following entities comprise the core of the UDDI data model:<br />
Business entity Business entities are the white and yellow pages of the<br />
registry. Business entities provide business information<br />
about a service provider such as business name, contacts,<br />
description, identifiers, and categories.<br />
Business service A business service is a descriptive container used to group a<br />
set of Web services related to a business process or group<br />
of services. Categorization is available on this level. A<br />
business service maps to a WSDL service.<br />
Binding template These are the technical Web service descriptions relevant for<br />
application developers who want to find and invoke a Web<br />
Chapter 11. Working with Web services 363
service. A binding template points to a service<br />
implementation description (for example, a URL). This entity<br />
is sometimes also called access locator. A binding template<br />
maps to a WSDL port.<br />
tModel A tModel is a technical fingerprint, holding metadata about<br />
type specifications as well as categorization information. Its<br />
attributes are key, name, optional description, and URL. The<br />
simplest tModel contains some text characterizing a service.<br />
A tModel points to a service interface description (for<br />
example, through a URL). The type specification itself, which<br />
can be a WSDL document or any other formal specification,<br />
is not part of the UDDI model. This entity is sometimes also<br />
called service type.<br />
Figure 11-3 displays this data model with the entities introduced above. It also<br />
shows their relationships and the link to the WSDL level.<br />
UDDI<br />
contains<br />
points to<br />
WSDL<br />
Business<br />
Service<br />
Binding<br />
Template 1<br />
Implementation<br />
Document<br />
Figure 11-3 UDDI entities and their relationships<br />
The business entity tops the containment hierarchy, containing one or more<br />
business service entities and in turn binding template entities. The tModel<br />
instances (service types) are not contained by the business entity, but referenced<br />
by the binding template entities.<br />
364 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
n<br />
1<br />
n<br />
1<br />
0..1<br />
1<br />
Business<br />
Entity<br />
find<br />
n<br />
m<br />
n 1<br />
import<br />
tModel<br />
(ServiceType)<br />
n<br />
0..1<br />
Interface<br />
Document
A binding template points to an access point URL where the service can be<br />
invoked. This is a common use of the binding template, but not required. The<br />
binding template could point to a phone number as a contact point.<br />
A service type entity (tModel) has a reference to a Web service type<br />
specification, which typically is a WSDL document. Note that the UDDI registry<br />
merely contains a URL pointing to the Web site of the service provider where the<br />
document can be found, not the WSDL document itself.<br />
These references are implemented as URLs; therefore, any other specification<br />
format can easily be supported as well.<br />
UDDI API overview<br />
The UDDI programming API provides publishing and inquiry features.<br />
The inquiry API supports the following operations:<br />
► Find a business entity through its Universal Unique Identifier (UUID).<br />
► Find a business entity through a wild-carded name.<br />
► Find a business entity through categorization information.<br />
► Navigation from business entity to contained services—an optional<br />
categorization parameter can be specified.<br />
► Find a service type (tModel).<br />
► Access to detailed information on the found entities.<br />
There are find_xxx and get_xxx methods for business, service, binding template,<br />
and service type (tModel).<br />
The publishing API has the following functions:<br />
► Publishing, updating, and unpublishing of business entities<br />
► Publishing, updating, and unpublishing of business services and binding<br />
templates<br />
► Publishing, updating, and unpublishing of service types (tModels)<br />
► Methods related to the individual API user—authenticating operations belong<br />
to this group of operations<br />
There are save_xxx and delete_xxx methods for the elements of the UDDI object<br />
model (business, service, binding, tModel).<br />
Chapter 11. Working with Web services 365
More information<br />
The Web site of the UDDI organization is rich in content; you can find all UDDI<br />
specifications there; for example, the data model and API for Versions 1 and 2.<br />
Moreover, there are technical white papers, a best practices section, and an<br />
informative list of frequently asked questions:<br />
http://www.uddi.org<br />
Two registries that you can take a look at are:<br />
► UDDI Business Registry<br />
http://www.ibm.com/services/uddi<br />
The UDDI Business Registry is an open, e-commerce service registry<br />
maintained by a group of companies, called operators, that have pledged to<br />
share all public information about registrants among themselves and with<br />
users of the service and to maintain interoperability among the multiple peer<br />
nodes of the UDDI service network.<br />
► <strong>IBM</strong> Test Registry<br />
http://www.ibm.com/services/uddi<br />
A registry for developers to experiment with the technology and test their<br />
services.<br />
It is worth noting that these registries use a slightly different terminology than the<br />
UDDI object model exposed to API programmers:<br />
► Business service instances are called businesses.<br />
► Business services are called services.<br />
► Binding templates are called access locators.<br />
► tModel instances are called service types.<br />
11.2 Studio Site Developer support for Web services<br />
Site Developer facilitates the following Web services development tasks to help<br />
you build and deploy Web services-enabled applications for your dynamic<br />
e-business across a broad range of software and hardware platforms used by<br />
today's businesses.<br />
► Discover — Browse the Universal Description Discovery and Integration<br />
(UDDI) business registry or a Web Services Inspection Language (WSIL)<br />
document to locate existing Web services for integration.<br />
► Create or Transform — Create Web services from existing artifacts, such as<br />
JavaBeans, Web sites that take and return data, DB2 XML Extender calls,<br />
DB2 stored procedures, and SQL queries.<br />
366 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► Build — Wrap existing artifacts as Simple Object Access Protocol (SOAP)<br />
and HTTP GET/POST-accessible services and describe them in Web<br />
Services Description Language (WSDL).<br />
► Deploy — Deploy the Web service into the <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> or<br />
Tomcat test environments.<br />
► Test — Test the Web service as it runs locally or remotely.<br />
► Develop — Generate a sample application to assist you in creating your own<br />
Web service client application.<br />
► Publish — Publish your Web services to a private or public UDDI business<br />
registry advertising your Web services so that other clients or businesses can<br />
access them.<br />
► All Web services support is based on open standards such as UDDI V2,<br />
SOAP 2.3, WSDL 1.1, and new support for WSIL 1.0.<br />
► Support Apache Axis 1.0 runtime.<br />
► WSDL Editor — This is a graphical tool for editing WSDL files and embedded<br />
XML schemas.<br />
► Enhanced Web Services Explorer — With support for discovering, browsing,<br />
invoking, and publishing WSDL.<br />
► Support for creation of WS-I compliant Web Services.<br />
► Command line tool for creation and consumption of Web services.<br />
11.2.1 Web service preferences<br />
Studio Site Developer allows you to set different Web services properties within<br />
the workbench. To set any of the Web services preferences listed below, follow<br />
these steps:<br />
1. Click Window -> Preferences to open the Preferences dialog.<br />
2. Expand Web services, and click the preference category that you want to set.<br />
3. Select the check boxes that you want to set as the default when creating your<br />
Web service.<br />
4. Click OK to apply the changes and close the Preferences notebook.<br />
Backward Compatibility<br />
The Backward Compatibility preferences enable you to use options that are<br />
compatible with previous <strong>WebSphere</strong> Studio releases. This preference only<br />
applies if you are using Web services that use the <strong>IBM</strong> SOAP runtime.<br />
Chapter 11. Working with Web services 367
Code Generation<br />
The Code Generation preferences enable you to:<br />
► Use absolute location URI for WSDL import statements<br />
► Use inline schema when generating code<br />
► Enable element-based mappings to proxy files<br />
► Map XML simple data types to java.lang wrapper classes instead of to Java<br />
primitive types<br />
This preference only applies if you are using Web services that use the <strong>IBM</strong><br />
SOAP runtime.<br />
Dialogs<br />
The Dialogs preferences enable you to determine which dialog boxes you want to<br />
see when creating your Web service.<br />
JDBC Drivers<br />
The JDBC Drivers preferences enables you to add JAR files for additional JDBC<br />
drivers. This is used only by the DADX validation code on Linux.<br />
Resource Management<br />
The Resource Management preferences enable you to determine the defaults<br />
that you want to use when creating your Web service.<br />
Scenario Defaults<br />
The Scenario Defaults preferences enable you to determine the defaults that you<br />
want to use when creating your Web service.<br />
SOAP Transports<br />
Select your default transport: SOAP over HTTP or SOAP over JMS. This<br />
preference only applies if you are using Web services that use the <strong>WebSphere</strong><br />
5.0.2 runtime.<br />
Web Services Explorer<br />
The Web Services Explorer preferences allow you to select whether or not to<br />
ignore schemas for SOAP arrays.<br />
WS-I Compliance<br />
The WS-I Compliance preferences allow you to select your level of compliance<br />
with the WS-I Basic Protocol. This preference only applies if you are using Web<br />
services that use the <strong>WebSphere</strong> 5.0.2 runtime.<br />
368 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
11.2.2 Wizards<br />
11.2.3 WSDL editor<br />
Studio Site Developer provides wizards that support the following Web services<br />
development activities. All of these wizards can be accessed by selecting File -><br />
New -> Other from the main menu and then selecting the Web Services node<br />
from the New dialog.<br />
► Create a Web service client. The wizard assists you in generating a JavaBean<br />
proxy and a sample application. The generated JavaBean proxy provides a<br />
remote procedure call interface to the Web service and the sample Web<br />
application shows how to code the proxy file.<br />
► Create a Web service. The wizard lets you create and publish Web services<br />
that are created from JavaBeans, DADX files, and URLs.<br />
► Create DADX files. The wizard helps with the creation of a DADX file from<br />
either SQL queries or a DAD file, which is a user-specified file that provides<br />
control over the mapping of XML document elements to database columns for<br />
querying and updating.<br />
DADX is an XML document format that specifies how to create a Web service<br />
using a set of operations that are defined by DAD documents and SQL<br />
statements. A DADX Web service enables you to wrap DB2 Extender or<br />
regular SQL statements inside a standard Web service. The DADX file<br />
defines the operations available to the DADX runtime environment, and the<br />
input and output parameters for the SQL operation. The DADX Web service is<br />
deployed into a DADX group.<br />
► Create a DADX group configuration. The Web Services DADX Group<br />
Configuration wizard assists you in creating a DADX group. The DADX group<br />
contains connection information (JDBC and JNDI) and other information that<br />
is shared between DADX files within the group. Once you have created a<br />
DADX group, use the Web Service wizard to create a new Web service.<br />
► Create JavaBeans for XML schema. The wizard enables you to generate<br />
JavaBeans from schema.<br />
► Create WSDL files. The wizard helps you create an empty WSDL file. The<br />
WSDL file can be modified using the WSDL editor.<br />
Important: For additional information about each of these wizards please<br />
refer to the Studio Site Developer help documentation.<br />
<strong>WebSphere</strong> Studio provides a WSDL editor for creating, modifying, viewing, and<br />
validating WSDL files. The WSDL editor can be opened by double-clicking a<br />
WSDL file from the navigator views in the workbench.<br />
Chapter 11. Working with Web services 369
Using the WSDL editor, you can do the following:<br />
► Create new WSDL files<br />
► Validate and edit WSDL files<br />
► Import existing WSDL files for structured viewing<br />
► Generate documentation from a WSDL document.<br />
Figure 11-4 WSDL editor<br />
11.2.4 Web Services Explorer<br />
The Web Services Explorer is a Web application that supports the publication,<br />
discovery, and maintenance of business entities, business services, and service<br />
interfaces.<br />
Use the Web Services Explorer to do any of the following tasks:<br />
► Add a registry to the Web Services Explorer<br />
► Add a registry, business entity, business service, service interface, WSIL, or<br />
WSDL service to Favorites<br />
► Discover a Web service<br />
370 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
WSDL editor
► Publish a business entity to a registry<br />
► Publish a business service to a registry<br />
► Remove a business entity, business service, or service interface from a<br />
registry<br />
► Update a business entity, business service, or service interface<br />
► Manage referenced services<br />
► Manage publisher assertions<br />
► Explore and modify WSDL<br />
The Web Services Explorer is accessed by selecting Run -> Launch Web<br />
Services Explorer from the main menu of the workbench.<br />
Figure 11-5 Web Services Explorer<br />
Chapter 11. Working with Web services 371
11.3 Using Web services in the Online Catalog sample<br />
To illustrate how to incorporate an external Web service in our application, we will<br />
use the Web services client wizard. The Web service we choose performs<br />
currency conversion from one country to another for a specified amount. There<br />
are several Web services available that provide such a service, but we will use<br />
the service provided by XMethods for our sample. Once we have consumed the<br />
Web service, we will link up the associated pages to the main page of our<br />
application.<br />
11.3.1 Locating and consuming a Web service<br />
Finding Web services usually means searching the Internet for UDDI registries.<br />
In the case of our example, we will use the Web Services Explorer to locate a<br />
currency conversion Web service.<br />
1. From the main menu select Run -> Launch the Web Services Explorer.<br />
2. The Web Services Explorer opens in the Web Browser.<br />
Figure 11-6 Web Services Explorer<br />
372 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3. From the Navigator window click UDDI Main. This opens the Open Registry<br />
page in the Actions window.<br />
4. Select XMethods Registry from the Favorite Registry drop-down box.<br />
5. Click Go. This opens the Registry Details page.<br />
6. Scroll to the bottom of the page and click Find. The Find page opens.<br />
7. Enter CurrencyFind as the name of the query.<br />
8. From the Search for drop-down box select Services.<br />
9. Scroll down the page and in the Name field enter currency.<br />
10.Click Go. The Query Results page opens.<br />
11.From the list of available services click the Currency Exhange Rate link.<br />
Figure 11-7 Query results page<br />
12.The Service Details page opens and displays information about the<br />
Currency Exchange Rate service.<br />
a. Scroll to the bottom of the page and click Launch Web Service Wizard.<br />
This opens the Launch Web Service Wizard page.<br />
b. Verify that the Web Service Client radio button is selected and click Go.<br />
13.The Web Services Client wizard opens.<br />
Chapter 11. Working with Web services 373
Figure 11-8 Web services page<br />
a. Verify that the Client proxy type drop-down value is set to Java proxy.<br />
b. Select Test the generated proxy. This creates a sample that will use the<br />
Web service. The sample can be a starting point for the code in your<br />
application.<br />
c. Select Create folders when necessary. The wizard will be creating files<br />
and folders during the Web services client generation. This allows the<br />
folders to be created as you go.<br />
d. Click Next.<br />
14.On the Client Environment Configuration page you are required to select a<br />
runtime protocol and server for the client environment. In the Client-Side<br />
Environment Selection area select the Choose Web service runtime<br />
protocal first radio button. Two windows will be displayed in the lower part of<br />
the page.<br />
374 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 11-9 Client environment configuration page<br />
a. From the Web service runtime window select <strong>IBM</strong> SOAP and from the<br />
<strong>Server</strong> window, expand <strong>Server</strong> Types, <strong>WebSphere</strong> V 5.0, and select<br />
<strong>WebSphere</strong> Express V5.0 Test Environment.<br />
b. Verify that the Client Web Project value is set to OnlineCatalog and click<br />
Next.<br />
15.The Web Service Selection page is displayed and prompts for the WSDL file<br />
location. This is where we enter the URL of the WSDL. This will be filled in for<br />
us since we invoked this wizard from the Web Services Explorer.<br />
Chapter 11. Working with Web services 375
Figure 11-10 Web service selection page<br />
16.Click Next. The wizard will attempt to access the WSDL file at the URL<br />
entered, analyze the information in the file, and then present the Web Service<br />
Binding Proxy Generation page.<br />
376 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 11-11 Web service binding proxy generation page<br />
a. This page allows you to select the type of binding (SOAP, httpget, httpost)<br />
that you want to use. The options are based on the binding information<br />
found in the WSDL file. In this example, only one type of binding, SOAP,<br />
was defined. However, you may find that multiple types have been defined<br />
that you can select.<br />
For this example, we can leave the defaults for all fields.<br />
b. Click Next.<br />
17.The Web Service Test page lets you generate a sample Web application to<br />
use the Web service. Change the Folder field to currency_conversion.<br />
Chapter 11. Working with Web services 377
Figure 11-12 Web service test page<br />
Note: Use the instructions in 13.4.1, “Creating a server and server<br />
configuration” on page 466, to create a test environment server.<br />
18.Click Finish. The wizard automatically launches the TestClient.jsp in the Web<br />
browser.<br />
378 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 11-13 TestClient.jsp<br />
19. The wizard also copies the files needed and generates the sample client. The<br />
JavaBean proxy files are placed in the JavaSource directory and sample<br />
JSPs under the folder specified in the wizard (currency_conversion). The<br />
wizard produces the following files:<br />
– To test the generated proxy, the following files are created in the<br />
currency_conversion folder:<br />
TestClient.jsp: this is basically the parent of a frameset. The frameset<br />
consists of the next three JSPs. This is what is created and launched to<br />
test the Web service.<br />
Method.jsp: this contains a list of the methods available in the Web<br />
service to test.<br />
Input.jsp: this displays a form customized to the method to allow the<br />
user to enter input and submit the test.<br />
Result.jsp: this invokes the proxy class as a useBean and shows the<br />
results produced by the Web service.<br />
Chapter 11. Working with Web services 379
– Proxy: The proxy class makes the call to the Web service provider:<br />
JavaSource/proxy.proxytype/service_nameproxy.java<br />
WebContent/WEB-INF/classes/proxy/proxytype/service_nameproxy.clas<br />
s<br />
In summary, Input.jsp JSP takes the source and target countries from the<br />
user and calls Result.jsp. Result.jsp passes the country information to the<br />
proxy bean, which fetches the conversion rate using the Web service and<br />
then passes the results back to Result.jsp.<br />
11.3.2 Integrating the client into your application<br />
The sample JSPs generated by the wizard serve as a good starting point for<br />
incorporating the Web service into your application. For example, in the Online<br />
Catalog application, we took this client and made the following modifications:<br />
► We created a new entry point page to replace TestClient.jsp and called it<br />
conversion.html. The new page consists of two iframes, Input.jsp and<br />
Result.jsp.<br />
► We changed Input.jsp and Result.jsp to match the overall motif of the<br />
application.<br />
► We added a field in Input.jsp to allow the user to enter an amount to be<br />
converted and added code to do that conversion and to select the country<br />
from a list in a drop-down list box.<br />
► We added code in Result.jsp to convert the amount entered using the rate<br />
retrieved by the Web service.<br />
► We added the conversion.html to the Web site diagram and then applied the<br />
template to it.<br />
The finished result now looks like Figure 11-14 on page 381.<br />
380 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 11-14 Reworked sample<br />
11.3.3 For more information<br />
This topic has looked at the most elementary use of Web services, that of a<br />
client. For more information on developing Web services see:<br />
► <strong>WebSphere</strong> Studio <strong>Application</strong> Developer V5 Programming Guide,<br />
SG24-6957.<br />
► Web Services Wizardry with <strong>WebSphere</strong> Studio <strong>Application</strong> Developer,<br />
SG24-6292. This is written to <strong>WebSphere</strong> Studio Version 4 but has a lot of<br />
appropriate material.<br />
► The Studio Site Developer online Web developer help.<br />
► <strong>IBM</strong> Web Services home page at:<br />
http://www.ibm.com/software/solutions/webservices/<br />
► <strong>IBM</strong> Web Services ToolKit:<br />
http://www.ibm.com/software/solutions/webservices/wstk-info.html<br />
Chapter 11. Working with Web services 381
► WSDL 1.1 specification at:<br />
http://www.w3.org/TR/wsdl<br />
► For more information on WSIF, see:<br />
http://www-106.ibm.com/developerworks/webservices/library/ws-wsif.html<br />
382 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 12. Using Struts<br />
In this chapter, we introduce you to the Jakarta Struts framework and<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express support for building Struts-based Web<br />
applications.<br />
In this chapter, the following topics are covered:<br />
► Struts overview<br />
► Studio Site Developer and Struts<br />
► Using Struts in the Online Catalog sample<br />
For more information, we suggest that you read the following:<br />
► <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express: A Development Example for New<br />
Developers, SG24-6301<br />
► Writing a Simple Struts <strong>Application</strong> using <strong>WebSphere</strong> Studio V5 by Jane<br />
Fung and Colin Yu at:<br />
http://submit.boulder.ibm.com/wsdd/techjournal/0302_fung/fung.html<br />
12<br />
© Copyright <strong>IBM</strong> Corp. 2003 383
12.1 Struts overview<br />
Struts is an open source framework for building Web applications according to<br />
the Model-View-Controller (MVC) architectural pattern (see 2.3.3, “MVC<br />
architectural pattern” on page 28). Struts is part of the Jakarta project, sponsored<br />
by the Apache Software Foundation. For reference, see:<br />
12.1.1 Why we use Struts<br />
http://jakarta.apache.org/struts<br />
http://jakarta.apache.org/struts/userGuide/introduction.html<br />
Note: <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express includes support for Struts<br />
V1.02 and V1.1.<br />
The Struts open source framework was created to make it easier for developers<br />
to build J2EE Web applications. Like a building, a Web application must have a<br />
solid foundation from which the rest of the structure can grow. Using Struts as the<br />
foundation allows developers to concentrate on building the business application<br />
rather than on the infrastructure.<br />
The Struts framework has gained considerable attention because of its ease of<br />
use and ability to fit the needs of today’s developers in building applications fast.<br />
Struts combines servlets, JSPs, custom tags and message resources into a<br />
unified infrastructure and saves the developer the time it takes to code an entire<br />
MVC model, which is a considerable task.<br />
The model 2 approach is concerned with separating responsibilities in Web<br />
applications. <strong>Application</strong> development and maintenance are much easier if the<br />
different components of a Web application have clear and distinct<br />
responsibilities.<br />
As an example, consider an appliance with which you are certainly familiar: a<br />
television set. You will probably agree that changing TV channels is quite a<br />
simple task. Now ask yourself these questions:<br />
► Do you know how the television set represents channels internally?<br />
► Do you know exactly what goes on when you change TV channels?<br />
► Do you think you should know these things?<br />
Chances are that you have answered no to all of the questions above. What is<br />
the advantage of you not knowing how TVs represent their data and implement<br />
their operations? You could buy a new TV, which does these things internally in a<br />
completely different way, and you could still change channels.<br />
384 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
12.1.2 Struts framework<br />
True to the MVC design pattern, Struts applications have three major<br />
components: a servlet (the controller), JSPs (the view), and the application's<br />
business logic (the model).<br />
Struts model component<br />
Struts does not define its own model component. In a Web application (and a<br />
Struts application), most of the model (the business logic) can be represented<br />
using Java beans or EJBs. Access to the business logic is through Struts action<br />
objects (classes that subclass org.apache.struts.action.Action).<br />
The action object can handle the request and respond to the client (usually a<br />
Web browser), or indicate that control should be forwarded to another action. For<br />
example, if a login succeeds, a loginAction object may want to forward control to<br />
a mainMenu action.<br />
Action objects are linked to the application controller, and so have access to the<br />
methods of the servlet. When forwarding control, an object can indirectly forward<br />
one or more shared objects, including Java beans, by placing them in one of the<br />
standard collections shared by servlets.<br />
An action object can, for instance, create a shopping cart bean, add an item to<br />
the cart, place the bean in the session collection, and then forward control to<br />
another action, which may use a JSP to display the contents of the user's cart.<br />
Because each client has its own session, each also has its own shopping cart.<br />
Struts view component<br />
In general, a view represents a display of the domain model in a user interface.<br />
The view in a Struts application is made up of various components. JSPs are the<br />
main component. JSPs, of course, are not Struts components. However, Struts<br />
provides additional components that can be used by or with JSPs:<br />
► Form beans<br />
► Custom tags<br />
► HTML documents<br />
Form beans<br />
A form bean is an instance of the org.apache.struts.action.ActionForm class<br />
subclass that stores HTML or JSP form data from a submitted client request or<br />
input data from a link that a user has clicked. A form bean is a type of Java bean.<br />
An HTML or JSP form comprises fields in which the user can enter information.<br />
Chapter 12. Using Struts 385
When a browser submits an HTML form, the Struts ActionServlet does the<br />
following:<br />
1. Looks at the field names from the HTML form<br />
2. Matches them to the properties' names in the form bean<br />
3. Automatically calls the setter methods of these variables to put the values<br />
retrieved from the HTML form<br />
The form bean can be used to collect data from the user, to validate what the<br />
user entered, and by the JSP to repopulate the form fields<br />
In the case of validation errors, Struts has a shared mechanism for raising and<br />
displaying error messages. It automatically invokes the ActionForm.validate<br />
method whenever the JSP page containing the form corresponding to this<br />
ActionForm submits the form. Any type of validation can be performed in this<br />
method. The only requirement is that it return a set of ActionError objects in the<br />
return value. Each ActionError corresponds to a single validation failure, which<br />
maps to a specific error message. These error messages are held in a properties<br />
file to which the Struts application refers.<br />
Custom tags<br />
There are four tag libraries included in Struts:<br />
1. The HTML tag library, which includes tags for describing dynamic pages,<br />
especially forms.<br />
2. The beans tag library, which provides additional tags for improved access to<br />
Java beans and additional support for internationalization.<br />
3. The logic tag library, which provides tags that support conditional execution<br />
and looping.<br />
4. The template tag library for producing and using common JSP templates in<br />
multiple pages.<br />
Using these custom tags, the Struts framework can automatically populate fields<br />
to and from a form bean, providing two advantages:<br />
► The only thing most JSPs need to know about the rest of the framework is the<br />
proper field names and where to submit the form. The associated form bean<br />
automatically receives the corresponding value.<br />
► If a bean is present in the appropriate scope, for instance after an input<br />
validation routine, the form fields will be automatically initialized with the<br />
matching property values.<br />
386 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Therefore, an input field declared in a JSP using Java code as:<br />
<br />
can be replaced by a more elegant and efficient Struts tag:<br />
<br />
with no need to explicitly refer to the Java bean from which the initial value is<br />
retrieved. That is handled automatically by the JSP tag, using facilities provided<br />
by the framework.<br />
HTML documents<br />
Although HTML documents generate only static content, you can use standard<br />
HTML documents within your Struts application. Of course, they will not be able<br />
to render any dynamic data, but they are still valid to use whenever the view is<br />
static.<br />
For example, a login page may just be an ordinary HTML document that invokes<br />
a Strut login action.<br />
Struts controller component<br />
The most important Struts controller responsibilities are:<br />
► Intercepting client requests<br />
► Mapping each request to a specific business operation<br />
► Collecting results from the business operation and making them available to<br />
the client<br />
► Determining the view to display to the client based on the current state and<br />
result of the business operation<br />
In the Struts framework, several components are responsible for the controller<br />
duties and they can be classified in two parts: the action servlet and action<br />
classes.<br />
Action servlet<br />
The Struts framework provides the org.apache.struts.action.ActionServlet class<br />
for servlets. The action servlet bundles and routes HTTP requests from the client<br />
(typically a user running a Web browser) to action classes and corresponding<br />
extended objects, deciding what business logic function is to be performed, then<br />
delegates responsibility for producing the next phase of the user interface to an<br />
appropriate view component such as a JSP.<br />
Chapter 12. Using Struts 387
When initialized, the action servlet parses a configuration file. The configuration<br />
file defines, among other things, the action mappings for the application. The<br />
controller uses these mappings to turn HTTP requests into application actions.<br />
At least, a mapping must specify:<br />
► A request path<br />
► The object type to act upon the request<br />
Each mapping defines a path that is matched against the request URI of the<br />
incoming request, and the fully qualified class name of an action class.<br />
Action class<br />
An action class is one that extends org.apache.struts.action.Action. The action<br />
classes interface with the application’s business logic. Based on the results of the<br />
processing, the action class determines how control should proceed. The action<br />
class specifies which JSP or servlet control should be forwarded to.<br />
Note: The action class can contain the actual business logic, in which case it<br />
would be considered the model and not the controller. However, this practice is<br />
not recommended, since the application’s business logic woold then be mixed<br />
with the Struts framework code: this would limit the ability to reuse the<br />
business logic. The advised practice is to use the action class as an interface<br />
to the business logic, and allow it to share in the controller role, guiding the<br />
flow of the application.<br />
12.2 Studio Site Developer and Struts<br />
The Struts application development tools that are provided by <strong>WebSphere</strong> Studio<br />
Site Developer make it easy for you to build and manage a Struts-based Web<br />
application. Studio Site Developer acts as follows:<br />
► A Web project which can be configured for Struts. This adds the Struts<br />
runtime (and dependent JARs), tag libraries and action servlet to the project<br />
and creates skeleton Struts configuration and application resources files.<br />
Studio Site Developer provides support both for Struts 1.02 and 1.1 beta 2,<br />
selectable when setting up the project.<br />
► A set of component wizards to define ActionForm classes, action classes with<br />
action forwarding information, and JSP skeletons with the tag libraries<br />
included.<br />
► A configuration file editor to maintain the control information for the action<br />
servlet.<br />
388 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► A design tool to edit a graphical view of the Web application from which<br />
components (forms, actions, JSPs) can be created using the wizards. This<br />
graphical view is called a Web diagram. The Web diagram editor provides<br />
top-down development (developing a Struts application from scratch),<br />
bottom-up development (that is, you can easily diagram an existing Struts<br />
application that you may have imported) and meet-in-the-middle development<br />
(that is, enhancing or modifying an existing diagrammed Struts application).<br />
► A Web Structure view that provides a hierarchical (tree-like) view of the<br />
application. This view shows the artifacts, such as Web pages and actions,<br />
and you can expand the artifacts to see their attributes. For example, an<br />
action can be expanded to see its forwards, which can then be expanded to<br />
see its links. This is useful for understanding specific execution paths of your<br />
application. The Web Structure view is available in the Web perspective.<br />
► Page Designer support for rendering the Struts tags, making it possible to<br />
properly view Web pages that use the Struts JSP tags. This support is<br />
customizable using the preferences settings.<br />
► Validators to validate the Struts XML configuration file and the JSP tags used<br />
in the JSP pages.<br />
12.2.1 Struts development process<br />
You would typically set up and use Struts in an application in the following<br />
manner:<br />
1. Create a new project with Struts support.<br />
If you have an existing project, you must add Struts support to the project.<br />
2. Use wizards to:<br />
– Draw a Struts application Web diagram to visually model the application<br />
flow.<br />
– Develop the JSPs in the Web diagram using the custom Struts HTML and<br />
bean tags.<br />
– Generate templates for ActionForm and action mapping classes and<br />
modify them to add the business logic.<br />
– Edit the Struts configuration file to map actions to Web pages and vice<br />
versa.<br />
12.2.2 Struts support in a Web project<br />
By default, Struts support is not added to a project in Studio Site Developer.<br />
Support can be added when creating a new project and can also be added to an<br />
existing project by modifying the project properties.<br />
Chapter 12. Using Struts 389
Note: Once Struts support has been enabled, numerous files are added to the<br />
directory of the project in the WEB-INF folder, both in the root and in the lib<br />
folder.<br />
Adding Struts support to a new project<br />
Creating a Web project with Struts support is done in the same manner as<br />
illustrated in Chapter 4, “Working with Web applications” on page 57. The only<br />
difference is that on the Features Page of the New Web Project wizard, you must<br />
select the Add Struts support and JSP Tag Libraries features.<br />
Figure 12-1 Adding Struts support<br />
As you continue through the wizard, you will notice that a new page is available<br />
for configuring. The Struts Settings page allows you to override the default Struts<br />
settings.<br />
390 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-2 Struts settings page<br />
Click the Override default settings box and specify the changes:<br />
► To specify a different version of Struts, select from the Struts version<br />
drop-down menu.<br />
► To change the default Java package prefix, edit the Default Java package<br />
prefix field.<br />
► To create a resource bundle for your Struts project, make sure that the Create<br />
a Resource Bundle for the Struts Project box is selected and that a Java<br />
package name and a resource bundle name are specified.<br />
Clicking Finish will create the project and you will now be ready for Struts<br />
application development.<br />
Enabling Struts support in an existing project<br />
If you have an existing project that was created without Struts support, you can<br />
enable the feature by modifying the project properties.<br />
1. Right-click the Web project in the Project Navigator view and select<br />
Properties from the context menu. The properties dialog will open.<br />
2. Select Web Project Features from the left menu box to display the Web<br />
project features.<br />
Chapter 12. Using Struts 391
3. Select Add Struts support and JSP Tag Libraries if not already selected.<br />
Figure 12-3 Web project properties dialog<br />
4. Click Apply.<br />
5. The Struts Settings page is displayed. This page allows you to override the<br />
default Struts settings.<br />
392 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-4 Struts settings page<br />
6. Click Finish to update the project properties with Struts support.<br />
7. Click OK to close the project properties dialog.<br />
12.2.3 Setting Struts preferences<br />
Various preferences settings affect the Web diagram editor, the Struts<br />
configuration file editor, and other Struts tools. To set Struts preferences,<br />
complete the following steps:<br />
1. In the workbench, click Window -> Preferences. The Preferences window<br />
opens.<br />
2. In the Preferences window, click Web Tools and then one of the following<br />
menu selections:<br />
– Struts Tools<br />
– Struts Tools -> Page Designer Struts Support<br />
– Struts Tools -> Web Diagram Editor<br />
3. Change the preferences as desired and click Apply and then OK.<br />
Chapter 12. Using Struts 393
Struts tools<br />
You can set the following general Struts preferences.<br />
Figure 12-5 Struts preferences - Struts tools<br />
► Restart local server when a Struts configuration file changes<br />
Automatically restarts the test server when a registered Struts configuration<br />
file changes. The options are Prompt, Yes, and No.<br />
► Default Java package prefix<br />
Used by various Struts wizards when building package names for new Java<br />
classes such as Action and ActionForm subclasses.<br />
394 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Page designer Struts support<br />
You can set the following Struts-related preferences for the JSP page designer.<br />
Figure 12-6 Struts preferences - Page designer Struts support<br />
► Display error messages for tag<br />
Indicates whether the tag should render error messages. The<br />
error messages displayed are either the default list or the ones specified in<br />
the JSP.<br />
► Error messages to display for tag<br />
Specifies the default error messages to be displayed for tags.<br />
You can override these in each JSP by specifying the keys of error messages<br />
in the application's resource bundle.<br />
► List of options for tag<br />
Specifies the list of options to be rendered for tags.<br />
Chapter 12. Using Struts 395
► Evaluate conditional logic tags to true<br />
Indicates whether the conditional logic tags such as should be<br />
evaluated to true. If this option is on, the body of the conditional tag will be<br />
rendered. If this option is off, nothing will be rendered for the conditional logic<br />
tag. You can override this option in each JSP.<br />
► Count for tag<br />
Specifies the number of times the body of a tag should be<br />
rendered. You can override this option in each JSP.<br />
► Display messages for tag<br />
Indicates whether the tag should render messages. The<br />
messages displayed are either the default list or the ones specified in the JSP.<br />
► Messages to display for tag<br />
Specifies the default messages to be displayed for tags.<br />
You can override these in each JSP by specifying the keys of messages in the<br />
application's resource bundle.<br />
Web diagram editor<br />
You can specify the following preferences that pertain to the Web diagram editor.<br />
396 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-7 Struts preferences - Web diagram editor<br />
► Delete resource when deleting graphics representation<br />
Specifies one of the following actions to take when you delete a part from the<br />
free-form surface:<br />
– Delete the part's underlying resource<br />
– Not delete the part's underlying resource<br />
– Ask you whether to delete the part's underlying resource<br />
► Preferred action on double-clicking an unrealized action mapping<br />
Specifies whether you want the Struts configuration file editor opened or the<br />
Action wizard invoked.<br />
► Preferred action on double-clicking an unrealized form bean<br />
Specifies whether you want the Struts configuration file editor opened or the<br />
ActionForm wizard invoked.<br />
Chapter 12. Using Struts 397
► Graphical connection format<br />
Specifies the visual representation of the following connections:<br />
– Unrealized connection<br />
– Realized connection<br />
– General connection<br />
– Action Mapping Input connection<br />
– Procedural data reference connection<br />
– Declared data reference connection<br />
12.2.4 Web diagram editor<br />
A Web diagram is a file that helps you visualize the application flow of a<br />
Struts-based Web application. Because of the levels of indirection involved in a<br />
Struts application, being able to visualize the application's flow can help you to<br />
better understand the application itself.<br />
Figure 12-8 Web diagram<br />
398 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Within the Web diagram editor , you can add different Struts components<br />
(actions, form beans, Web pages) to create a Struts-based application. The<br />
editor also allows you to invoke wizards and editors for the different components<br />
of the Web diagram.<br />
Note: For more information on how to create a Web diagram, see “Web<br />
diagram wizard” on page 420. After a Web diagram file (*.gph) is created, you<br />
can double-click the file to open the Web diagram editor.<br />
Web diagram terminology<br />
Below is a list and description of some of the common Web diagram terms.<br />
► Free-form surface: A free-form surface (FFS) is the area of the Web diagram<br />
editor that allows you to add nodes and connections.<br />
► Node: A Web page, action mapping, bean, or form bean as represented on<br />
the free-form surface.<br />
► Module: A Struts module is a Struts configuration file and a set of<br />
corresponding actions, form beans, and Web pages. By default, a Struts<br />
application contains only one module, but more than one module can be<br />
added.<br />
► Action: A Struts action is an instance of a subclass of an Action class, which<br />
implements a portion of a Web application and the perform or execute method<br />
of which returns a forward.<br />
► Action mapping: An action mapping is a configuration file entry that, in<br />
general, associates an action name with an action. An action mapping can<br />
contain a reference to a form bean that the action can use, and can<br />
additionally define a list of local forwards that is visible only to this action.<br />
► Form bean: A form bean (type of Java bean) is an instance of a subclass of<br />
an ActionForm class that stores HTML form data from a submitted client<br />
request or that can store input data from a Struts action link that a user has<br />
clicked. To create a form bean, you must create both a form bean and a<br />
form-bean mapping.<br />
► Dynaform: A dynaform (type of form bean) is an instance of a<br />
DynaActionForm class or subclass that stores HTML form data from a<br />
submitted client request or that stores input data from a link that a user has<br />
clicked. To create a dynaform, you need create only a form-bean mapping; a<br />
form bean will be dynamically created for you at runtime.<br />
► Exceptions: A Struts exception is an element defined in a Struts<br />
configuration file that specifies how to handle Java exceptions that occur<br />
during execution of Struts actions. An exception can be local or global. Global<br />
exceptions are only available in Struts 1.1.<br />
Chapter 12. Using Struts 399
► Forwards: A Struts forward is an object returned by an action; it has two<br />
fields: a name and a path. The path indicates where a request is to be<br />
forwarded. A forward can be local (pertaining to a specific action) or global<br />
(available to any action).<br />
► Connections: In a Struts diagram, a connection is a line that represents<br />
either logic flow or data flow.<br />
– Logic flow<br />
A logic flow connection in a Web diagram represents how a page or an<br />
action “flows” to the next page or action. For example, a link from a Web<br />
page to another page represents how the first page can go to the next<br />
page. This type of connection is represented in a Web diagram with a<br />
black line. Possible types of logic flow connections include:<br />
Web page to Web page<br />
Web page to action mapping<br />
Web page to Web application<br />
Action mapping to action mapping<br />
– Data flow<br />
A data flow connection is a line that represents a possible flow of data<br />
through beans from a Web page or an action mapping. Two types of data<br />
flow connections exist:<br />
Declared data reference: This connection type is shown, by default, as<br />
a blue line. Types of declared data reference connections include:<br />
Action mapping to form bean, where the form bean is the form bean<br />
specified in the action mapping declaration.<br />
Web page to Java bean, where the bean is referenced in a Web<br />
page by a useBean tag<br />
Web page to form bean, where the bean is referenced in a Web<br />
page by a useBean tag<br />
Note: The first connection made from an action mapping to a form<br />
bean is assumed to be the connection to the action mapping's<br />
defined form bean. Any subsequent connections from that action<br />
mapping to other form beans are assumed to represent bean<br />
references from within the action mapping's action class and are<br />
shown as procedural data references.<br />
400 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Procedural data reference: This connection type is shown, by default,<br />
as agreen line. Types of procedural data reference connections<br />
include:<br />
Action mapping to Java bean<br />
Action mapping to form bean<br />
Context menu<br />
In the Web diagram editor, the context menu displays an appropriate list of<br />
possible actions. The context menu can be accessed by right-clicking anywhere<br />
on the free-form surface or on an object within the free-form surface.<br />
The content of the list depends on which object on the free-form surface is<br />
selected. Listed below are the context menu actions built into the diagram editor.<br />
Table 12-1 Context menu actions<br />
Item Parent Function Icon<br />
Connection Draws a<br />
connection from<br />
the selected node<br />
to a target.<br />
Draw All From Draw Draws all targets<br />
and connections<br />
from the selected<br />
node.<br />
Draw Selected<br />
From<br />
Draw ► Displays a<br />
pop-up dialog<br />
that lists all<br />
links and<br />
forwards from<br />
the selected<br />
node.<br />
► You can select<br />
which links or<br />
forwards you<br />
want drawn.<br />
Chapter 12. Using Struts 401
Item Parent Function Icon<br />
Draw All Draw Draws all targets<br />
and connections<br />
from the selected<br />
node and then<br />
recursively<br />
performs the same<br />
action on each of<br />
the targets.<br />
Action Mapping<br />
Node<br />
New Primes the cursor<br />
ready to drop a new<br />
action mapping<br />
onto the FFS.<br />
Form Bean Node New Primes the cursor<br />
ready to drop a new<br />
form bean onto the<br />
FFS.<br />
Java Bean Node New Primes the cursor<br />
ready to drop a new<br />
Java bean onto the<br />
FFS.<br />
Web Page Node New Primes the cursor<br />
ready to drop a new<br />
Web page onto the<br />
FFS.<br />
Web <strong>Application</strong><br />
Node<br />
Struts Module<br />
Node<br />
New Primes the cursor<br />
ready to drop a new<br />
Web application<br />
onto the FFS.<br />
New Primes the cursor<br />
ready to drop a new<br />
Struts module onto<br />
the FFS.<br />
Open Opens the part in<br />
its default editor.<br />
Open Other For those parts that<br />
have more then<br />
one editor, this<br />
opens the part in<br />
the other editor.<br />
402 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Item Parent Function Icon<br />
Change Path Changes the path<br />
of the part.<br />
Change<br />
Description<br />
Change Module<br />
Association<br />
Struts tools drawer from the Palette view<br />
The Palette view provides a Struts tools drawer that contains much of the same<br />
actions as the Web diagram context menu mentioned previously.<br />
Figure 12-9 Struts tools drawer<br />
Changes the<br />
description of the<br />
part.<br />
Changes the<br />
module association<br />
for the diagram.<br />
Undo Undoes the last<br />
undoable action.<br />
Redo Redoes that last<br />
undone action.<br />
Delete Deletes the<br />
selected part.<br />
Chapter 12. Using Struts 403
12.2.5 Wizards<br />
To use an action, select it from the drawer and then click anywhere on the<br />
free-form surface to place it. With connections, click Connection from the<br />
drawer, then click one node and then another to create the connection.<br />
Realizing Web diagram parts<br />
Once you have added a node to the Web diagram editor, it will be unrealized. An<br />
unrealized node is represented as a grayed out icon within the Web diagram<br />
editor. When the node becomes realized, the icon will change color. Simply put,<br />
an unrealized node is a node that is just an icon on the free-form surface and is<br />
yet to be created (realized); think of it as a place holder for the node.<br />
To realize an unrealized node, double-click the node to invoke the appropriate<br />
wizard. For a JSP, HTML page, action mapping, Web application, Java bean, and<br />
form bean, only one wizard exists. When double-clicking a Module node, either<br />
the Module wizard or Action Mapping wizard will be invoked. The Module wizard<br />
is opened if the module does not exist and the Action Mapping wizard will open if<br />
the entry point action mapping does not exit.<br />
To realize a declared or procedural data reference connection, you must first<br />
realize the source of the connection. If the source is realized, the appropriate<br />
editor is launched where you are able to enter the required code to make the<br />
connection realized.<br />
Note: Unrealized connections are indicated in the Web diagram editor with a<br />
dashed line. As soon as the connection is realized, the line becomes solid.<br />
For a detailed explanation of the wizards, see 12.2.5, “Wizards” on page 405..<br />
Note: You can also realize an unrealized node by identifying it as an existing<br />
node. If doing this, there are resolution rules that need to be followed for each<br />
node. Please refer to the <strong>WebSphere</strong> Studio Site Developer product help for<br />
more information.<br />
Studio Site Developer also provides you with the following wizards to aid in the<br />
creation of a Struts-based application. These wizards can be found by selecting<br />
File -> New -> Other -> Web -> Struts from the workbench main menu.<br />
404 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-10 Struts wizards<br />
In addition, some of the wizards can be accessed through the Web diagram<br />
editor and/or the Struts explorer.<br />
Action wizard<br />
To create an action and optionally create an action mapping, complete the<br />
following steps:<br />
1. In the Project Navigator of the Web perspective, right-click the name of a<br />
project.<br />
2. Left-click New -> Other -> Web -> Struts -> Action Class -> Next.<br />
3. On the New Action Class page, complete the following steps:<br />
Chapter 12. Using Struts 405
Figure 12-11 Action wizard<br />
– In the Action class name field, type the name of the new action.<br />
– In the Folder field, specify the name of the folder in which the new class is<br />
to be created.<br />
– In the Java package field, specify the name of the Java package in which<br />
the class is to be created.<br />
– If you want to specify modifiers that apply to the new class, select one or<br />
more of the following boxes: public, abstract, final.<br />
– Make sure that a value is supplied in the Superclass field.<br />
– For each interface that you want to create, click Add and type the interface<br />
name, the names of matching types, and any qualifiers.<br />
– If you want to create method stubs, click the check boxes to select the<br />
ones you want.<br />
– For the code generation model, select Generic Action Class.<br />
4. Click Finish.<br />
406 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
5. If you want to create an action mapping in addition to creating an action, on<br />
the Create a mapping for your Action class page, complete the following<br />
steps:<br />
Figure 12-12 Action wizard<br />
– Make sure that the Add new mapping box is checked.<br />
– Make sure that a configuration file name is specified<br />
– If you want to change the default mapping path, type the path name in the<br />
Action Mapping Path field.<br />
– To specify forwards, click Add and specify the forward's name and path<br />
and, if the forward is context-relative, change the Context relative? value<br />
to true.<br />
– To delete a forward, select the forward name and click Remove.<br />
– If you want to specify a form bean, select the name from the Form Bean<br />
Name drop-down menu.<br />
Chapter 12. Using Struts 407
– If you want to specify a form bean scope, from the Form Bean Scope<br />
drop-down list select request or session. The default behaves as if<br />
request were selected.<br />
6. Click Finish.<br />
Action mapping wizard<br />
To create an action mapping that associates a Struts action with a forward,<br />
complete the following steps:<br />
1. In the Project Navigator of the Web perspective, right-click the name of a<br />
project or any artifact within the project.<br />
2. Left-click New -> Other -> Web -> Struts -> Action Mapping.<br />
Note: There are four other ways to invoke the Module wizard.<br />
– Double-clicking an unrealized action mapping node in the Web diagram<br />
editor.<br />
– Right-clicking the project in the Struts Explorer view and selecting<br />
New -> Action Mapping from the context menu.<br />
– Expanding the project directory in the Struts Explorer view, right-clicking<br />
the module, and selecting New -> Action Mapping from the context<br />
menu.<br />
– Expanding the module folder in the Struts Explorer view, right-clicking<br />
the Actions folder, and selecting Add Action Mapping... from the<br />
context menu.<br />
408 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3. On the New Action Mapping page, complete the following steps:<br />
Figure 12-13 Action mapping wizard<br />
a. Specify the configuration file name or accept the default.<br />
b. Specify the action mapping path or accept the default.<br />
c. To specify forwards, click Add and specify the forward's name and path<br />
and, if the forward is context-relative, change the Context relative? value<br />
to true.<br />
d. If you want to use a form bean, select a form bean name from the Form<br />
Bean Name drop-down menu and select the scope from the Form Bean<br />
Scope drop-down menu.<br />
Chapter 12. Using Struts 409
– If you want to reuse an existing class for your mapping's type, click the An<br />
existing Action class radio button and select a fully qualified class name<br />
from the drop-down menu. Otherwise, click the Create an Action class<br />
radio button and select one of the following models from the Model<br />
drop-down list:<br />
Generic Action Mapping<br />
Reuse an existing class<br />
4. Click Finish.<br />
5. If you want to create an action class in addition to creating an action mapping,<br />
on the Create a Action class for your mapping page, complete the following<br />
steps:<br />
6. On the New Action Class page, complete the following steps.<br />
410 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-14 Action mapping wizard<br />
a. In the Action class name field, type the name of the new action.<br />
b. In the Folder field, specify the name of the folder in which the new class is<br />
to be created.<br />
c. In the Java package field, specify the name of the Java package in which<br />
the class is to be created.<br />
d. If you want to specify modifiers that apply to the new class, select one or<br />
more of the following boxes: public, abstract, final.<br />
e. Make sure that a value is supplied in the Superclass field.<br />
f. For each interface that you want to create, click Add and type the interface<br />
name, the names of matching types, and any qualifiers.<br />
Chapter 12. Using Struts 411
g. If you want to create method stubs, click the check boxes to select the<br />
ones you want.<br />
7. Click Finish.<br />
ActionForm wizard<br />
To create a Struts form bean and optionally create a form bean mapping,<br />
complete the following steps:<br />
1. In the Project Navigator of the Web perspective, right-click the name of a<br />
project or artifact within a project.<br />
2. Click New -> Other -> Web -> Struts -> ActionForm Class -> Next.<br />
3. On the New ActionForm Class page in the ActionForm class name field, type<br />
the name of the ActionForm subclass that you are creating.<br />
4. Fill out the other fields as appropriate for the subclass you are creating, and<br />
click Next.<br />
5. On the Choose new fields for your ActionForm class page, click the check box<br />
beside the name of each node for which you want a get and a set method<br />
created. Check boxes exist for every node in the following hierarchy:<br />
– Project<br />
– Module<br />
– Folder<br />
– Web page<br />
– Form<br />
– Form field (leaf)<br />
If you click the check box beside the name of a form field, you will generate a<br />
corresponding field, get method, and set method in your form bean. If you<br />
click the check box beside the name of a parent, you will generate a<br />
corresponding field, get, and set for every leaf underneath that parent. Click<br />
Next.<br />
6. On the Create new fields for your ActionForm class page, click Add and type<br />
the field name and type for each field you want to create. If you want to create<br />
a form-bean mapping, click Next. Otherwise click Finish and skip the final<br />
step.<br />
7. On the Create a mapping for your ActionForm class page, make sure that the<br />
Add new mapping box is selected and that the correct configuration file<br />
name and mapping name are specified. Then click Finish.<br />
412 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Form bean mapping wizard<br />
To create a Struts form-bean mapping, complete the following steps:<br />
1. In the Project Navigator of the Web perspective, right-click the name of a<br />
project.<br />
2. Click New -> Other -> Web -> Struts -> Form-Bean Mapping -> Next.<br />
Note: There are three other ways to invoke the Form bean mapping wizard.<br />
– Double-clicking an unrealized form bean node in the Web diagram<br />
editor.<br />
– Expanding the project directory in the Struts Explorer view, right-clicking<br />
the module, and selecting New -> Form Bean from the context menu.<br />
– Expanding the module folder in the Struts Explorer view, right-clicking<br />
the Form Beans folder, and selecting Add Form Bean... from the<br />
context menu.<br />
3. On the New Form-Bean page, complete the following steps:<br />
a. Make sure that the correct configuration file name and mapping name are<br />
specified.<br />
b. Click one of the following radio buttons:<br />
An existing ActionForm<br />
Create an ActionForm class or Struts dynaform using DynaActionForm<br />
c. If you selected the second option in the previous step, you must select one<br />
of the following models from the drop-down menu:<br />
Generic Form-Bean Mapping<br />
dynaform using DynaActionForm<br />
d. Click Next.<br />
4. On the Choose new fields for your ActionForm class page, click the check box<br />
beside the name of each module for which you want a get and a set method<br />
created. Then click Next.<br />
5. On the Create new fields for your ActionForm class page, click Add and type<br />
the field name and type for each field you want to create. If you chose<br />
Generic Form-Bean Mapping, click Next; otherwise click Finish.<br />
6. On the Create a mapping for your ActionForm class page, click the Add new<br />
ActionForm class box and complete the following steps:<br />
a. Specify the name for the new ActionForm class.<br />
b. Specify the path name of the folder in which the class will be created, or<br />
accept the default.<br />
Chapter 12. Using Struts 413
c. Specify the name of the Java package, or accept the default.<br />
d. Click any of the check boxes that describe the characteristics of the class<br />
that you want to create:<br />
public<br />
abstract<br />
final<br />
e. Specify the name of the superclass in which the class will be created, or<br />
accept the default.<br />
f. For each interface that you want to create, click Add and type the interface<br />
name, the names of matching types, and any qualifiers.<br />
g. Click the check boxes for the method stubs that you want created, or<br />
accept the defaults. The choices are as follows:<br />
inherited abstract methods<br />
constructors from superclass<br />
reset(..., HttpServletRequest)<br />
reset(..., ServletRequest)<br />
validate(..., HttpServletRequest)<br />
validate(..., ServletRequest)<br />
h. Click Finish.<br />
JSP wizard<br />
A Struts JSP file is a JSP file that uses Struts tag libraries. If you select Struts<br />
support in the JSP wizard as described below, you can (optionally) create a form<br />
in the new JSP file that contains fields from a user-specified form bean.<br />
To create a Struts JSP file:<br />
1. In the Project Navigator of the Web perspective, right-click WebContent in a<br />
project folder.<br />
2. Click New -> JSP File.<br />
Note: There are two other ways to invoke the JSP wizard.<br />
– Double-clicking an unrealized Web Page node in the Web diagram<br />
editor.<br />
– Expanding the module folder in the Struts Explorer view, right-clicking<br />
the Web Pages folder, and selecting Add JSP File... from the context<br />
menu.<br />
3. Fill out fields on the first New JSP File page, making sure that Struts JSP is<br />
specified in the Model field.<br />
414 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
4. If you want to create the new JSP file with all the defaults, click Finish. The<br />
JSP file will contain the two most frequently used Struts tag-library<br />
declarations but will not contain a form. If you want to change other<br />
information or include a form in the new JSP file, click the Show advanced<br />
options box, and then click Next.<br />
5. In the Tag libraries box on the Tag Libraries page, select the names of any tag<br />
libraries that you want added to the new JSP file. If these are the only tag<br />
libraries you want, click Next.<br />
If you want to add other tag libraries, click Add and complete the following<br />
actions:<br />
a. Click the check box for each tag library you want to add, and choose any of<br />
the available customizations that you want.<br />
b. To specify a tag library that is not in the list, click Import, specify the path<br />
name of a JAR file, and click Finish.<br />
c. Click OK.<br />
6. If you want to remove a tag library from the list on the New JSP File page,<br />
select the name of the library and click Remove.<br />
7. When the Tag libraries list on the New JSP File page is as you want it, click<br />
Next.<br />
8. On the next two New JSP File pages, provide the information requested, and<br />
click Next.<br />
9. If you want to include a form in the new JSP file, complete fields on the Form<br />
Field Selection page:<br />
a. If your application comprises more than one module and you want to<br />
specify a module other than the default, type the path name of the module<br />
in the Form bean module field.<br />
b. In the Form bean entry field, type the name of the entry or select one from<br />
the drop-down list. As you type the entry, the Bean name field is<br />
automatically filled out with the same name for the Java bean.<br />
c. To specify an action to be invoked by the JSP file, type the name of the<br />
action or click Browse.<br />
d. If you selected an existing form bean entry and it references an existing<br />
ActionForm subclass, the Fields list automatically contains the properties<br />
of the ActionForm subclass. You can select which fields you want to<br />
include in your form.<br />
e. Click Next.<br />
Chapter 12. Using Struts 415
10.On the Design the Form page, you can change how the fields are created in<br />
the new JSP file:<br />
a. Select each field that you want to change. The properties of the selected<br />
field will be displayed, and you can change their values.<br />
b. To see nested fields, click the + icon next to a field. If the selected field is<br />
an array, the properties being displayed refer to each array item.<br />
c. To change the title of the new JSP file, click the Page tab.<br />
d. Click Finish. The JSP file is created and the JSP editor starts.<br />
Configuration file wizard<br />
A Struts configuration file is created automatically when you create a Struts<br />
project or a Struts module. However, you can have more than one configuration<br />
file for the default module. To create a Struts configuration file, complete the<br />
following steps:<br />
1. In the Project Navigator, select the name of a project.<br />
2. Navigate the following menu path: File -> New -> Other.<br />
3. Select Web and then Struts in the left pane and Struts Configuration File in<br />
the right pane.<br />
4. Click Next. A new window appears.<br />
416 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-15 Configuration file wizard<br />
5. Type the name of the new Struts configuration file and click Finish.<br />
Exception wizard<br />
To create a Struts exception, complete the following steps:<br />
1. In the Project Navigator of the Web perspective (Window -> Open<br />
Perspective -> Web), right-click the name of a project.<br />
2. Click New -> Other -> Web -> Struts -> Struts Exception -> Next.<br />
Chapter 12. Using Struts 417
Note: The Exception wizard can also be invoked from the Struts Explorer<br />
view. Right-click the module folder and select New -> Global Exception for<br />
the context menu or expand the module, right-click the Global Exceptions<br />
folder and select Add Global Exception... from the context menu to invoke<br />
the wizard. This folder only contains Global exceptions, so if you create a<br />
Local exception, it will not be reflected in this folder but will be reflected in the<br />
configuration file.<br />
Figure 12-16 Exception wizard<br />
a. Select a configuration file from the Configuration file drop-down menu.<br />
b. Click Browse and select an exception type.<br />
c. Type the path name of your exception handler to be created.<br />
d. Click Browse and select an exception handler class name.<br />
e. Click one of the following radio buttons to select the exception context:<br />
Global<br />
Local to action-mapping<br />
f. Specify a key name for your exception.<br />
418 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3. Click Finish.<br />
Module wizard<br />
A Struts module is created automatically when you create a Struts project. To<br />
create an additional Struts module, complete the following steps:<br />
1. In the Project Navigator of the Web perspective (Window -> Open<br />
Perspective -> Web), select the name of a project.<br />
2. On the main menu bar, click File -> New -> Other.<br />
3. Select Web and then Struts in the left pane and Struts Module in the right<br />
pane.<br />
Note: There are two other ways to invoke the Module wizard. Double-clicking<br />
an unrealized Module node in the Web diagram editor will invoke the Module<br />
wizard; right-clicking the project in the Struts Explorer view and selecting<br />
New -> Module from the context menu will also invoke the Module wizard.<br />
4. Click Next. The Create a Struts module window appears.<br />
Figure 12-17 New struts module wizard<br />
Chapter 12. Using Struts 419
5. Type the name of the new Struts module and change any defaults as desired<br />
by selecting the Override default settings option.<br />
– Deselecting the Create module directory option will not create a module<br />
directory in the WebContent directory of your Web project.<br />
– If you wish to change the name of the Struts configuration file, you can, but<br />
it is recommended that you leave the default value since it includes the<br />
module name you specified and can easily been recognized if you are<br />
looking for it.<br />
– Deselect the Create a Resource Bundle for the Struts Project option if<br />
you do not want to create a resource bundle for the module.<br />
A Resource bundle contains locale-specific objects. For example, a<br />
Resource bundle could include a properties file that contains the label text<br />
for all the buttons in your application. Instead of hard-coding the text onto<br />
the buttons, you can call the values from the properties file. This is very<br />
beneficial if you ever want to change the language of your application.<br />
– You can change the name of the Resource bundle Package if you like, but<br />
again, it is best to leave the default value since it contains the module<br />
name you specified and can be easily recognized if required.<br />
– Editing the value in the Resource bundle Name field will change the name<br />
of the default application resources properties file.<br />
Note: When the Create a Resource Bundle for the Struts Project<br />
option is selected, a properties file called<br />
<strong>Application</strong>Resources.properties is created and placed in the Web<br />
Content/WEB-INF/classes//resources directory. This<br />
file is read by the Struts framework at runtime.<br />
In this file, it is possible to specify properties which can be used by your<br />
application. For example, you could create a property called page.title<br />
and specify the value as “My New Page”. This property could be used in<br />
a page called page.jsp to set the page title. This is potentially beneficial<br />
if you ever want to change the language of your application.<br />
6. Click Finish. A Struts configuration file is created.<br />
Web diagram wizard<br />
To create a Web diagram, complete the following steps:<br />
1. In the Project Navigator, select the name of a project.<br />
2. Right-click and select the following menu path: New -> Other -> Web -><br />
Struts -> Web Diagram.<br />
420 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: The Web diagram wizard can also be invoked by right-clicking the<br />
project name in the Struts explorer view and selecting New -> Web Diagram<br />
from the context menu.<br />
3. Click Next. The Create a Web diagram page appears with a default parent<br />
folder name provided.<br />
Figure 12-18 Web diagram wizard<br />
a. If you want to specify a different parent folder, type the name or select it<br />
from the choices in the box beneath the Enter or select the parent folder<br />
field.<br />
b. In the File name field, type the name of the Web diagram file that is to be<br />
created.<br />
c. If you want to associate the Web diagram with a module other than the<br />
default Struts module, select a module from the Module drop-down menu.<br />
Chapter 12. Using Struts 421
d. If you want to associate the Web diagram with a file in the file system, click<br />
Advanced, check the Link to file in the file system box, click Browse, and<br />
select a file.<br />
4. Clicking Finish creates a new Web diagram file (*.gph) and places it in the<br />
specified folder.<br />
12.2.6 Struts configuration file editor<br />
A Struts configuration file (struts-config.xml) is an XML document that describes<br />
all or part of a Struts application and is used to configure the interaction between<br />
Struts objects.<br />
Figure 12-19 Configuration file editor<br />
The struts-config.xml file is located in the WEB-INF folder of the Web project.<br />
Double-clicking the file opens the Struts configuration file editor. Once you have<br />
completed making your changes to the configuration file, you must save it to<br />
apply your changes.<br />
422 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The Struts configuration file editor contains the following options:<br />
► Action Mappings: Add, remove, and edit action mappings, local forwards, and<br />
local exceptions.<br />
► Global Forwards: Add, remove, and edit global forwards.<br />
► Form Beans: Add, remove, and edit form beans.<br />
► Data Sources: Add, remove, and edit data sources.<br />
► Global Exceptions: Add, remove, and edit Global exceptions.<br />
► Controller: Add, remove, and edit Controller attributes.<br />
► Message Resources: Add, remove, and edit message resources.<br />
► Plug-ins: Lets you define plug-ins associated with the configuration file.<br />
► Source: Lets you edit the XML source of the file.<br />
12.2.7 Struts explorer view<br />
The Struts Explorer view provides you with a way to navigate through the various<br />
referenced parts of a Web application from a starting point such as a Web page ,<br />
an Action mapping, a Global forward, or a Global exception.<br />
Objects contained in the Struts explorer view can be dragged and dropped onto<br />
the free-form surface of the Web diagram editor.<br />
In addition, configuration files, modules, action mappings, form beans, Web<br />
pages, global forwards, and global exceptions can be created in the Struts<br />
explorer view. Please refer to 12.2.5, “Wizards” on page 405 for more<br />
information.<br />
To view the organization of a Struts project in the Struts Explorer, complete the<br />
following steps:<br />
1. In the Web perspective, click Window -> Show View -> Struts Explorer. The<br />
Struts Explorer view lists the names of the J2EE Web projects that exist in<br />
your workspace.<br />
2. In the Struts Explorer, you can click the + signs to expand the list into a tree<br />
that lists the Web pages contained in a project. If the project is a Struts Web<br />
application, you can also get a list of Struts artifacts that are associated with<br />
the project.<br />
3. You can expand each Web page to see the links that the page contains.<br />
4. You can follow a link to the next page or action to see how the Web<br />
application flows from the initial page.<br />
Chapter 12. Using Struts 423
12.2.8 Data Mappings view<br />
The Struts Data Mappings view lets you see how a Web page form controls data<br />
maps to the destination formBean class. You can then use this mapping to<br />
determine whether there is a mismatch between the input (form) and the target<br />
(formBean).<br />
Figure 12-20 Data Mappings view<br />
This viewer takes selections from Struts Explorer and Web diagram editor as the<br />
context, and if the selection is valid, the Data Mappings Viewer refreshes with the<br />
new input.<br />
When a valid input is selected, a table with two columns appears. The columns<br />
contain the following information:<br />
► A list of all the fields that this form link contains, including the hidden fields<br />
► A list of properties in the form bean that can be set<br />
12.2.9 Struts validation<br />
Struts validation is built upon the validation framework in the workbench. By<br />
default, the following aspects of a Struts project are automatically validated when<br />
a relevant file is closed:<br />
► Syntax of Struts configuration file<br />
► Syntax of Struts tags in web.xml file<br />
► Resolution of Struts links and references in various Struts files<br />
424 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
These validators can be turned on and off in the workbench preferences and/or<br />
the project properties. For more information about syntax validation, see “Syntax<br />
validation” on page 92.<br />
12.3 Using Struts in a sample<br />
To illustrate the use of Struts, we will create an administrative login sample that<br />
will allow a user to log in as either a “read access” administrator or a “write<br />
access” administrator.<br />
Let’s assume that up to this point in our application, we have created all the<br />
front-end content for our Web site. We now need to add the back-end content<br />
and the administrative login will be the entry point.<br />
Depending on the user name and password submitted, the user will see a<br />
different administrative maintenance page. The “read access” administrator<br />
(admin1) will see options to view customers and orders. The “write access”<br />
administrator (admin2) will see the options to view, edit, and delete products.<br />
Struts will be used to first validate the user name and password entries and then,<br />
depending on the submitted values, the action will forward the user to the<br />
appropriate page. A Struts action will also be used to log the user out of the<br />
administrative section of the site.<br />
The following JSPs and Java classes are created in this sample:<br />
► login.jsp - provides the interface to log in to the administration page<br />
► LoginForm.java - an instance of this class is used to validate the user input<br />
parameters from the login.jsp page<br />
► LoginAction.java - an instance of this class is used to authenticate the user<br />
► admin1.jsp - displays the options to view a customer or an order<br />
► admin2.jsp - displays the options to view, edit, and delete products<br />
► LogoutAction.java - an instance of this class is used to log the user out of the<br />
administration page and redirect the user to the login page.<br />
Chapter 12. Using Struts 425
Note: We did not follow this sample through to completion. There are four<br />
actions that are referenced in the code but not coded: customer.do, orders.do,<br />
additem.do, and edititem.do. This sample is designed to show you how to use<br />
the tools to create the Struts components. For an end-to-end example, see<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express: A Development Example for New<br />
Developers, SG24-6301.<br />
The following diagram illustrates the sequence of events that occur when a user<br />
attempts to log in to the administrative function of the site as a “write access”<br />
administrator.<br />
Web Browser<br />
Figure 12-21 Login flow for admin2 user<br />
The steps in this sample will follow the same flow as outlined in 12.2.1, “Struts<br />
development process” on page 389. The only difference is that after the Struts<br />
components have been created, we will integrated the login.jsp page with the<br />
rest of the application by adding a hyperlink to all of the pages.<br />
426 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
8<br />
1<br />
ActionServlet LoginAction<br />
7<br />
admin2.jsp<br />
3<br />
6<br />
2<br />
4<br />
LoginForm<br />
5
Important: If you are downloading the Online Catalog sample from the<br />
additional material section of the <strong>IBM</strong> Redbook site, this sample will be<br />
included in the project but will not be incorporated into the application. The<br />
classes created in this example will be located in the onlinecatalog.actions<br />
and onlinecatalog.forms packages. Any JSPs or HTML pages associated with<br />
the example will be located in the struts_login folder in the WebContent<br />
directory.<br />
The login function in the sample will use a JSP to verify that the user name<br />
and password submitted are valid by referencing a table in the SALESAPP<br />
database.<br />
12.3.1 Adding Struts support to the OnlineCatalog project<br />
When we originally created the OnlineCatalog project, we did not add Struts<br />
support. In order for us to continue, we need to enable Struts support on the<br />
project.<br />
1. In the Project Navigator view of the Web Perspective, right-click the<br />
OnlineCatalog Web project and select Properties from the context menu.<br />
2. Select Web Project Features from the left menu box to display the Web<br />
Project Features in the dialog.<br />
3. Select the Add Struts support check box from the features list box.<br />
4. Click Apply. The Struts Settings page is displayed. This page allows you to<br />
override the default Struts settings; see “Enabling Struts support in an existing<br />
project” on page 391 for more information.<br />
5. Click Finish to update the project properties with Struts support.<br />
6. Click OK to close the project properties dialog.<br />
12.3.2 Creating a Web diagram<br />
Now that Struts support has been added to the OnlineCatalog project, we can<br />
create a Web diagram.<br />
1. In the Project Navigator view, navigate to the<br />
OnlineCatalog\WebContent\struts_login folder.<br />
Chapter 12. Using Struts 427
Note: The Web diagram file (*.gph) does not have to be added to the<br />
struts_login folder. The file can be placed anywhere in the WebContent folder,<br />
but it is recommended that it be placed in a location that will be remembered.<br />
2. Right-click the folder and select New -> Other from the context menu.<br />
3. In the New dialog, select Web -> Struts in the left pane and Web Diagram in<br />
the right pane.<br />
4. Click Next. The Web diagram wizard opens.<br />
5. In the Create a Web Diagram window, accept the defaults and enter<br />
LoginProcess in the File name field.<br />
Figure 12-22 Creating a Web diagram<br />
6. Click Finish. This creates a new Web diagram file, LoginProcess.gph, under<br />
the WEB-INF folder and opens it in the Web diagram editor.<br />
428 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
12.3.3 Creating the Web page nodes<br />
With the Web diagram created, we can add the Web page, Action mapping, and<br />
Form bean nodes. We will start with the Web page nodes. Recall that we need to<br />
create three Web page nodes: login.jsp, admin1.jsp, and admin2.jsp.<br />
1. Double-click Web Page Node in the toolbar to the right. This will prime the<br />
cursor to drop a new Web page onto the free-form surface.<br />
2. Click where you want the page to be. A Web page icon is displayed on the<br />
free-form surface.<br />
3. Change the default name /page.jsp to /struts_login/login.jsp.<br />
4. Follow the same process to create Web page nodes for the two administration<br />
pages, modifying the default names to /struts_login/admin1.jsp and<br />
/struts_login/admin2.jsp.<br />
5. Save the LoginProcess Web diagram (Ctrl+ S).<br />
Figure 12-23 Adding Web page nodes to the Web diagram<br />
Chapter 12. Using Struts 429
Important: Notice that the icons are grey. Once the nodes become realized,<br />
these icons will change color.<br />
12.3.4 Creating the action mapping nodes<br />
For the verification of the user name and password, we need to add an action<br />
mapping node to the free-form surface. We will also add an action mapping node<br />
for the logout action.<br />
1. Double-click Action Mapping Node in the toolbar to the right. This will prime<br />
the cursor to drop a new action mapping onto the free-form surface.<br />
2. Click where you want the action to be. An action mapping icon is displayed on<br />
the free-form surface.<br />
3. Change the default path from /action to /login.<br />
4. Similarly, create an action mapping node for the logout action and change the<br />
path to /logout.<br />
Figure 12-24 Adding Action mapping nodes to the Web diagram<br />
5. Save the LoginProcess Web diagram.<br />
430 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
12.3.5 Creating connections<br />
The application flow is depicted by connecting the nodes within the Web<br />
diagram. To create a connection between two nodes, right-click the first node,<br />
select Connection from the context menu and then click the second node.<br />
For our application, we need to create the following connections:<br />
► From the login.jsp page to the /login action mapping.<br />
► From the /login action mapping to the admin1.jsp page. Change the default<br />
forward name to admin1page.<br />
► From the /login action mapping to the admin2.jsp page. Change the default<br />
forward name to admin2page.<br />
► From the /login action mapping to the login.jsp page. Change the default<br />
forward name to failure.<br />
► From the admin1.jsp page to the /logout action mapping.<br />
► From the admin2.jsp page to the /logout action mapping.<br />
► From the /logout action mapping to the login.jsp page. Change the default<br />
forward name to success.<br />
Figure 12-25 Adding connections to the Web diagram<br />
Chapter 12. Using Struts 431
Important: Notice that the connection lines in the diagram are dashed. When<br />
the connections are realized, the lines will become solid.<br />
12.3.6 Editing the <strong>Application</strong>Resources.properties file<br />
The <strong>Application</strong>Resources.properties file is used to specify properties that can<br />
be used throughout the application. We are going to add some properties to the<br />
file for later use in our pages. You will see how some of these are used as we go<br />
through the sample.<br />
1. Navigate to the <strong>Application</strong>Resources.properties file in the Web<br />
Content/WEB-INF/classes folder. It will be located in the resources folder<br />
under the folder hierarchy for the Struts Java package prefix (you can see this<br />
in the Struts preferences).<br />
2. Double-click the file to open it in the default text editor.<br />
3. Replace the contents of the file with the text shown in Example 12-1.<br />
Example 12-1 <strong>Application</strong>Resources.properties<br />
errors.header = The following errors were<br />
detected:<br />
errors.prefix = <br />
errors.suffix = <br />
erros.footer = <br />
login.title = Administration Login<br />
login.username = User Name<br />
login.password = Password<br />
login.submitlabel = Login<br />
logout.label = Logout<br />
logout.submitlabel = Logout<br />
error.username.required = Please specify a user name.<br />
error.password.required = Please specify a password.<br />
error.password.mismatch = Invalid username or password entered.<br />
admin1.title = Administration Menu - Read<br />
Access<br />
admin2.title = Administration Menu - Write<br />
Access<br />
4. Close the file and save it when prompted.<br />
432 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
12.3.7 Realizing and editing the Web pages<br />
Up to this point, we have added the Web pages, action mappings, and<br />
connections to the Web diagram. All of the nodes are unrealized (grey icon) and<br />
we will now go through the process of realizing them.<br />
Tip: When you cursor over a node on the free-form surface of the Web<br />
diagram editor, the name or path of the node is given. It also tells you if the<br />
node is unrealized or realized.<br />
Login page<br />
To realize the login Web page node:<br />
1. From the LoginProcess Web diagram, double-click the login.jsp Web page<br />
node to invoke the JSP wizard.<br />
2. Verify that the File Name field value is login.jsp and that the Model<br />
drop-down has Struts JSP selected.<br />
3. Click Finish. The login.jsp page is created and opened in Page Designer.<br />
4. View the source of the page using the Source tab. Note that the taglib<br />
directives are automatically added into the JSP. Also, a Struts-html form tag is<br />
inserted with action /login.<br />
Example 12-2 login.jsp<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Chapter 12. Using Struts 433
You will notice that there is a warning on the page indicating that the target<br />
/login cannot be resolved. We will resolve this later by defining the<br />
corresponding action class.<br />
Figure 12-26 login.jsp warning<br />
5. Right after the tag, add a bean message tag by selecting<br />
JSP -> Insert Custom from the main menu. An alternative way to do this is to<br />
drag and drop the Custom icon from the toolbar on the right to the desired<br />
location in the editing area. Both methods will cause the Insert Custom Tag<br />
dialog to open.<br />
6. Select the tag library with the prefix bean from the left pane and select the<br />
message tag from the right pane.<br />
Figure 12-27 Insert custom tag dialog<br />
7. Click Insert. You will notice that a tag has been added.<br />
434 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Example 12-3 Adding a bean message tag<br />
<br />
<br />
<br />
<br />
<br />
8. Click Close.<br />
9. Add the key attribute to the bean message tag and set the value to<br />
login.title.<br />
<br />
This value corresponds to a property set in the<br />
<strong>Application</strong>Resources.properties file. At runtime, the Struts framework reads<br />
the value of the property and the bean message tag displays it.<br />
10.Click a spot inside the tags and<br />
add another bean message tag.<br />
11.Add the key attribute to the bean message tag and set the value to<br />
login.username.<br />
<br />
12.Add a tag after the closing tag of the bean message.<br />
13.Add another bean message after the tag and set the key attribute to<br />
login.password.<br />
Example 12-4 Adding a second bean message tag<br />
<br />
<br />
<br />
<br />
<br />
14.Click a spot after the username bean message tag and before the tag;<br />
add a custom HTML text tag and set the property attribute to username. This is<br />
done in the same way as adding a custom bean tag, except that this time, you<br />
must select the tag library with the html prefix (see Figure 12-27 on<br />
page 434).<br />
Chapter 12. Using Struts 435
Example 12-5 Adding a html text tag<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
15.Click a spot after the password bean message tag and add a custom HTML<br />
password tag.<br />
16.Set the property attribute to password.<br />
<br />
17.Add a tag after the closing tag of the HTML password tag.<br />
18.Insert an HTML submit tag after the tag.<br />
Example 12-6 Adding a html submit tag<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
19.Click a spot between the opening and closing HTML submit tags and insert a<br />
bean message tag; set the key attribute to login.submitlabel.<br />
Example 12-7 Adding a bean message tag<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
436 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
20.Right above the tag, insert an HTML errors tag.<br />
When the login action redirects the user to the login page because of an error,<br />
the errors will be displayed at the top of the login.jsp page.<br />
21.Verify that the code is similar to the example below.<br />
Example 12-8 Content area of login.jsp<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
22.While in the Preview page of Page designer, the login.jsp page should look<br />
similar to Figure 12-28.<br />
Figure 12-28 Preview page of login.jsp<br />
Chapter 12. Using Struts 437
23.Save your changes and exit the Page designer.<br />
Admin1 page<br />
To realize the admin1 Web page node, follow these steps.<br />
1. Realize the admin1.jsp page node in the same fashion that the login.jsp page<br />
node was realized.<br />
2. Once the admin1.jsp page is created and opened in Page designer, click the<br />
Source tab. Note that the Struts HTML form tag is automatically inserted into<br />
the JSP withthe action set to /logout.<br />
3. Since the admin1 page does not contain any input parameters, we do not<br />
need an HTML form tag. Remove the code associated with the HTML form<br />
tag.<br />
4. Add a message bean tag after the tag and set the key attribute to<br />
admin1.title.<br />
<br />
5. After the message bean title tag, insert the code shown in the following<br />
example.<br />
Example 12-9 Menu for admin1.jsp<br />
<br />
<br />
View<br />
Customers<br />
View<br />
Orders<br />
<br />
<br />
Ignore the two warnings indicating the broken links. We are not concerned at<br />
this point with what the menu system does, rather we simply wish to get the<br />
login function working for our site.<br />
6. Between the third set of tags, add an HTML link tag and set the<br />
href attribute to /OnlineCatalog/logout.do. This inserts a link to the Logout<br />
action which redirects the administrator to the login page. As was the case in<br />
the login.jsp page, a warning is displayed indicating that the target logout.do<br />
cannot be resolved. This will be created later in the sample.<br />
7. Between the HTML link tags, add a message bean tag and set the key<br />
attribute to logout.label.<br />
8. Verify that the code is similar to the following example.<br />
438 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Example 12-10 admin1.jsp<br />
<br />
<br />
<br />
<br />
View<br />
Customers<br />
View<br />
Orders<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
9. While in the Preview page of Page designer, the admin1.jsp page should look<br />
similar to the following diagram.<br />
Figure 12-29 Preview page of admin1.jsp<br />
10.Save your changes and exit the Page Designer.<br />
Chapter 12. Using Struts 439
Admin2 page<br />
The admin2.jsp page will be identical to the admin1.jsp page, however the<br />
message bean title tag will have a key attribute set to admin2.title and the<br />
menu of the page will contain two different options.<br />
1. Realize the admin2.jsp and then verify that the code added to it is similar to<br />
the code shown in the example below.<br />
Example 12-11 admin2.jsp<br />
<br />
<br />
<br />
Add Item<br />
Modify or Delete<br />
Item<br />
<br />
<br />
<br />
<br />
<br />
<br />
2. Save your changes and exit the Page designer.<br />
12.3.8 Creating the form bean<br />
With all of the Web pages in place, we can now create a form bean using the<br />
ActionForm wizard. An instance of this class is used to validate the input<br />
parameters from the login.jsp page. Note that it is not always necessary to create<br />
an ActionForm class for each JSP within the application.<br />
To create a form bean:<br />
1. In the Project Navigator view in the Web Perspective, navigate to the<br />
OnlineCatalog/JavaSource folder.<br />
2. Right-click the folder and select New -> Other from the context menu.<br />
3. In the New window, select Web -> Struts from the left pane and ActionForm<br />
class from the right pane. Click Next to invoke the ActionForm class wizard.<br />
4. Change the ActionForm class name field value from Form to LoginForm.<br />
440 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-30 Creating an ActionForm class<br />
5. Click Next.<br />
6. On the next page, navigate to the Web Pages folder and select the box beside<br />
the login.jsp page.<br />
Chapter 12. Using Struts 441
Figure 12-31 Creating an ActionForm class<br />
7. Click Next.<br />
8. On the next page, you will notice that the password and username fields have<br />
been created.<br />
Figure 12-32 Creating an ActionForm class<br />
9. Click Next.<br />
10.Leave the defaults on the Create a mapping for your ActionForm class page<br />
and click Finish.<br />
442 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-33 Creating an ActionForm class<br />
This generates the template code for the LoginForm class and opens the<br />
corresponding file in the Java editor.<br />
Note: In the JavaSource folder of the OnlineCatalog project, a package<br />
called onlinecatalog.forms has been created and contains the<br />
LoginForm.java file.<br />
11.Replace the validate method with the following code.<br />
Example 12-12 Validate method code<br />
public ActionErrors validate(<br />
ActionMapping mapping,<br />
HttpServletRequest request) {<br />
ActionErrors errors = new ActionErrors();<br />
// Validate the fields in your form, adding each error to<br />
this.errors as found.<br />
if((username == null) || (username.length() < 1))<br />
errors.add("username", new<br />
ActionError("error.username.required"));<br />
if((password == null) || (password.length() < 1))<br />
errors.add("password", new<br />
ActionError("error.password.required"));<br />
return<br />
errors;<br />
Chapter 12. Using Struts 443
The method returns errors if either the username or password is not specified<br />
in the login.jsp page. Note the parameters used to construct an instance of<br />
ActionError class. Each string parameter represents a property set in the<br />
<strong>Application</strong>Resources.properties file. The Struts framework handles the task<br />
of reading the property values from this file at run-time.<br />
12.Once you add the code above, you will get an error on two lines stating that<br />
ActionError cannot be resolved or is not type. To fix these errors, add the<br />
following import statement at the top of the LoginForm code (with the other<br />
import statements):<br />
import org.apache.struts.action.ActionError;<br />
13.Save your changes and close the Java editor.<br />
12.3.9 Realizing and editing the action classes<br />
As depicted in the Web diagram, the application uses two action classes; one to<br />
handle the administrator login and another to handle administrator logouts.<br />
Login action class<br />
To realize the action class for login:<br />
1. Double-click the /login action mapping node in the Web diagram editor to<br />
invoke the Action mapping wizard.<br />
2. On the New Action Mapping page, select loginForm as the Form Bean Name<br />
from the drop-down list.<br />
444 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-34 Creating /login action mapping<br />
3. Click Finish. This generates the template code for the LoginAction class and<br />
opens the corresponding file in the Java editor. Replace the code for the<br />
LoginAction class with the code from the following example.<br />
Note: A package called onlinecatalog.actions has been created in the<br />
JavaSource folder of the OnlineCatalog project. It contains the code for the<br />
LoginAction.java file.<br />
Chapter 12. Using Struts 445
Example 12-13 LoginAction class<br />
public class LoginAction extends Action {<br />
public ActionForward execute(<br />
ActionMapping mapping,<br />
ActionForm form,<br />
HttpServletRequest request,<br />
HttpServletResponse response)<br />
throws Exception {<br />
ActionErrors errors = new ActionErrors();<br />
//return value<br />
ActionForward forward = new ActionForward();<br />
//Get the Form to read the user's input<br />
LoginForm loginForm = (LoginForm) form;<br />
String userName = loginForm.getUsername();<br />
String password = loginForm.getPassword();<br />
// Write logic determining how the user should be forwarded.<br />
// For simplicity, the user input is checked against a known set<br />
// of userid/passwords. In a business application, the<br />
// the username/password validation is done against an underlying<br />
// database storing users' information.<br />
//START LOGIN LOGIC<br />
if (userName.equals("admin1") && password.equals("admin1"))<br />
{<br />
forward = mapping.findForward("admin1page");<br />
}<br />
else if (userName.equals("admin2") && password.equals("admin2"))<br />
{<br />
forward = mapping.findForward("admin2page");<br />
}<br />
else<br />
{<br />
errors.add(ActionErrors.GLOBAL_ERROR, new<br />
ActionError("error.password.mismatch"));<br />
forward = mapping.findForward("failure");<br />
}<br />
//END LOGIN LOGIC<br />
//Report any errors we have discovered. These errors are displayed<br />
//on the destination page respresented by the 'forward' object<br />
if(!errors.isEmpty())<br />
446 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
{<br />
}<br />
saveErrors(request, errors);<br />
//Finish with<br />
return (forward);<br />
}<br />
}<br />
Note: For simplicity, the logic of authenticating the administrator has been<br />
implemented within the action class itself. In a practical Web application,<br />
the action class should invoke model objects which implement the<br />
business logic.<br />
4. Save your changes and close the Java editor.<br />
5. From the Web diagram editor, double-click the /login action mapping node to<br />
open the Configuration file editor.<br />
6. The editor opens to the Action Mappings tab with the /login action mapping<br />
selected.<br />
7. Select the Local Forwards tab at the top of the page. Notice that the<br />
forwards have been set for the /login action mapping.<br />
Chapter 12. Using Struts 447
Figure 12-35 Local forwards for the /login action mapping<br />
8. Select the Action Mappings tab at the top of the page and verify that the<br />
Form Bean Name field value is set to loginForm.<br />
9. In the Action Mapping attributes area of the page, enter /login.jsp in the<br />
Input field.<br />
448 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-36 Action mapping attributes for the /login action mapping<br />
10.Save the changes and close the Configuration file editor.<br />
Logout action class<br />
To realize the action class for logout:<br />
1. Double-click the /logout action mapping node in the Web diagram editor to<br />
invoke the Action mapping wizard.<br />
2. Leave all the defaults and click Finish. This generates the template code for<br />
the LogoutAction class and opens the corresponding file in the Java editor.<br />
Note: In the JavaSource folder of the OnlineCatalog project, a package called<br />
onlinecatalog.actions has been created and contains the LogoutAction.java<br />
file.<br />
3. Replace the code for the LogoutAction class with the code from the following<br />
example.<br />
Chapter 12. Using Struts 449
Example 12-14 LogoutAction class<br />
public class LogoutAction extends Action {<br />
}<br />
public ActionForward execute(<br />
ActionMapping mapping,<br />
ActionForm form,<br />
HttpServletRequest request,<br />
HttpServletResponse response)<br />
throws Exception {<br />
}<br />
ActionErrors errors = new ActionErrors();<br />
// return value<br />
ActionForward forward = new ActionForward();<br />
// Write logic determining how the user should be forwarded.<br />
forward = mapping.findForward("success");<br />
// Finish with<br />
return (forward);<br />
The perform method returns an instance of ActionForward corresponding to<br />
success.<br />
4. Save your changes and close the Java editor.<br />
5. With all of the nodes created, your LoginProcess Web diagram should look<br />
similar to Figure 12-37 on page 451.<br />
450 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 12-37 LoginProcess Web diagram<br />
12.3.10 Integrating with the Online Catalog sample template<br />
In the Online Catalog sample, we used the Web Site Designer to model and<br />
create some of the HTML and JSP pages in our application. These pages were<br />
based on a default page template we selected when creating the Web project.<br />
The final step in this process is to integrate the login.jsp page with the<br />
application. To do so, we will add the page to the Web site diagram. This will<br />
automatically add a hyperlink to all the pages in the application using the<br />
predefined template we originally selected when we created the project.<br />
Chapter 12. Using Struts 451
Important: If you use the Struts framework for this function of your<br />
application, you have to apply it to all the pages added thereafter.<br />
For example, you cannot hyperlink the menu functions of either the admin1.jsp<br />
or admin2.jsp pages to other pages. You would have to create an action for<br />
each forward. If you are forwarding for forms, you would be required to create<br />
form beans to capture the data and then create an action to perform any logic.<br />
This would be done in the same fashion as was illustrated above.<br />
1. From the Project Navigator view of the Web perspective, navigate to Web Site<br />
Configuration and double-click it to open the Web site diagram for the<br />
application.<br />
2. With the diagram open, locate the login.jsp page, drag it from the Project<br />
Navigator view and drop it behind the index.html page to create a child of the<br />
index.html page.<br />
3. To apply the template, select Page Template -> Apply Template... from the<br />
context menu.<br />
4. Disable the Navigation Candidate property by right-clicking the pages and<br />
selecting Navigation -> Navigation Candidate from the context menu. If you<br />
do not do this, all of the pages will appear in the site navigation.<br />
5. Add admin1.jsp and admin2.jsp. to the Web Site Configuration and apply the<br />
template.<br />
6. Save the Web site diagram.<br />
12.3.11 Understanding the Struts configuration file<br />
Up to this point, you have created Web pages, action forms and action classes to<br />
implement the site administration login process. As you created these<br />
components, Studio Site Developer internally modified the Struts configuration<br />
file.<br />
Navigate to the struts-config.xml file in the WEB-INF of the project and<br />
double-click it to open the editor. Click the Source tab and take a look at the tags<br />
in the file to understand how the various components work together within the<br />
Struts framework.<br />
During runtime, when the user enters the username and password in the<br />
login.jsp page and submits it, the following occurs:<br />
1. The ActionServlet forwards the user input to the form class represented by<br />
loginForm to validate the user input. The loginForm class and login.jsp should<br />
452 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
have a one-one relationship. The name of the input parameters in the<br />
login.jsp page must exactly match the field names of the loginForm class.<br />
2. If the input validation fails, the loginForm class returns an instance of the<br />
ActionErrors class. The ActionServlet then redirects the user to the login.jsp<br />
page.<br />
3. If the user entered a valid input, the ActionServlet invokes the perform method<br />
on an instance of onlinecatalog.LoginAction class passing the user input<br />
wrapped in an instance of loginForm class.<br />
4. Depending on the logic implemented in the perform method, the<br />
ActionServlet is returned an instance of ActionForward corresponding to one<br />
of the forwards in the action tag.<br />
Example 12-15 Struts configuration file entry<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
For example, if the user authentication fails, the perform method returns an<br />
ActionForward object corresponding to failure.<br />
5. The ActionServlet then reads the ActionForward object and performs the<br />
specified action. For example, if ActionForward to admin1page is returned,<br />
the ActionServlet redirects the user to the admin1.jsp page.<br />
Struts ActionServlet URL mapping<br />
In the web.xml file, under the OnlineCatalog/Web Content/WEB-INF folder, an<br />
entry is created to register the Struts’ ActionServlet with a corresponding<br />
mapping to ensure that Struts requests get passed to it. A common convention is<br />
that a URL mapping ending with do is a Struts request, such as /logout.do.<br />
In our sample, the admin1.jsp and admin2.jsp pages consist of the following lines<br />
of code to insert a link to logout of the menu page.<br />
<br />
<br />
<br />
Chapter 12. Using Struts 453
The ActionServlet handles the request, as specified by the URL mapping in the<br />
web.xml file, and checks the Struts configuration file for routing information. In<br />
our case, the configuration file consists of an entry for the logout action which<br />
corresponds to the URL request /OnlineCatalog/logout.do.<br />
454 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 13. Deploying applications<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express provides two application server<br />
environments for the deployment of applications. First, the <strong>WebSphere</strong> test<br />
environment provides a runtime test environment within Studio Site Developer.<br />
Second, the Express <strong>Application</strong> <strong>Server</strong> is provided as a standalone application<br />
server environment. It can be installed locally on the Studio Site Developer<br />
server or on a remote system.<br />
From a developer’s viewpoint, either can be used for testing applications,<br />
however, the management, operation, and deployment issues may differ<br />
depending on whether you are using the embedded test environment, a<br />
standalone application server reserved for testing, or deploying to a standalone<br />
production application server.<br />
This chapter provides information on the following:<br />
► Express <strong>Application</strong> <strong>Server</strong> and the <strong>WebSphere</strong> test environment<br />
► <strong>Server</strong> configuration and management using the <strong>Server</strong> tools<br />
► Deploying applications to production servers<br />
13<br />
© Copyright <strong>IBM</strong> Corp. 2003 455
13.1 <strong>Application</strong> server overview<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express consists of two major components. You<br />
have seen the development component, Studio Site Developer. Now we will take<br />
a look at the application server component which provides the runtime<br />
environment for the applications.<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express supports the following runtime<br />
environments:<br />
► <strong>WebSphere</strong> test environment: This is an instance of Express <strong>Application</strong><br />
<strong>Server</strong> that is installed as a part of Studio Site Developer. It is used to test<br />
applications as you are developing them.<br />
► Express <strong>Application</strong> <strong>Server</strong>: This is a standalone application server. It can be<br />
installed on the same machine as Studio Site Developer, or on a remote<br />
system. This standalone version of the application server is used to run the<br />
applications in a production environment. You may also have the case where<br />
a standalone application server has been installed for test purposes.<br />
Express <strong>Application</strong> <strong>Server</strong> is intended to be a single application server<br />
environment. It does not support the use of multiple servers for workload<br />
distribution. However, it is possible that you will have multiple servers defined for<br />
testing purposes.<br />
The primary component of the Express <strong>Application</strong> <strong>Server</strong> is the Web container.<br />
It provides the runtime environment for JSPs and servlets. It also contains an<br />
embedded HTTP server capable of serving static HTML Web pages.<br />
13.1.1 Configuration and management<br />
The methods you use to configure and manage an application server depend<br />
primarily on the circumstances.<br />
► Express <strong>Application</strong> <strong>Server</strong> administrative console and commands<br />
In a production environment, the administrative console application provided<br />
with Express <strong>Application</strong> <strong>Server</strong> is the preferred method of administration. It<br />
provides a Web-based console that can be used from any Web browser. It<br />
also exposes more configuration options than you find in the Studio Site<br />
Developer <strong>Server</strong> tools. You can use the administrative console to configure<br />
the server, deploy applications to it, and monitor server activity. You cannot,<br />
however, start and stop the application server from the administrative<br />
console. This is because the console is actually an application running on the<br />
server. Commands that can be entered from the operating system command<br />
line are provided for these functions.<br />
456 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► Studio Site Developer <strong>Server</strong> tools<br />
Developers who have control over an application server, whether it be in the<br />
Studio Site Developer test environment, or a remote application server set up<br />
for their use, will use the <strong>Server</strong> tools provided with Studio Site Developer,<br />
including elements like the <strong>Server</strong> perspective, <strong>Server</strong>s view, and Console<br />
view. The person managing and configuring the server is doing so from a<br />
workstation with Studio Site Developer installed. Using the <strong>Server</strong> tools, you<br />
can define servers, configure them, start and stop them, monitor their activity,<br />
and publish applications to them. In addition, you have access to the<br />
administrative console from the <strong>Server</strong> tools.<br />
Important: As a general rule, an application server should only be<br />
administered in one way. In other words, if you use the administrative console<br />
to administer a server, do not also use the <strong>Server</strong> tools to administer it. Any<br />
changes made by the administrative console will not be seen by the <strong>Server</strong><br />
tools and vice versa.<br />
In this redbook, we will discuss using the <strong>Server</strong> tools to manage application<br />
servers and deploy applications to them. Information about the administrative<br />
console and commands can be found in the <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express V5.0.1 Administrator Handbook, SG24-6976.<br />
13.1.2 Managing test application servers<br />
Figure 13-1 on page 458 shows an application development scenario. In this<br />
example, when <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express was installed on the<br />
development machine, the default install options were taken, meaning that both<br />
Studio Site Developer (including the <strong>WebSphere</strong> test environment) and a<br />
standalone Express <strong>Application</strong> <strong>Server</strong> were installed. In addition, Express<br />
<strong>Application</strong> <strong>Server</strong> was installed on three remote systems to allow testing on<br />
multiple platforms.<br />
Chapter 13. Deploying applications 457
<strong>Application</strong><br />
developer<br />
Internet<br />
user<br />
Windows / Linux<br />
<strong>WebSphere</strong> Studio<br />
<strong>WebSphere</strong> Test<br />
Environment<br />
Express<br />
<strong>Application</strong><br />
<strong>Server</strong><br />
Agent<br />
Controller<br />
Internet<br />
TCP/IP<br />
FTP<br />
app1.ear<br />
Agent<br />
Controller<br />
FTP<br />
server<br />
Agent<br />
Controller<br />
FTP<br />
server<br />
Agent<br />
Controller<br />
FTP<br />
server<br />
Figure 13-1 <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express development and runtime<br />
environment<br />
Multiple servers, both local and remote, can be managed from Studio Site<br />
Developer. Each server is a separate entity, meaning no workload management<br />
is implied.<br />
The <strong>IBM</strong> Agent Controller (installed with the Express <strong>Application</strong> <strong>Server</strong>)<br />
provides the mechanism for communication between the <strong>Server</strong> tools and the<br />
application server.<br />
An FTP server is used on the remote systems to receive the application files to<br />
be deployed.<br />
458 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Linux<br />
Express <strong>Application</strong> <strong>Server</strong><br />
Agent<br />
Embedded<br />
HTTP <strong>Server</strong><br />
JSP<br />
Web container<br />
servlet<br />
iSeries<br />
Express <strong>Application</strong> <strong>Server</strong><br />
Agent<br />
Embedded<br />
HTTP <strong>Server</strong><br />
JSP<br />
Web container<br />
servlet<br />
Windows<br />
Express <strong>Application</strong> <strong>Server</strong><br />
Agent<br />
Embedded<br />
HTTP <strong>Server</strong><br />
JSP<br />
Web container<br />
servlet
13.2 Using the <strong>Server</strong> tools<br />
Studio Site Developer provides wizards and views that make configuring and<br />
managing an application server environment simple. To illustrate these tools, we<br />
will look at them from the <strong>Server</strong> perspective. The views and wizards available<br />
from this perspective are designed to working with application servers easy and<br />
intuitive. The <strong>Server</strong> perspective puts these tools at your fingertips, but note that<br />
most of the views are also available in the Web perspective by default.<br />
Let us take a look at some of the views (as seen in Figure 13-2).<br />
► The <strong>Server</strong> Configuration view (bottom left) enables you to define or modify<br />
server instances and configurations, and bind them to a project. When you<br />
double-click the server in the <strong>Server</strong> Configuration view, the <strong>Server</strong><br />
Configuration editor opens.<br />
► The <strong>Server</strong>s view (bottom right) lists all the currently defined server instances.<br />
Here you can start or stop their execution, or assign another server<br />
configuration to a server instance.<br />
► The Console view (currently hidden by the <strong>Server</strong>s view) shows all the output<br />
listed by a running server instance.<br />
Figure 13-2 The <strong>Server</strong> perspective<br />
Chapter 13. Deploying applications 459
Note: The Web perspective also contains the <strong>Server</strong>s view, the <strong>Server</strong><br />
Configuration view, and the Console view. You may find it easier to work in the<br />
Web perspective when you are testing an application.<br />
13.2.1 Setting preferences for the <strong>Server</strong> perspective<br />
There are preference settings that you may want to update once you start using<br />
the <strong>Server</strong> perspective. To define these preferences, do the following:<br />
1. From the toolbar, select Window -> Preferences -> <strong>Server</strong>.<br />
2. Expand the <strong>Server</strong> entry.<br />
Figure 13-3 <strong>Server</strong> preferences window<br />
The default options are shown in Figure 13-3. Among the options, we<br />
recommend paying attention to the following:<br />
– Automatically publish before starting servers<br />
Specifies that all the files should automatically be published before starting<br />
the server.<br />
460 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
– Keep publishing dialog open after publishing<br />
Specifies that a monitor opens to display messages when files are<br />
published. This is helpful if you have a problem with publishing, but for the<br />
most part it is not necessary.<br />
– Automatically restart servers when necessary<br />
Specifies that Studio Site Developer can automatically restart the server<br />
when it detects that the server must be restarted to handle resource<br />
changes in the workspace. This setting is fine for the test environment, but<br />
you probably do not want this setting if other people will be using the<br />
server.<br />
– Prompt before making irreversible changes with an editor<br />
Specifies that the server tools will prompt you before you make a change<br />
in a editor that cannot be undone.<br />
– Save dirty editors before starting the server<br />
Determines whether to save editors with unsaved changes before starting<br />
the server.<br />
– Repair invalid servers<br />
Occasionally, the server configuration may become out of sync with<br />
existing conditions in the workspace. This usually happens when an EAR<br />
file has been modified or deleted so the information in the server<br />
configuration is incorrect. This is easily fixed by allowing Studio Site<br />
Developer to perform repairs but it is probably a good idea to select the<br />
Prompt option so you have a chance to decline the repairs.<br />
– Publishing method:<br />
Smart publish (select): Specifies that you only want to publish changed<br />
resources to the server. All resources that no longer exist in the<br />
workspace are deleted on the server. This is the default value.<br />
Prompt user: Specifies that you want to choose which resources to<br />
publish to the server or to remove from the server.<br />
Publish all: Specifies that you want to publish all resources to the<br />
server, regardless of whether they have changed. No resources are<br />
deleted from the server.<br />
3. Click Apply and then OK to save your changes.<br />
Chapter 13. Deploying applications 461
13.3 Defining servers and server configurations<br />
Every server instance you plan to use, whether it is a local server, remote server,<br />
or the <strong>WebSphere</strong> test environment, must be represented by a server definition<br />
and a server configuration definition.<br />
The server definition defines the host where the server resides and the directory<br />
information needed to locate the application server. Each server definition has an<br />
associated server configuration that contains the information needed to set up<br />
the runtime environment, such as port information, data sources, MIME types,<br />
and session management information.<br />
<strong>Server</strong> 1<br />
Host name: server1.ibm.com<br />
<strong>WebSphere</strong> installation directory<br />
<strong>WebSphere</strong> deployment directory<br />
DB2 driver location<br />
Remote file transfer definitions<br />
Operating system<br />
<strong>Server</strong> 2<br />
Host: server2.ibm.com<br />
<strong>WebSphere</strong> installation directory<br />
<strong>WebSphere</strong> deployment directory<br />
DB2 driver location<br />
Remote file transfer definitions<br />
Platform<br />
Figure 13-4 <strong>Server</strong>s and server configurations<br />
<strong>Server</strong> and server configuration definitions are usually created at the same time<br />
and for all practical purposes look like the same thing. They are represented by<br />
one entry in the standard <strong>Server</strong> Configuration view. To view both the server and<br />
server configurations, you will need to change the <strong>Server</strong> Configurations view to<br />
its advanced setting.<br />
462 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
or<br />
<strong>Server</strong> configuration a<br />
Data sources<br />
Class paths<br />
Security settings<br />
Host alias<br />
Ports<br />
application 1<br />
Session management application 2<br />
Class loader policy<br />
<strong>Server</strong> configuration b<br />
<strong>Server</strong> configuration c<br />
application 3<br />
application 4<br />
application 1<br />
application 2
Figure 13-5 Advanced <strong>Server</strong> Configuration view<br />
To create a server or server configuration independent of one another, you need<br />
to use the context menu for the <strong>Server</strong>s project in the Navigator view.<br />
Chapter 13. Deploying applications 463
Figure 13-6 Creating servers and server configurations<br />
The server - server configuration relationship is a one-to-one relationship;<br />
however, you can create alternate configurations and switch the server to use the<br />
new configuration. Note that the server has to be stopped before you can switch<br />
the configuration. You can switch configurations from the context menu of the<br />
server in the <strong>Server</strong> Configurations view.<br />
When you open a server, the editor will show the information in a series of tabs.<br />
The server definition consists of the items you see on the server tab when you<br />
open it. The remaining tabs contain the server configuration information. You can<br />
see this for yourself by opening a server that has no configuration associated<br />
with it (you will only see the <strong>Server</strong> tab) or by opening a configuration that isn’t<br />
associated with a server (you will see all the tabs but the <strong>Server</strong> tab).<br />
464 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
13.3.1 <strong>Server</strong> types<br />
Table 13-1 lists the types of servers supported by Studio Site Developer.<br />
Table 13-1 Summary of server types<br />
<strong>Server</strong> type Use<br />
<strong>WebSphere</strong> Version 5.0<br />
Express server Express <strong>Application</strong> <strong>Server</strong> installed locally or<br />
remotely.<br />
Express test environment The Express <strong>Application</strong> <strong>Server</strong> internal to Studio<br />
Site Developer.<br />
Express server attach Used to attach to an application server and then<br />
debug the Web objects running on it.<br />
Other types<br />
J2EE Publishing server Used for publishing static Web and J2EE projects to<br />
a remote location or a J2EE application server<br />
(assumes port 80). This just copies the application<br />
to the specified directory. It does not update<br />
httpd.conf, nor does it allow you to start or stop the<br />
server. It is always “started.” There is no stop option.<br />
Static Web publishing server Used for publishing Web projects to an HTTP server.<br />
TCP/IP monitoring server Allows you to monitor TCP/IP activity between the<br />
Web browser and application server (does not<br />
publish or run applications).<br />
We will focus on the Express server and Express test environment. For<br />
information on the others, please refer to the help contents in Studio Site<br />
Developer.<br />
13.4 Using the Express test environment<br />
The easiest way to get started with testing applications is to begin with the<br />
<strong>WebSphere</strong> test environment. This should be the first place you deploy an<br />
application during development and where you test at each development stage.<br />
To use the test environment, you need to do the following:<br />
1. Create a server and server configuration.<br />
2. Publish the enterprise application to the server.<br />
Chapter 13. Deploying applications 465
3. Update the server configuration for application-specific values (variables, data<br />
sources, etc.).<br />
4. Start the server.<br />
5. Run the application.<br />
13.4.1 Creating a server and server configuration<br />
The first step is to create the test environment server.<br />
Tip: If you are doing Web application development, you can create and use<br />
the server environment directly from the Web perspective, as we are doing<br />
here. You do not need to open the <strong>Server</strong> perspective.<br />
To create the server:<br />
1. Right-click the <strong>Server</strong>s folder in the Navigator view and select New -> <strong>Server</strong><br />
and <strong>Server</strong> Configuration.<br />
Figure 13-7 Create a server and configuration<br />
2. Enter a server name and select the Express Test Environment option under<br />
<strong>WebSphere</strong> Version 5.0.<br />
466 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 13-8 Select the server type<br />
3. Click Next.<br />
4. Leave the default (7080) for the HTTP port. This option allows you to specify a<br />
unique port for the server to avoid conflicts with other processes on the<br />
system or with other servers. If you define multiple servers, setting this port to<br />
a unique number for each server is not enough to allow you to run the servers<br />
simultaneously. <strong>Server</strong>s actually use several port numbers in addition to this.<br />
When the server configuration is complete, you can open it to the Ports tab to<br />
view or change the ports.<br />
5. Click Finish.<br />
The new server environment will be configured and you will see it in the <strong>Server</strong><br />
Configuration view.<br />
Chapter 13. Deploying applications 467
13.4.2 Publishing an application to the test environment<br />
To publish an application to the test environment, do the following:<br />
1. Select the server in the <strong>Server</strong>s view or the <strong>Server</strong> Configuration view.<br />
Right-click and select Add and remove projects....<br />
Figure 13-9 Add an application to the server<br />
2. Select the enterprise application from the Available Projects list and click<br />
Add.<br />
468 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 13-10 Select the enterprise application to publish<br />
3. The application will be deployed to the test environment and you will see an<br />
entry for the application appear under the server.<br />
Note: Only enterprise applications can be added to a server. If you have<br />
been working with a Web module but have not added it to an enterprise<br />
application project, you will need to do this first.<br />
You can create an enterprise application by selecting File -> New -><br />
Project. Select J2EE and Enterprise <strong>Application</strong> Project. Once you have<br />
created the enterprise application, open the application deployment<br />
descriptor (application.xml), switch to the Modules tab, and add the Web<br />
module.<br />
4. In the <strong>Server</strong>s view, you will see the server listed. The <strong>Server</strong> State column<br />
indicates that the server needs to be republished. Although we have<br />
associated an application with the server configuration, we have not actually<br />
put the application on the server.<br />
Chapter 13. Deploying applications 469
Note: If you have not changed the server preferences from the default, the<br />
publish will happen automatically when you start the server and you will not<br />
need to perform the next step, which publishes the server manually. You<br />
can check the preferences by clicking Window -> Preferences -> <strong>Server</strong>.<br />
The Automatically publish before starting servers option should be<br />
selected.<br />
5. Select the server in the <strong>Server</strong>s view, right-click, and select Publish.<br />
Figure 13-11 Publish the application<br />
Once the publish is complete, the server state should indicate that the server<br />
is synchronized.<br />
13.4.3 Updating the server configuration for the application<br />
If the application you are testing has requirements for the runtime environment,<br />
you will need to add them at this point. For example, if you are using a data<br />
source to access a database, you will need to define the JDBC driver and data<br />
source. If you are using JAAS for database authentication, you will need to add<br />
the JAAS authentication entry. These steps are the same whether you are using<br />
the Express test environment or a standalone Express <strong>Application</strong> <strong>Server</strong>. To<br />
update the server configuration to add these resources, see 13.6, “Working with<br />
server configurations” on page 483.<br />
470 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
13.4.4 Starting the test environment server<br />
So far, you have defined a server and published an application to it. The next step<br />
is to start the server.<br />
1. Select the server in the <strong>Server</strong>s view, right-click, and select Start (or highlight<br />
the server and select the Start the <strong>Server</strong> icon at the top of the view).<br />
Figure 13-12 Start the server<br />
2. The Console view will open automatically, showing you the server runtime<br />
messages. Monitor the console for error messages as the server starts. If you<br />
see problems or if the server doesn’t start, review the console messages,<br />
correct the problem, and try again.<br />
Chapter 13. Deploying applications 471
Figure 13-13 Check the console for messages<br />
The message you need to see is the last one shown in Figure 13-13, <strong>Server</strong><br />
server1 open for e-business. This indicates that the server started<br />
successfully.<br />
13.4.5 Running the application<br />
The last step in the process is to test the application.<br />
1. Find the project or file you want to test in the Navigation view, right-click, and<br />
select Run on <strong>Server</strong>.<br />
472 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 13-14 Run the application<br />
Note that in this case, we tested the application by selecting the Web project.<br />
You could also test segments of the application by selecting a specific file.<br />
Obviously, the file you select needs to be a logical starting point in the<br />
application.<br />
2. You will be asked to select a server. Select the test environment server that<br />
you just created and continue.<br />
Chapter 13. Deploying applications 473
Tip on setting a server preference: If you don’t want this prompt in the<br />
future, you can select the Set server as project default box. To change<br />
the setting or preference later, use the Web project preferences. Select the<br />
Web project in the Navigator view, right-click, and select Properties. Select<br />
the <strong>Server</strong> Preference menu.<br />
When you run the application, it will run on the server set in the<br />
preferences. If the server is stopped, Studio Site Developer will attempt to<br />
start it. This can be confusing if you have multiple servers and have not set<br />
the ports for each server to be unique. If another server is running, you will<br />
see port conflicts when the second server is started.<br />
Figure 13-15 Select a server<br />
3. The application will open in a Web browser. You can exercise the application<br />
code from there.<br />
474 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 13-16 Test the application<br />
Be sure to keep an eye on the Console view to see if any error messages are<br />
generated.<br />
Tip: If you select Run on <strong>Server</strong> for an application that has not been<br />
published you will be given the opportunity to create a new server or to run on<br />
an existing server. This is a shortcut to the steps we have just been through;<br />
however, we found that it did not save us any time and we liked controlling the<br />
server creation and publishing process ourselves.<br />
13.5 Working with an Express server<br />
You have tested the application in the <strong>WebSphere</strong> test environment and are now<br />
ready to deploy the application to a “real” server. This server can be a local<br />
instance of Express <strong>Application</strong> <strong>Server</strong> or a remote instance.<br />
Chapter 13. Deploying applications 475
The following are the steps required to do this:<br />
1. Install the Express <strong>Application</strong> <strong>Server</strong>.<br />
The installation will include the <strong>IBM</strong> Agent Controller which is used to enable<br />
communication between Studio Site Developer and Express <strong>Application</strong><br />
<strong>Server</strong>. The only indication you will see that the <strong>IBM</strong> Agent Controller is<br />
installed is the presence of the /RAC directory in the<br />
installation path, and on Windows, you will see a new service called <strong>IBM</strong><br />
Agent Controller.<br />
You will also need a file sharing mechanism, either a shared disk or FTP<br />
between the two servers so that the application files can be transferred to the<br />
server.<br />
2. Define the server and server configuration. This will identify the location of the<br />
server and its characteristics.<br />
3. Publish the enterprise application to the server. The application files will be<br />
copied or FTP’ed to the server location.<br />
4. Update the server configuration for application-specific values (variables, data<br />
sources, etc.)<br />
5. Start the server.<br />
6. Run the application.<br />
13.5.1 Defining the server to Studio Site Developer<br />
As we have seen from using the test environment, the first step to deployment is<br />
to define the server to Studio Site Developer. Defining a remote server (remote to<br />
Studio Site Developer, not necessarily on a remote system) is a little more<br />
involved than defining the test environment. Additional information, such as the<br />
location of the server, the remote server installation path, how to transfer the<br />
application and deployment information to the server, and how to access the<br />
HTTP port, is needed in order for Studio Site Developer to operate the server and<br />
to deploy applications to it.<br />
To define a remote Express <strong>Application</strong> <strong>Server</strong>:<br />
1. Right-click the <strong>Server</strong>s folder in the Navigator or <strong>Server</strong> Configuration view<br />
and select New -> <strong>Server</strong> and <strong>Server</strong> Configuration.<br />
2. Enter a server name and select the Express <strong>Server</strong> option under<br />
<strong>WebSphere</strong> Version 5.0, then enter a name for the server.<br />
476 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 13-17 Select the server type<br />
Click Next.<br />
3. Enter the IP address or host name of the remote server. If the server is on the<br />
same machine, enter 127.0.0.1 or localhost and click Next.<br />
4. If the <strong>IBM</strong> Agent Controller is working properly, the directory location for the<br />
<strong>WebSphere</strong> installation should be filled in for you. If you are going to use a<br />
DB2 server for application data, enter the location of the DB2 driver on the<br />
server system.<br />
Chapter 13. Deploying applications 477
Figure 13-18 Define the remote server settings<br />
Click Next.<br />
5. When an application is published from Studio Site Developer to the server,<br />
the application files must be copied to the server. In this panel, you select the<br />
file transfer mechanism to use when publishing applications to the server.<br />
478 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 13-19 Select a file transfer or copy instance<br />
Because we are defining a server on the local machine, the copy mechanism<br />
makes the most sense. This is also a good choice if you are copying files to<br />
another Windows system and have a network mapping to the application<br />
server’s local disk.<br />
If you select the FTP file transfer mechanism, make sure that you have an<br />
FTP server on the target system.<br />
Click Next.<br />
6. The next panel will differ depending on the file transfer mechanism you<br />
selected. It allows you to enter the information necessary for the transfer to<br />
take place, including the target directory (the server home directory).<br />
Figure 13-20 on page 480 shows the window for the copy file option.<br />
Chapter 13. Deploying applications 479
Figure 13-20 Defining the copy settings<br />
The definitions you enter will be stored for future use in other server<br />
configurations. The Project folder and Remote file transfer name fields are<br />
used to determine where this definition will be stored.<br />
Tip: The remote file transfer settings are stored with a file type of .rft. You<br />
can see these under the <strong>Server</strong>s folder in the Navigator view of the <strong>Server</strong><br />
perspective.<br />
Accept the defaults and click Next.<br />
480 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Tips: To predefine file transfer mechanisms, you can set up the copy or file<br />
transfer mechanisms ahead of time by using File -> New -> Other -><br />
Remote Transfer File. Give each remote file transfer definition a<br />
meaningful name (for example, To<strong>Server</strong>x or ToLocalTest) so you can<br />
easily select the appropriate profile when you are creating server<br />
configurations.<br />
To change the file transfer mechanism used to publish to a server: If you<br />
want to change the remote file transfer definition to be used to publish to a<br />
server, open the <strong>Server</strong> definition (in the <strong>Server</strong>s Configuration view) and<br />
change the designation on the <strong>Server</strong>s page.<br />
7. Select an HTTP port. The default is 7080.<br />
8. Click Finish.<br />
13.5.2 Publishing the application<br />
Publishing an application to a remote server works the same way as in the test<br />
environment. To publish an application to the remote server:<br />
1. Select the server in the <strong>Server</strong> Configuration view, right-click, and select Add<br />
and remove projects....<br />
2. Select the enterprise application in the Available Projects list and click Add.<br />
3. Click Finish. You will see an entry for the application appear under the server<br />
in the <strong>Server</strong> Configuration view.<br />
4. Select the server in the <strong>Server</strong>s view, right-click, and select Publish.<br />
5. If the application will require any server definitions (for example, class path or<br />
data source information), see 13.6, “Working with server configurations” on<br />
page 483 for information on how to make these configuration changes.<br />
What happens when you deploy an application<br />
When you deploy an application to an Express <strong>Application</strong> <strong>Server</strong>, the file<br />
structure required by the server is created and the files are copied to the server.<br />
You can see the new folders in two places on the server:<br />
► /installedApps/DefaultNode/.ear<br />
► /config/cells/DefaultNode/applications/.ear<br />
Chapter 13. Deploying applications 481
Figure 13-21 Deployed application files on the server<br />
13.5.3 Updating the server configuration for the application<br />
If the application you are testing has requirements for the runtime environment,<br />
you will need to add them at this point. For example, if you are using a data<br />
source to access a database, you will need to define the JDBC driver and data<br />
source. If you are using JAAS for database authentication, you will need to add<br />
the JAAS authentication entry. These steps are the same whether you are using<br />
the Express test environment or a standalone Express <strong>Application</strong> <strong>Server</strong>. To<br />
update the server configuration to add these resources, see 13.6, “Working with<br />
server configurations” on page 483.<br />
13.5.4 Starting the Express server<br />
The next step is to start the server.<br />
1. Select the server in the <strong>Server</strong>s view, right-click, and select Start or highlight<br />
the server and select the Run icon at the top of the view.<br />
482 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
2. The Console view will open automatically. Look for messages indicating that<br />
the server started properly. If you get error messages or if the server does not<br />
start, review the console messages, correct the problem, and try again.<br />
The message you want to see is <strong>Server</strong> server1 open for e-business.<br />
Note: If you have installed the Express <strong>Application</strong> <strong>Server</strong> on the same<br />
machine as your Studio Site Developer system, there will be port conflicts<br />
between the Express <strong>Application</strong> <strong>Server</strong> and the test environment. You will<br />
need to stop one server in order to run the other. To run both at the same time,<br />
you will need to alter the port numbers (for example, advance the number by<br />
1) for one of the servers. The port numbers are defined on the <strong>Server</strong><br />
Configuration Ports page.<br />
13.5.5 Running the application<br />
The last step in the process is to test the application.<br />
1. Find the Web module or individual Web resource you want to run in the<br />
Navigator view, right-click, and select Run on <strong>Server</strong>.<br />
If you haven’t set a server preference, you will be asked to select a server. If<br />
so, select the server you just created and continue.<br />
2. The application will open in a Web browser. You can exercise the application<br />
code from there.<br />
3. Now access the application from an external Web browser using the URL<br />
http://:7080//.<br />
Note: The context root is defined when you create the Web project (see<br />
Figure 4-4 on page 68). To see the context root, open the EAR deployment<br />
descriptor to the Module page and select the module.<br />
13.6 Working with server configurations<br />
In some cases, applications published to a server will run with no further<br />
intervention. However, there are usually things the server will have to be aware of<br />
that are not handled during the creation of the server and server configuration.<br />
For instance, if you are accessing a database then you will need a JDBC driver,<br />
and if the connection is a data source connection then you will need a data<br />
source definition. If you are connecting to a database using a driver manager<br />
definition, make sure the path to the driver class is included in the server class<br />
path.<br />
Chapter 13. Deploying applications 483
The server configuration can be opened with an editor, just like any other file.<br />
Just find the server in the <strong>Server</strong>s or <strong>Server</strong> Configuration view and double-click<br />
it to open.<br />
Note: You will notice as you go through the server configuration options, many<br />
of the pages will give you the choice of entering information at the cell, server,<br />
or node level. For <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express, this does not<br />
mean much since it is a single cell/node/server environment. Just follow the<br />
lead of the examples. It is best to be consistent. If you define things at the<br />
node level, then try to define everything at the node level.<br />
Figure 13-22 Working with a server configuration<br />
484 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: <strong>Server</strong> configuration settings are stored in XML files on the server.<br />
Settings are stored in a location that reflects the level of setting (node, cell, or<br />
server). Settings at multiple levels are merged. If the same setting is specified<br />
at multiple levels, the lowest (most specific) level takes precedence.<br />
► <strong>Server</strong>: App<strong>Server</strong>\config\cells\DefaultNode\nodes\<br />
DefaultNode\servers\server1<br />
► Node:App<strong>Server</strong>\config\cells\DefaultNode\nodes\<br />
DefaultNode<br />
► Cell: App<strong>Server</strong>\config\cells\DefaultNode<br />
The following settings for the server can be configured:<br />
► <strong>Server</strong>: These are the settings you enter when you create the server and<br />
server configuration. The most common change you might make here would<br />
be to change the FTP configuration associated with the server.<br />
► Configuration: The configuration settings include the server configuration<br />
name, whether to enable the universal test client (for testing Web services),<br />
and classloader behavior.<br />
► Environment: When you create an application, any classes required by the<br />
application must be accessible at runtime. These class files are usually<br />
packaged as JAR files and stored in the WEB-INF/classes directory. On this<br />
page, you can add entries to the global system class path and to the<br />
<strong>WebSphere</strong> classloader path (ws.ext.dirs). Environment settings also allow<br />
you to enter JVM arguments and system properties.<br />
► Web: This option allows you to modify MIME mappings and session<br />
management options. With the session management options you can select<br />
to use cookies, URL rewriting, or both for session management. If both<br />
mechanisms are chosen, cookies will take precedence over URL rewriting.<br />
► Data source: Creating a data source configuration is covered in “Defining a<br />
data source connection to the server” on page 200. Adding a data source<br />
definition updates the server’s JNDI name space.<br />
► Ports: Several processes in the Express <strong>Application</strong> <strong>Server</strong> require TCP/IP<br />
ports. There are defaults for all of these but they can be changed if you have a<br />
conflict with another process.<br />
► Variables: Express <strong>Application</strong> <strong>Server</strong> can make use of variables to limit the<br />
amount of hardcoding required in the server configuration. A good example is<br />
the DB2_JDBC_DRIVER_PATH variable. When you define a JDBC driver, the<br />
default driver path uses this variable. This means that if you change the<br />
installation path for DB2, you do not have to redefine the JDBC drivers. You<br />
only need to change the variable.<br />
Chapter 13. Deploying applications 485
► Trace: Allows you to enable <strong>WebSphere</strong> tracing and to specify the output file.<br />
► Security: Contains security settings for <strong>WebSphere</strong> security. Security is<br />
covered in Chapter 16, “Security” on page 551.<br />
► <strong>Application</strong>s: Allows you to specify classloader mode and policy.<br />
13.6.1 Classloaders and file location<br />
At runtime the server will need to be able to load the classes and JAR files used<br />
by the application. Classloaders are part of the JVM code and are responsible for<br />
finding and loading these files.<br />
The key to success is to understand how files are loaded and where to locate<br />
them for proper loading. In order to understand this, we suggest that you read<br />
J2EE Class Loading Demystified at:<br />
http://www7b.boulder.ibm.com/wsdd/library/techarticles/0112_deboer/<br />
deboer.html<br />
Tip: If you are getting a ClassNotFoundException, it is time to read that article.<br />
For now, take the default classloader settings in the server configuration and use<br />
the following guidelines taken from this article:<br />
► If your JAR file is only used in a single Web application, always put the JAR<br />
file in the Web project's Web Content/WEB-INF/lib folder. JAR files in this<br />
folder are automatically added to the Java build path, and will not require any<br />
further setup when moving to a different server.<br />
► If the JAR file is used by multiple modules within the same application, put the<br />
JAR file in the enterprise application. You will need to use the Edit Module<br />
Dependencies feature to set up the manifest files and the Java build class<br />
paths.<br />
► You can also put the JAR on one of the global class paths (using the Paths<br />
servlet configuration page), but we don't recommend this. It complicates your<br />
deployment and leaves your application vulnerable to incompatibility problems<br />
if those JARs are later upgraded.<br />
► If you still want to put the JAR file on the global class path, you must decide<br />
whether it should go on the class path or ws.ext.dirs. If the JAR file needs to<br />
access any J2EE or <strong>WebSphere</strong> classes, or any other JARs that have been<br />
added to ws.ext.dirs, it must also be placed on the ws.ext.dirs property.<br />
Otherwise, you are free to use either property.<br />
► If you have dependencies on the JAR file, update the Java build path of each<br />
project that uses the JAR file. Adding it to the global class path or ws.ext.dirs<br />
486 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
properties also means that you will have to publish the JAR file separately<br />
from your application, and you will have to set up the server class path again<br />
when you move to a different server.<br />
13.7 <strong>Server</strong> operations<br />
<strong>Server</strong>s can be started, stopped, published to, or restarted using the <strong>Server</strong><br />
perspective. The <strong>Server</strong>s view shows the status of each server and allows you to<br />
control it.<br />
13.7.1 Starting the server<br />
You can start a server from the <strong>Server</strong>s view by right-clicking the server project<br />
and selecting Start.<br />
When starting the server:<br />
► If the Automatically publish before starting servers check box in the server<br />
preferences (Window -> Preferences) is selected, the <strong>Server</strong> tools feature<br />
checks to see if your project and files on the remote server are synchronized<br />
prior to starting the server. If they are not, the project and the files are<br />
automatically updated on the remote when the server is started.<br />
► The Console view opens automatically and displays the messages as they<br />
occur. It will take a minute to start the server.<br />
► A successful start is indicated by the <strong>Server</strong> server1 open for e-business<br />
message. In the Status column of the <strong>Server</strong>s view, the status of the server<br />
changes to Started. If the server fails to start, check the console for an<br />
indication of what might be wrong.<br />
Chapter 13. Deploying applications 487
Note: You can also start the server by clicking the “start the server” icon ( )<br />
on the toolbar above the <strong>Server</strong>s view.<br />
If a server is set as the preferred server for a Web project, it will be<br />
automatically started when you select Run on <strong>Server</strong> for the Web module.<br />
Figure 13-23 <strong>Server</strong> console view<br />
Example 13-1 <strong>Server</strong> successfully started<br />
[8/5/02 18:47:45:047 EDT] 50453444 Ws<strong>Server</strong> A WSVR0001I: <strong>Server</strong> server1 open<br />
for e-business<br />
13.7.2 Stopping the server<br />
If you want to stop the server, select the server in the <strong>Server</strong>s view, and then<br />
select Stop from the context menu, or use the “stop the server” icon ( ).<br />
13.7.3 Restarting the server<br />
You need to restart the server when the server is started and one of the following<br />
situation occurs:<br />
► Changes are made to a file. However, if the file is a JSP file, an HTML file, a<br />
JPEG file, or a GIF file, you do not need to restart the server.<br />
► Changes are made to the server configuration, such as the port number.<br />
► Changes are made to the Web module, such as adding a JAR file.<br />
488 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
You may either restart the server automatically or manually. If you have selected<br />
the Automatically restart servers when necessary check box under the server<br />
preferences, the server will automatically start when one of the above-mentioned<br />
situations occurs.<br />
To restart a server manually:<br />
1. In the <strong>Server</strong>s view, select the server you want to restart.<br />
2. Click the ‘restart the server” icon ( ) on the toolbar. In the Status column of<br />
the <strong>Server</strong>s view, the status of the server changes to Stopped and then to<br />
Started if the server was previously started. If the server was previously<br />
started in debug mode, the status changes to Started in debug mode. If the<br />
server was previously started in profiling mode, the status changes to Started<br />
in profiling mode.<br />
13.8 Deploying applications for production<br />
<strong>Application</strong>s are deployed to the Express <strong>Application</strong> <strong>Server</strong> as enterprise<br />
applications. When you are testing, this is done for you by the <strong>Server</strong> tools when<br />
you publish the application to the server.<br />
In a production environment, it is likely that the Express <strong>Application</strong> <strong>Server</strong> is<br />
being managed from the administrative console and not from Studio Site<br />
Developer. In this case, you will need to export the application and place it on the<br />
application server for deployment.<br />
The steps involved in deploying an application are as follows.<br />
1. Ensure there are no errors in the application.<br />
2. Export the application to the server, either to a file or using FTP.<br />
3. Using the administrative console for the server, add any required resources<br />
such as data source definitions, install the application and start it. Using the<br />
administrative console to deploy an application is covered in <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express V5.0.1 Administrator Handbook, SG24-6976.<br />
13.8.1 Exporting an enterprise application to a file location<br />
To export the enterprise application to an EAR file for deployment:<br />
1. Find the enterprise application project in the Navigator view, right-click, and<br />
select Export.<br />
2. Select the EAR file and click Next.<br />
Chapter 13. Deploying applications 489
3. Enter the EAR file name to export the resources to. A possible location is the<br />
/installableApps directory of the Express <strong>Application</strong> <strong>Server</strong>,<br />
but you can export to anywhere in the file system.<br />
Figure 13-24 Exporting and enterprise application<br />
4. Make sure that the three options are deselected. Because the EAR file will be<br />
used in a production system, we do not want to include the source files or the<br />
meta-data.<br />
5. Click Finish to export the EAR file. The EAR file will be copied to the new<br />
directory. Notify the administrator of the application’s location and provide any<br />
information needed to install, for example, the name and location of<br />
databases used.<br />
13.8.2 Exporting an enterprise application using FTP<br />
To export project resources to an FTP server, do the following:<br />
1. Select File -> Export.<br />
2. In the Export dialog, either double-click FTP or select FTP and click Next.<br />
490 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3. In the Export resources to an FTP <strong>Server</strong> wizard page, specify the FTP host<br />
information. Also verify that the Folder field contains the correct path to the<br />
folder that you want exported. In the FTP folder field, enter a name of the<br />
folder that you want to export the files to.<br />
4. In the FTP Options area:<br />
– PASV, or Passive mode, allows a client rather than the FTP server to<br />
initiate the transfer operation, which enables transfers through firewalls<br />
that allow outgoing network connections only. If you select the Use<br />
Firewall option and select Settings, you will be prompted to define setting<br />
for a socks server or an FTP proxy server. If you select the FTP Proxy<br />
radio button, you must choose one of the available firewall types.<br />
5. Optionally, supply an FTP Connection Timeout value, in milliseconds.<br />
6. Click Next to supply FTP server login information.<br />
7. Click Finish to export the Web site.<br />
8. When the export is complete, verify the resulting directory structure and file<br />
data integrity.<br />
13.9 <strong>IBM</strong> Agent Controller settings and status<br />
The <strong>IBM</strong> Agent Controller must be installed and running on the server system<br />
before you can use a server with the <strong>Server</strong> tools, even if the server is local to the<br />
Studio Site Developer machine. This should be done automatically when you<br />
install Express <strong>Application</strong> <strong>Server</strong>, but check to make sure everything is working.<br />
1. Verify that the <strong>IBM</strong> Agent Controller has started.<br />
– Windows: Use the Windows services panel (Start -> Programs -><br />
Administrative tools -> Services) and make sure the <strong>IBM</strong> Agent<br />
Controller service has started. If not, start the service. By default the<br />
service will start when you complete the install and will be set to start<br />
automatically.<br />
– Linux: Execute RAStart.sh in the /bin directory.<br />
2. Check the <strong>IBM</strong> Agent Controller configuration settings to make sure that the<br />
WAS_HOME_V5 setting is correct.<br />
Chapter 13. Deploying applications 491
Example 13-2 <strong>IBM</strong> Agent settings<br />
<br />
<br />
<br />
<br />
<br />
The configuration settings are in the<br />
/RAC/config/serviceconfig.xml directory.<br />
Messages relating to the remote server operations can be seen in the <strong>IBM</strong> Agent<br />
Controller log. The log is located on the server machine at<br />
/RAC/config/servicelog.log.<br />
13.10 For more information<br />
► For information on using the administrative console to manage an Express<br />
<strong>Application</strong> <strong>Server</strong>, see <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.1<br />
Administrator Handbook, SG24-6976.<br />
► For information on the Express <strong>Application</strong> <strong>Server</strong> runtime architecture, see<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> Architecture, REDP3721.<br />
492 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 14. Testing and debugging<br />
This chapter provides information on the process of testing and debugging Web<br />
applications using Studio Site Developer.<br />
This chapter describes the following topics:<br />
► Debugging using the Web perspective<br />
► Debugging using the Debug perspective<br />
► Stepping through code using the Online Catalog sample<br />
14<br />
When developing an application, you will constantly be addressing any warnings<br />
and errors as indicated by the Tasks and Project navigator views within Studio<br />
Site Developer. After development, you will begin your testing procedure where<br />
you will verify the appearance and function of each resource. During this testing,<br />
you make come across resource errors that are not indicated in the Tasks or<br />
Project navigator views. Error determination may be possible using the Console<br />
view or the Debug perspective. For more information about each of these tools,<br />
please read the following sections.<br />
© Copyright <strong>IBM</strong> Corp. 2003 493
14.1 Debugging in the Web perspective<br />
14.1.1 Page errors<br />
The Web perspective provides several tools to aid you in debugging your Web<br />
applications. Tools include:<br />
► Project navigator view<br />
► Tasks view<br />
► Console view<br />
► Editor marker bars<br />
► Quick Fix tool<br />
Web servers generate error messages when they encounter unexpected<br />
conditions. If <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express encounters an error in<br />
your application at runtime, it will display the appropriate error page in the Web<br />
browser. Two of the most common errors that you may encounter during your<br />
development are the 404 and 500 errors.<br />
404 error<br />
The 404 error page is displayed when a page being requested is non-existent.<br />
This error could be the result of several problems:<br />
► The requested page has been moved or is named incorrectly.<br />
► The requesting page may be pointing to the incorrect URL for the requested<br />
page.<br />
494 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 14-1 404 error page<br />
Error message<br />
To address the error, verify first that the page being requested is in the correct<br />
location and is named correctly and then verify that the link that is requesting the<br />
page is correct. For a 404 error, your best bet is to look at the Project navigator<br />
and Tasks views for answers. For more information about these views, see<br />
14.1.3, “Tasks view” on page 497 and 14.1.2, “Project navigator view” on<br />
page 496.<br />
500 error<br />
The 500 error page is displayed when an internal server error has occurred.<br />
With Java development, this is most likely the result of an error occurring when a<br />
class or JSP was compiled.<br />
Chapter 14. Testing and debugging 495
Figure 14-2 500 page error<br />
These error pages do not really provide you with any significant information, but<br />
they do point you in the correct direction. 500 errors can also be located using<br />
the Project navigator or Tasks views, but the Console view may be of more help.<br />
For more information about the Console view, see 14.1.5, “Console view” on<br />
page 499.<br />
14.1.2 Project navigator view<br />
Errors and warnings on resources (including Java, HTML/JSP, and Links Builder<br />
errors and warnings) are indicated with a red error or yellow warning<br />
next to the resource with the error, as well as the parent folders all the way up to<br />
the project folder.<br />
For example, in Figure 14-3 on page 497, there is an error in<br />
FeaturedItemXMLServlet.java. This is indicated with an error icon for that file and<br />
the files above it in the hierarchy.<br />
496 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Error message
14.1.3 Tasks view<br />
Figure 14-3 Project navigator view<br />
You can navigate to the resource using the Project navigator view and then<br />
double-click it to open it in its default editor. The editor can then be used to<br />
correct the warning or error.<br />
Each warning or error will have an entry in the Tasks view providing you with<br />
information about the problem, including the description, resource, resource<br />
folder, and line location. Double-clicking an item from the Tasks view opens the<br />
corresponding resource in its default editor at the line of code causing the<br />
problem. For additional information about the Tasks view, please refer to “Tasks<br />
view” on page 84.<br />
Chapter 14. Testing and debugging 497
14.1.4 Editors<br />
Note: The Tasks view can be opened in the Web perspective by selecting<br />
Window -> Show View -> Tasks from the main menu of the workbench.<br />
Figure 14-4 Tasks view<br />
The Page Designer and Java editors are used to correct the conditions that<br />
caused the warnings or errors. Two common ways of opening the offending file<br />
and finding the errors are:<br />
► Double-click an entry in the Tasks view. The file with the error will be opened<br />
using its default editor and the current line will be the line where the warning<br />
or error exists.<br />
► Double-click a file with an error or warning icon in the Project Navigator view.<br />
The file will be opened using its default editor, however the current line will not<br />
be set to the line with the error (there may be more than one). You will need to<br />
scan down the editor marker bar for the error or warning icons.<br />
Editor marker bars<br />
If a resource is opened and the warning or error is not displayed, you can use<br />
either the left or right marker bars in the editor to locate it. The right marker bar<br />
will display all the warnings and errors contained in the resource using either a<br />
yellow (warning) or red (error) bar. Double-clicking the bar will take you to the line<br />
498 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
14.1.5 Console view<br />
containing the warning or error. The left marker bar can be used in the same way<br />
as the right marker bar, but you must scroll down to locate the warning or<br />
error icons. In either case, moving the cursor over either the icons or bars<br />
will display the warning or error message.<br />
Figure 14-5 Editor marker bars<br />
If an error is indicated with then the Quick Fix feature may be used to assist<br />
in fixing it. This is only available in the Java editor. For more information on using<br />
Quick Fix, please see “Quick Fix” on page 227.<br />
The previous views discussed are used while you are editing an application. The<br />
errors and warnings are a result of the automatic verification processes that take<br />
place as you are developing.<br />
The Console view shows errors that happen at runtime. When you test an<br />
application by running it on a server controlled through Studio Site Developer,<br />
this view will display server console messages.<br />
The console shows three different kinds of text, each in a different color. You can<br />
choose the different colors for these kinds of text on the preferences pages<br />
(Window -> Preferences -> Debug -> Console).<br />
Chapter 14. Testing and debugging 499
► Standard output: Default color blue<br />
► Standard error: Default color red<br />
► Standard input: Default color green<br />
When an error has occurred in a process, the Console view will display a<br />
message similar to the figure below. The Console view is a good starting point<br />
when a 500 error is received. The console messages may not give you the exact<br />
location of the error, but they will give you the resource name where the error<br />
occurred. This will allow you to debug the resource and locate the error.<br />
Figure 14-6 Console view<br />
14.2 Debugging using the Debug perspective<br />
Studio Site Developer includes an integrated debugger that makes it easy to<br />
trace the execution of code and to quickly find and fix problems. You can debug<br />
standalone Java code, servlets, JSPs, JavaScript, etc. Debugging can be done<br />
locally or remotely.<br />
500 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The debugger allows you to control the execution of your program by setting<br />
breakpoints, suspending launches, stepping through your code, and examining<br />
the contents of variables.<br />
14.2.1 Debug perspective<br />
The Debug perspective has many views designed to assist you with problem<br />
diagnosis. Among them are:<br />
► Debug view with running processes<br />
► <strong>Server</strong>s view for monitoring and controlling servers<br />
► Source view, showing the source of the Java program with the current line<br />
highlighted<br />
► Outline view, showing the outline of the source code<br />
► Console view, showing the server output<br />
► Breakpoint view, showing all defined breakpoints<br />
► Variables view, showing variables and their values at each step<br />
You can open the Debug perspective by selecting Window -> Open Perspective<br />
-> Debug from the main menu of the workbench.<br />
Chapter 14. Testing and debugging 501
Figure 14-7 Debug perspective<br />
Breakpoint view<br />
The Breakpoints view lists all the breakpoints you have set in the workbench<br />
projects. You can double-click a breakpoint to display its location in the editor. In<br />
this view, you can also enable or disable breakpoints, delete them, or add new<br />
ones.<br />
502 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 14-8 Breakpoint view<br />
Debug view<br />
This view allows you to manage the debugging or running of a program in the<br />
workbench. It displays the stack frame (it holds the return address, local<br />
variables used, and procedure parameters within a thread) for the suspended<br />
threads for each target you are debugging. Each thread (a single sequential flow<br />
of control within a program) in your program appears as a node in the tree. It<br />
displays the process for each target you are running. If the thread is suspended,<br />
the stack frames are shown as child elements.<br />
Figure 14-9 Debug view<br />
Threads<br />
Stack frame<br />
Chapter 14. Testing and debugging 503
Note: For additional information on the Debug view, please see the product<br />
help documentation.<br />
Variables view<br />
This view displays information about the variables in the currently-selected stack<br />
frame. If you look at Figure 14-10, you will notice that the view has been divided<br />
into two areas. The upper area is a list of all the variables that have been used in<br />
the corresponding file. Selecting a variable displays the variable value in the<br />
lower area of the view.<br />
Figure 14-10 Variables view<br />
Setting breakpoints<br />
Breakpoints are indicators to the debugger that it should stop execution at<br />
specific places in the code, and let you step through it. Breakpoints can be set to<br />
trigger always or when a certain condition has been met.<br />
504 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Tip: Breakpoints can be set in Java and JSP resources on an executable line<br />
of a program. However, within JSPs you can only set breakpoints in Java code<br />
and tags.<br />
In the editor area, open the file where you want to add the breakpoint. Directly to<br />
the left of the line where you want to add the breakpoint, open the marker bar<br />
(vertical ruler) pop-up menu and select Add Breakpoint. You can also<br />
double-click the editor marker bar next to the source code line. A new breakpoint<br />
marker appears on the marker bar, directly to the left of the line where you added<br />
the breakpoint. Also, the new breakpoint appears in the Breakpoints view list.<br />
Note: Enabled breakpoints are indicated with a blue circle. If the enabled<br />
breakpoint is successfully installed in a class in the JVM at runtime, it is<br />
indicated with a check mark overlay.<br />
Figure 14-11 Setting a breakpoint<br />
Breakpoint properties<br />
Right-click the breakpoint in the breakpoint view, and select Breakpoint<br />
Properties from the context menu. A window opens where more detailed options<br />
about the breakpoint are displayed (Figure 14-12 on page 506).<br />
Chapter 14. Testing and debugging 505
Figure 14-12 Breakpoint properties<br />
The Enable Hit Count property, when set, causes the breakpoint to be triggered<br />
only when the lines has been executed as many times as the hit count specified.<br />
Once triggered, the breakpoint is disabled.<br />
The other property of interest here is Enable Condition. If set, then the<br />
breakpoint is reached only when the condition specified in the entry field<br />
evaluates to true. This condition is a Java expression.<br />
The Restrict to Selected Thread(s) list is only filled if a server is running in debug<br />
mode already; otherwise the list in empty.<br />
Click OK to close the breakpoint properties. In the Breakpoints view, the<br />
breakpoint is now marked with a question mark , which indicates that it is a<br />
conditional breakpoint.<br />
506 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
14.3 Stepping through code using the Online Catalog<br />
sample<br />
When stepping through code using the debugger, the application will stop when<br />
each Web object is loaded by the server; this is also referred to as the<br />
step-by-step mode. At this point, you can step into or over each statement in the<br />
code, inspecting variables and using other debugging features.<br />
Studio Site Developer has extensive help information on this topic, including<br />
debugging Java, JavaScript, stored procedures, and compiled language<br />
applications. This section will take you through a common debug scenario and<br />
point out the highlights of the debugger.<br />
Let’s assume for this sample that we want to verify that the xslFile variable of the<br />
FeaturedItemXMLServlet servlet is being set to the correct value. To do this, we<br />
are going to set a breakpoint in the servlet, run the application in debug mode,<br />
and then check the variable value using the Variables view.<br />
14.3.1 Setting breakpoints<br />
1. Open the Web perspective.<br />
1. Navigate to the featured_item package in the JavaSource folder and expand<br />
it.<br />
2. Open the FeaturedItemXMLServlet.java in the Java editor by double-clicking<br />
it.<br />
3. Place your cursor in the left editor marker bar on the line String html =<br />
genHTML(baosXML.toString(),xslContent);. Use the Edit -><br />
Find/Replace option to find the string if you don’t see it right away.<br />
4. Double-click to set a breakpoint. A marker will be shown at the line.<br />
Chapter 14. Testing and debugging 507
Figure 14-13 Setting a breakpoint in FeaturedItemXMLServlet.java<br />
14.3.2 Running the application in debug mode<br />
Once you have set the breakpoint, the Web application can be started for<br />
debugging.<br />
1. From the Web perspective, right-click the OnlineCatalog project and select<br />
Debug on <strong>Server</strong>... from the context menu. The <strong>Server</strong> Selection dialog<br />
opens.<br />
Important: The server used for testing must be either stopped or already<br />
started in debug mode. Otherwise, an error message will be displayed.<br />
2. Select an existing server or create a new one and click Finish.<br />
3. Studio Site Developer switches to the Debug perspective automatically.<br />
4. You should now see index.html displayed in the Web browser view. This might<br />
take a minute or so if the server is new. Click the Featured Item link from the<br />
navigation menu.<br />
508 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 14-14 OnlineCatalog running in debug mode<br />
5. You are prompted to step into the<br />
featureditem.FeaturedItemXMLServlet.doGet method. This is a feature,<br />
step-by-step mode, in the debugger to allow you to debug code without<br />
setting breakpoints. Select the Skip radio button and click OK. The servlet is<br />
executed.<br />
Chapter 14. Testing and debugging 509
Note: For additional information about the Debug perspective, refer to the<br />
product help documentation.<br />
Figure 14-15 Skip method<br />
6. As soon as the breakpoint in FeaturedItemXMLServlet.java is reached,<br />
execution stops and the FeaturedItemXMLServlet.java source file is displayed<br />
with the line containing the breakpoint highlighted. The thread is suspended<br />
in debug, but other threads might still be running.<br />
510 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Breakpoint<br />
Figure 14-16 Debug perspective when stopped at breakpoint<br />
Suspended thread<br />
Breakpoints view<br />
Click the Breakpoints tab in the upper right window of the perspective to see the<br />
Breakpoints view. Notice that the breakpoint that we set earlier is listed. If we had<br />
additional breakpoints set in the current servlet or in other resources within the<br />
OnlineCatalog project, they would be listed here as well. Double-clicking the<br />
breakpoint will open the associated resource in its default editor and highlight the<br />
breakpoint line in the source code.<br />
Chapter 14. Testing and debugging 511
Figure 14-17 Breakpoint view<br />
14.3.3 Verifying the variable<br />
The purpose of this example was to illustrate how the debugging features can be<br />
used to verify the value of a variable. Click the Variables tab in the upper right<br />
window to display the Variables view. Scroll down until you locate the variable<br />
xstFile.<br />
Figure 14-18 Variables view<br />
Click xstFile and notice the value beside it and in the lower view area. The value<br />
displayed is /Documents and Settings/bogers/My<br />
Documents/<strong>IBM</strong>/wasexpress51/workspace/OnlineCatalog/WebContent/featured_<br />
item/FeaturedItem.xst, which is what we are required to have for the<br />
application. Had this been the incorrect value, we could have right-clicked xstFile<br />
and selected Change Variable Value from the context menu to open the Set<br />
Variable Value dialog and entered a different value with which to test.<br />
512 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 14-19 Set variable value dialog<br />
You can continue to step through the application by clicking Resume in the<br />
Debug view. You will again be prompted to skip or step into the next method. If<br />
you wish to end the debug session, stop the application server from the <strong>Server</strong>s<br />
view.<br />
Chapter 14. Testing and debugging 513
514 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 15. Development in a team<br />
environment<br />
15<br />
In most cases a developer does not work alone but as a part of a team, making<br />
the use of a version control system important. Version control systems provide<br />
two important features required for working in a team environment:<br />
► A history of the work performed by the team members<br />
► A way to coordinate and integrate this work<br />
Studio Site Developer delivers an adapter for a Concurrent Versions System<br />
(CVS) to provide team development management. This chapter provides<br />
information on team development using CVS, including the following:<br />
► Team development and CVS overview<br />
► Sharing an application for the first time<br />
► Using CVS in a team development environment<br />
► Tracking the history of changes and reverting back to previous versions<br />
© Copyright <strong>IBM</strong> Corp. 2003 515
15.1 Team development with CVS<br />
CVS provides a client/server environment for team development. Studio Site<br />
Developer provides the client component. To complete the team development<br />
environment, you will need to download and install a CVS server (see<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.1 Administrator Handbook,<br />
SG24-6976 for more information). Some of the highlights of CVS are discussed<br />
in the following sections.<br />
15.1.1 Non-exclusive checkout<br />
CVS operates on the principle that the development team is unlikely to produce<br />
many real conflicts, meaning that the developers have a logical separation of<br />
tasks and are most likely working on separate files within the project. Files that<br />
are checked out are not locked, meaning resources can be checked out by<br />
multiple developers at the same time. It is up to the developers to resolve true<br />
conflicts correctly.<br />
15.1.2 Access to resources<br />
Typically each user will have an account on the server so that actions can be<br />
logged to a particular user. The creation of users and groups is done by the<br />
server administrator.<br />
Unlike some other repositories, the Studio Site Developer does not have any<br />
notion of object ownership. Write access is controlled only by the write<br />
permission to the directory that holds the resource. Anyone who is authorized to<br />
access the resource can create, edit, or delete it.<br />
15.1.3 Working with resources<br />
Projects are stored in a repository for access by users. Project versions are<br />
unmodifiable copies of the project. Projects stored in a branch are modifiable.<br />
A branch is a shared workspace on a team server where project data is stored.<br />
Teams share and integrate their ongoing work in branchs. Resources can be<br />
changed in the team members’ individual workspaces without affecting the<br />
branch. Each developer must explicitly commit changed resources to the branch.<br />
Every repository has at least one branch. Under certain conditions, more than<br />
one branch can exist in a repository.<br />
516 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
15.1.4 Change history<br />
CVS maintains a history of source code in a tree structure that shows all<br />
changes. Each change is stamped with the time it was made and the user name<br />
of the person who made it. As a rule, developers will also provide a description of<br />
the change. Given that information, CVS can help developers find answers to<br />
questions such as:<br />
► Who made the change?<br />
► When was it made?<br />
► Why was it made?<br />
► What other changes were made at the same time?<br />
CVS records all changes to a given project in a directory tree called a repository.<br />
CVS does not work with ordinary directory trees; you need to work within a<br />
directory that CVS created for you. Just as you check out a book from a library<br />
before taking it home to read it, you use the cvs checkout command to get a<br />
directory tree from CVS before working on it.<br />
15.1.5 Making changes available to the team<br />
While you are working on the project on your workstation, all changes are local.<br />
For others to access a resource you have changed you have to commit it to the<br />
branch. At the same time, others may have committed changes to the branch. To<br />
bring your local and repository systems up-to-date you need to synchronize your<br />
local workspace with the repository. Two distinct process are involved in<br />
synchronizing resources: Update and commit.<br />
Conflicts arise when you have modified a resource for which a more recent<br />
version is available in the branch. In this situation, you can do one of three things:<br />
Update the resource from the branch, commit your version of the resource to the<br />
branch, or merge your work and the branch resource.<br />
15.1.6 Conflict resolution<br />
What happens if more then one developer has changed the same file or the<br />
same line? Whose changes should prevail? It is generally impossible to answer<br />
this question automatically and CVS does not make any attempts to resolve such<br />
a conflict. It simply recognizes that a conflict exists. Studio Site Developer<br />
provides the tools to make conflict resolution easy.<br />
It is important to realize what CVS does and does not consider a conflict. CVS's<br />
understanding of conflicts is strictly textual and it does not understand the<br />
semantics of your program. From its perspective your source code is simply a<br />
tree of text files.<br />
Chapter 15. Development in a team environment 517
15.2 Team environment using Studio Site Developer<br />
Developers using Studio Site Developer can:<br />
► Check out resources.<br />
► Modify the resources.<br />
► Resolve conflicts with code changes made by other developers.<br />
► Check the new code back into the server.<br />
► Create versions of a project.<br />
The Studio Site Developer team environment works under the assumption that<br />
the division of labor among the developers reduces the likelihood of true conflicts<br />
(two developers altering the same resource).<br />
15.2.1 Typical flow for team development<br />
There are some important but subtle issues related to working with a repository:<br />
► Each project is associated with a specific branch in a specific repository.<br />
Different projects can be associated with different repositories, which may in<br />
fact be on completely different servers.<br />
► The branch contains all projects in the repository. Individual users can pick<br />
which projects they are interested in and add them to their workspaces. From<br />
that point on they are synchronizing those projects only with respect to the<br />
branch.<br />
► The branch represents a large in-progress collection of all known projects.<br />
From the branch's perspective everything is always open for change. The<br />
default branch that most users work with is known as the HEAD branch. Other<br />
branches are sometimes created to split the development effort, but at some<br />
point will need to be merged back into the HEAD branch.<br />
► The act of versioning a project effectively snapshots it and places it into the<br />
Project Versions section of the repository; however, the “branch copy” of it is<br />
still open for changes.<br />
► When you version the project you should do so by versioning the project as it<br />
appears in your workbench. This is where you can easily control what it looks<br />
like and test it to ensure that there are no errors.<br />
The following is a typical team environment scenario. The steps are:<br />
1. Create and share an application by versioning it to the repository.<br />
a. Create the Web project.<br />
b. Connect to the CVS repository.<br />
c. Share the application by committing (copying) it to the repository.<br />
518 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
d. Create a version of the application to act as a stable copy that developers<br />
can use as a starting point.<br />
2. The team members connect to the repository and add the version to their<br />
workspaces.<br />
3. As resources are created and modified, the team members synchronize with<br />
the repository. Synchronization steps are:<br />
a. Update from the repository to accept incoming changes from other<br />
developers.<br />
b. Resolve conflicts when the work of two developers hits the same resource.<br />
c. Commit the new resolved code to the repository.<br />
4. When the application reaches a stable level or one that you want to preserve,<br />
version the project.<br />
15.3 Connecting to a repository<br />
To begin working in a team environment you need to connect to the repository<br />
the team will be using. The primary interface for the team environment is from the<br />
CVS Repository Exploring perspective.<br />
1. Open the perspective by selecting Window -> Open Perspective -> CVS<br />
Repository Exploring.<br />
2. With the cursor in the Repositories view, right-click and select New -><br />
Repository Location from the context menu.<br />
3. Enter the information needed to connect to the repository.<br />
a. In the Host Name field, type the host address of the CVS server machine.<br />
If the CVS server is on the same machine, use localhost.<br />
b. In the Repository Path field, type the path to the repository on the host.<br />
c. In the Authentication section enter the user ID and password to use to<br />
connect to the repository. This user must have access to files in the<br />
repository directory.<br />
Note: Until we added this user ID to the Administrators group on the<br />
CVS server we had problems using CVS. It was not enough to give the<br />
CVS user access to the repository.<br />
Chapter 15. Development in a team environment 519
d. Select the connection type (authentication protocol) of the CVS server<br />
from the connection type drop-down menu (for example, pserver).<br />
pserver: The authentication will be performed by the CVS password<br />
server on the CVS server machine. The password server defaults to<br />
port 2401, though this could be changed. In this case, you would need<br />
to know the server port and enter it in the Use Port field.<br />
ext: Use an external connection program.<br />
extssh: Use an external secure shell (ssh) connection.<br />
In our example we have installed the CVS server on a Windows 2000<br />
server and are using the CVS authentication so we select pserver. We<br />
have set up the CVS server to use the local operating system security so<br />
the user name and password entered here must be valid on that system.<br />
e. Select Validate connection on finish to test the connection to the server.<br />
Deselect this option if you want to authenticate later.<br />
Figure 15-1 CVS Repository Location wizard<br />
4. Click Finish.<br />
The repository will be added to the CVS Repositories view and, assuming the<br />
connection information is correct, you can browse the repository contents.<br />
520 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 15-2 CVS Repository perspective<br />
Important: As you work with the CVS repository, keep in mind that the files<br />
you are seeing are outside of Studio Site Developer. When updates are made<br />
to the repository, whether you make them or someone else does, you may<br />
need to use the refresh button ( ) to see the updates.<br />
15.4 Adding a new application to the repository<br />
Assume that you have created a Web project and now you want to put it in the<br />
repository to share with the team. The basic steps to do this are:<br />
1. Select the project and “share” it with the team.<br />
2. Commit the project to the repository.<br />
3. Create an initial version of the project.<br />
15.4.1 Sharing the project<br />
In this section we discuss sharing the project.<br />
Chapter 15. Development in a team environment 521
Note: When you share a project you designate a repository to hold the project.<br />
Sharing a project does not automatically copy the resources to the repository<br />
but simply sets up the definitions needed in your workspace and in the CVS<br />
server to hold the project in the repository.<br />
The first time you want to share a project by putting it in the team repository, do<br />
the following:<br />
1. From the Project Navigator view in the Web perspective (or any Navigator<br />
view) select the Web project, right-click, and select Team -> Share Project<br />
from the context menu.<br />
2. The Share Project wizard will open and you will have a chance to choose an<br />
existing repository location or to add a new one.<br />
Figure 15-3 Share Project wizard screen 1<br />
3. The next screen gives you a chance to specify a different module name. The<br />
default is to use the project name as the module name. Click Next.<br />
4. The final screen is informational so click Finish.<br />
At this point three things have happened as a result of the wizard processing:<br />
► The information you have entered is stored as a Web project property. A new<br />
folder called CVS and two new files under it called Root and Repository are<br />
created in the workspace under the Web project folder to hold this<br />
522 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
information. As you continue working with the project, CVS folders are<br />
created under each project folder to hold information relevant to team<br />
processing. You will never access these directly so they are not visible from<br />
the Studio Site Developer navigators. We only mention them here so you will<br />
get a feel for the processing that is taking place.<br />
Note: When you disconnect a project from the repository you have the<br />
option to delete these files. If you keep them, the next time you share the<br />
project it will use these files for the connection. If you are changing<br />
repositories, you should delete them when you disconnect.<br />
► A folder is created on the CVS server in the repository. The folder is empty<br />
since nothing has been committed to it yet.<br />
► The Synchronize window opens in the workbench to show you the<br />
discrepancies between the project in your workspace and the project in the<br />
repository. Since nothing has been put in the repository yet, you will see all<br />
the resources of the project listed in the Outgoing view. The resources will<br />
have a gray arrow with a + in them, indicating they are new changes to be<br />
sent to the repository.<br />
Figure 15-4 The Synchronize view<br />
Chapter 15. Development in a team environment 523
15.4.2 Copy (commit) the project to the repository<br />
So far you only have a place holder in the CVS repository for the project. Other<br />
users will be able to see the project in the repository but there are no resources<br />
in it. To make the resources available for sharing, you must commit the project,<br />
which will result in the resources being copied to the CVS repository. The<br />
resources will be placed in the HEAD branch only. No version is created.<br />
Note: Committing a project or a resource causes it to be copied from your<br />
workspace to the branch in the repository. A resource must be initially<br />
committed as a part of a project commit before it can be committed<br />
individually.<br />
Each time you commit a resource a new revision tag is associated with it.<br />
Note: When you initially commit a Web project, a revision tag is associated<br />
with each resource in the project because each resource is new to the<br />
repository. This initial revision tag is 1.1.<br />
Each time you commit a resource the revision tag is changed to the next level<br />
(1.2, 1.3, etc.). If you commit at the Web project level, only changed resources<br />
get a new revision tag, and that revision tag will be the next number in the<br />
sequence for that resource.<br />
In Figure 15-4 on page 523, you see the Synchronize view with the project<br />
showing in the Outgoing Mode view. To commit you do the following:<br />
1. Switch to the Outgoing Mode view in the Synchronize view, select the project<br />
at the top, right-click, and select Commit.<br />
Or select the project in the Project Navigator view, right-click the Web project,<br />
and select Team -> Commit.<br />
524 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
2. Enter a comment and click OK. If asked if you want to add the resources to<br />
version control, click Yes.<br />
The comment will be shown when you view the history of resources<br />
committed with this action. If, for example, you are committing a project, you<br />
might want to add a comment like Bug 0010 fixed in HTML files. If you are<br />
committing an individual HTML or JSP file, you might want to add a comment<br />
like Changed to use session attributes vs request parameters. The<br />
comment should give you an idea of what happened in the revision.<br />
If you are using the Synchronize view, you will notice that the entries in the<br />
Outgoing view will disappear since they are no longer conflicting with the<br />
repository.<br />
3. Close the Synchronize view and switch to the CVS Repository Exploring<br />
perspective to view the repository. You should now be able to see the Web<br />
project and its resources under the HEAD branch. You may need to use the<br />
refresh button ( ) to see the updates<br />
15.4.3 Creating a version<br />
Tip: If you are using the Team menu in the Project Navigator and you have<br />
added resources since a previous commit, you will have to take an<br />
additional step before you can commit: Select the new resource, right-click,<br />
and select Team -> Add to version control.<br />
You will know that you need to do this because the option to commit will be<br />
grayed out in the menu. In addition, a reminder is added to the Tasks view<br />
when you add a resource.<br />
It does not hurt to spot check the CVS repository to make sure you are<br />
copying all the resources you intend to. If they are missing from the<br />
repository, go back and add them to version control.<br />
The last step in sharing a project is to create a base version.<br />
Note: Versions are a snapshot of the state of a project at a given time. They<br />
are not modifiable but are used as a reference point when comparing code or<br />
as a starting point for development.<br />
Chapter 15. Development in a team environment 525
It makes sense to do this when you first share the project in order to give<br />
everyone a good comparison point. Future versions can be made whenever the<br />
code has reached a point that you would want to save. Adding the project to<br />
version control in the commit is not the same as creating a version. Versions can<br />
be made in either of the following ways:<br />
► From the branch in the CVS Repositories view. This creates a version from<br />
the repository branch copy of the project. Use this option if you want all<br />
committed changes from all developers of the project.<br />
► From the Team menu in the Project Navigator view. This creates a version<br />
from the project in your workspace. Only resources that you have committed<br />
will be included. If you have uncommitted resources you will be notified and<br />
given an option to continue without them. If you use this option you will not<br />
pick up any committed changes from other users. Versioning a project with<br />
uncommitted or outgoing changes is handy if you have to split the project at<br />
the point where you started making changes to the resources and commit the<br />
resources to another branch.<br />
Version from branch<br />
You can version from the branch in the CVS Repository Exploring perspective by<br />
selecting the project under the desired branch. When versioning from the branch<br />
you are versioning the latest resource versions that are in the branch at that<br />
moment in time.<br />
Note: You should not version your projects from the branch if you are not sure<br />
what is currently committed in the branch.<br />
In order to version a project it must be associated with a branch. If this is not the<br />
case, you must first associate it.<br />
To create a version from the branch:<br />
1. Open the CVS Repository Exploring perspective.<br />
2. Select the Web project in the CVS Repositories view under the branch (for<br />
example, HEAD), right-click, and select Tag as Version.<br />
3. Enter a comment and click OK.<br />
Version from workspace<br />
When versioning a project from the workspace, the base version of the resources<br />
in the workspace is captured as part of the project version. This is the preferred<br />
method of versioning a project because you know exactly which resource<br />
versions will be in the project version.<br />
526 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
This operation is allowed if you have outgoing changes or uncommitted changes.<br />
Uncommitted changes are simply ignored, and resources with outgoing changes<br />
can still have their base versions be part of the project version.<br />
To create a version from your workspace:<br />
1. Open the Web perspective.<br />
2. Add any new resources to version control by selecting the resource,<br />
right-clicking, and selecting Team -> Add to version control.<br />
3. Commit to the repository using Team -> Commit and enter a comment.<br />
Note: As you will see later, you should always synchronize with the<br />
repository before committing changes so that you do not overlay changes<br />
made by others. For simplicity we will assume you have done this.<br />
4. Select the Web project Project Navigator view, right-click, and select Team -><br />
Tag as Version.<br />
5. Enter a comment and click OK.<br />
Once again, the comment should be meaningful, for example, BaseVersion,<br />
Version1, etc. It will appear as a comment in the resource history in the Tag<br />
column and beside the version in the CVS Repositories view.<br />
A look at the new version in the CVS Repository Exploring perspective will show<br />
you the resources that make up the version and their revision tags. Figure 15-5<br />
on page 528 shows a version that has resources at two different revision levels.<br />
The index.jsp resource is at revision 1.3. The Master.css resource is at revision<br />
1.1.<br />
Chapter 15. Development in a team environment 527
Figure 15-5 Viewing the project version<br />
15.4.4 (Optional) changing the sharing information for a Web project<br />
The information you entered is treated as a Web project property and can be<br />
changed to a limited extent. To view this information select Properties from the<br />
Web project context page and then select the CVS option.<br />
To change the information click the Change Sharing button. You will be given a<br />
list of repository locations that you can switch to. The only change allowed is to<br />
another user ID on the same repository. In other words, the only repository<br />
locations you can switch to must have the same server and repository.<br />
If you want to send the project to a different repository you will need to<br />
disconnect the project (Team -> Disconnect) from the current repository. This<br />
does not affect the CVS server, but it erases the association between the project<br />
and that repository. Then you follow the steps for adding an application to a<br />
repository to put it on the other one.<br />
528 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 15-6 Web project CVS properties<br />
15.5 Adding an existing application to your workspace<br />
Now that a project has been added to the repository, other members of the<br />
development team can begin working on it. They will need to begin by creating a<br />
connection to the repository, as in 15.3, “Connecting to a repository” on<br />
page 519.<br />
Getting a copy of the current project is easy. The project should be available<br />
under the HEAD branch.<br />
1. Expand the HEAD branch in the CVS Repositories view and select the<br />
project.<br />
2. Right-click and select Check Out As Project from the context menu.<br />
The project will be copied into your local workspace and you can switch to the<br />
Web perspective to begin work.<br />
Chapter 15. Development in a team environment 529
15.6 Working with the team using the repository<br />
As the team members update and create resources they will need to synchronize<br />
with the branch periodically. This ensures they have the latest code from other<br />
developers and that conflicts are resolved early in the process. The primary<br />
steps are:<br />
1. Synchronize your workspace copy with the current branch.<br />
2. Resolve conflicts if necessary.<br />
3. Update from the repository (receive changes from the repository).<br />
4. Commit your changes to the repository.<br />
15.6.1 Synchronizing with the repository<br />
The synchronization process will compare the resources in your workspace with<br />
those in the branch and report the differences.<br />
Note: The local history of a resource will be reset every time you synchronize<br />
with the branch.<br />
To synchronize:<br />
1. Select the project that you want to synchronize with the branch from the<br />
Project Navigator view.<br />
2. From the context menu of resource, select Team -> Synchronize with<br />
Repository.<br />
The project in your workspace will be compared to the branch. If there are<br />
differences you will see them in the Synchronize view. There are three modes<br />
in which resources are synchronized in the view:<br />
– Incoming mode: Shows incoming changes only (resources in the steam<br />
that differ from what is in the workbench).<br />
– Outgoing mode: Shows outgoing changes only (resources that have been<br />
modified in the workbench only).<br />
– Incoming/Outgoing mode: Shows both incoming and outgoing changes.<br />
You can switch to any of these three modes by using the view’s toolbar<br />
buttons.<br />
530 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 15-7 Synchronizing with the repository<br />
To see the difference in a workspace resource and the same resource in the<br />
repository, double-click the resource in the Structure Compare area and both<br />
versions will be opened in the Text Compare area. The workbench file is on<br />
the left side and the repository file is on the right side.<br />
15.6.2 Dealing with conflicting changes<br />
If you have modified a resource and no one else has committed a change for the<br />
same resource to the repository, then there is no conflict and you can continue<br />
with a commit. But if you have changed a resource and the copy you started with<br />
was also changed by someone else and committed, then you have a true conflict.<br />
To see true conflicts, click the Show only conflicts button on the Structure<br />
Compare toolbar. Conflicts are indicated by a red arrow in the view.<br />
Chapter 15. Development in a team environment 531
Figure 15-8 Working with conflicts<br />
If you find that you have a conflict, you can choose to do one of the following:<br />
► You can take the change from the branch (update to it) and discard your local<br />
changes.<br />
This could be the right action to take if you have made unintended changes<br />
locally, or if you realize that the version in the branch is “better” than yours.<br />
Overwriting your local changes should be done with caution since you are in<br />
essence throwing work out.<br />
► You can commit your change, overwriting the copy in the branch.<br />
Note: This should be done only with great caution and, if possible, after<br />
consulting with the other developer(s). In essence you are throwing away<br />
someone else's work. The change you are overwriting may have other<br />
dependencies in the branch.<br />
► You can resolve the conflicts manually and mark the resource in your<br />
workspace as “merged”. You may then later choose to commit this merged<br />
result.<br />
Merging will typically be the preferred option because of the risk of<br />
unintentionally losing work associated with the other two options.<br />
532 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Merging changes<br />
The Synchronize view shows those resources that are in conflict with the<br />
repository. For a given resource in conflict, typically you will want to merge your<br />
changes with changes in the branch’s resource.<br />
For example, let us assume that both you and another team member have<br />
modified the same HTML page. Selecting that resource in the Synchronize view<br />
will display a comparison of the local resource and the branch version. By cycling<br />
through and resolving the individual conflicts by manually updating the code, you<br />
can decide for each change whether to accept the incoming change, reject it, or<br />
merge it with your local changes. When you are finished resolving the conflicts,<br />
you save your changes in your workspace. You can subsequently commit this<br />
merged resource.<br />
Figure 15-9 Resolving conflicts<br />
You can resolve conflicts in the Incoming/Outgoing view in the following ways.<br />
► Whole document: In the Structure Compare editor, select the resource that<br />
you want to merge so that the resource is displayed in the Text Compare<br />
editor. In the Text Compare editor, click the Copy all from right to left button<br />
to entirely replace the text in your local editor with the contents of the<br />
repository copy.<br />
Chapter 15. Development in a team environment 533
► Current change: In the Text Compare editor, either use the Select Next<br />
Change and Select Previous Change buttons to navigate to the conflict that<br />
you want to resolve, or simply click in either source pane somewhere in the<br />
desired change difference section. Click the Copy current change from<br />
right to left button when you want to overwrite the highlighted fragment with<br />
the corresponding modification in the repository.<br />
► Manually: If you want to combine the two changes you can use copy and<br />
paste to move data from the repository copy to the local copy.<br />
Note: You will see more on comparing two files in 15.9.4, “Working with the<br />
comparison” on page 547.<br />
When you are done, you can save your local version by selecting Save in the<br />
context menu of the text compare area for the local copy.<br />
This will prompt you to save your changes. If you have updated your working<br />
copy you will be reminded to mark the new file as merged when you are done.<br />
This flags the resource as an outgoing change.<br />
Figure 15-10 Mark as merged<br />
To mark the resource as merged, select it in the Structure Compare area, and<br />
select Mark as Merged in the context menu.<br />
534 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 15-11 Marking the new local copy as merged<br />
15.6.3 Updating from the repository<br />
Updating is the act of taking changes committed by others to the branch and<br />
copying to your workspace, replacing your copy.<br />
You can update your workspace with the work that has been done by other team<br />
members and committed to the branch since you last synchronized. To update<br />
workbench resources:<br />
1. Select the resource or project in the navigator view you want to update.<br />
2. From the context menu, select Team -> Synchronize with Repository.<br />
3. In the Synchronize view, select the Incoming mode button on the view’s<br />
toolbar. The resources that are different in the respository will be flagged. If<br />
you want to see the actual differences you can double-click the resource and<br />
the two versions will open in the Text Compare area.<br />
4. Click the Show only conflicts icon to see a list of resources that have true<br />
conflicts. If there are no conflicts (no red arrows), you can update the<br />
resources in the workbench without losing any changes you have made.<br />
Chapter 15. Development in a team environment 535
If there is a conflict, use the Text Compare area to resolve the conflicts.<br />
5. Once you are ready to bring in the changes from the repository, select the<br />
top-most resource in the hierarchy in the Structure Compare area and select<br />
Update from the context menu.<br />
Note: The branch itself is not changed when you update. When you accept<br />
incoming changes, these changes are applied to your workspace. The branch<br />
is only changed when you commit or merge your outgoing changes.<br />
15.6.4 Committing changes to the repository<br />
When you have made changes to a resource, you need to commit the resource<br />
to the repository for use by other team members. Committing a resource copies it<br />
from your local workbench to the repository branch. As a result, these changes<br />
are then seen as incoming changes when other developers update from the<br />
branch later.<br />
Note: Update first! You should update your local copy from the current branch<br />
before committing your changes. This ensures that you have the very latest<br />
work from the other team members.<br />
To commit a resource:<br />
1. Select the resource you want to commit from the Project Navigator view.<br />
2. From the resource’s context menu, select Team -> Synchronize with<br />
Repository.<br />
3. In the Synchronize view, select the Outgoing mode button on the view’s<br />
toolbar. You can see the outgoing changes in the Text Compare area.<br />
4. If there are no conflicts, you can commit the resource, creating a new revision<br />
of the resource in the branch.<br />
If there is a conflict, use the Text Compare area to resolve your conflicts first.<br />
Once all the conflicts have been resolved, you are ready to commit.<br />
5. In the Structure Compare area, select the top-most resource in the hierarchy<br />
and select Commit from the context menu.<br />
536 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
15.7 Using multiple branches<br />
The current resources in a project in the repository are stored in a branch. The<br />
CVS repository always has a default branch called HEAD. This is the main trunk<br />
in the repository where development typically takes place.<br />
In some circumstances it may be convenient to create a new branch. This allows<br />
you to isolate the work you are doing from other developers. For example, if you<br />
are trying to debug a problem you could create a separate branch to work from.<br />
This keeps changes that others are making from affecting your debugging efforts.<br />
It also gives you the freedom to change things that might normally affect other<br />
components. In the meantime, the primary development efforts can continue to<br />
take place in the HEAD branch.<br />
When you have accomplished your task in the secondary branch you can merge<br />
the relevant changes back into the HEAD branch.<br />
15.7.1 Creating a new branch<br />
Creation of a new branch in the CVS Repositories view can be seen as defining a<br />
new branch name. The underlying CVS branch is not created until you explicitly<br />
copy a project version or commit contents to the repository. Branch name<br />
definitions persist between workspace sessions until explicitly removed within the<br />
CVS Repositories view.<br />
Note: You need to be careful when using alternate branches. Adding a project<br />
from the branch to the workspace via the CVS Repositories view or<br />
associating it with another branch in another repository deletes all existing<br />
synchronization information currently managed for the given project and<br />
reinitializes with the new information for the newly added/reassigned project.<br />
Using another branch in the same repository does not change the<br />
synchronization information.<br />
There are two options for putting a project in a branch:<br />
► Based on a project version<br />
Choose this option if you are splitting based on an existing project version in<br />
the repository, for example, to fix a bug in a previous version of your project.<br />
Chapter 15. Development in a team environment 537
► Based on the project in your workspace<br />
Sometimes you don't want to commit your changes to everyone in the team<br />
but would still like to version them. You may want to do this, for example, if<br />
your changes are not yet stable, or if it will take a long time before you are<br />
ready to commit them to the team. In this case, you may want to create a new<br />
branch to commit your changes to.<br />
Creating a new branch based on a project version<br />
To create a new branch from an existing project version, do the following:<br />
1. Open the CVS Repository Exploring perspective.<br />
2. Find Branches in the CVS Repositories view, right-click, and select Add to<br />
Branch List... from the context menu.<br />
3. Enter the new branch name and click OK. The new tag is created and you are<br />
ready to add a project to this new branch.<br />
4. In the CVS Repositories view, select the project under the HEAD branch that<br />
you want to split off into the new branch you just created. Select Tag with<br />
Existing from the context menu.<br />
5. Expand the versions folder and select the version. Click OK.<br />
6. You can now expand the project under the new branch. The resources are<br />
now there and should have the same revision levels you see in the original<br />
version.<br />
7. Highlight the new project under the branch and select Check Out As Project<br />
from the context menu. Note that this will overwrite the copy that you have in<br />
your workspace.<br />
Creating a new branch from the workspace<br />
The first step is to define a new branch in your workspace and associate the<br />
project with it:<br />
1. From the Project Navigator view, select the project you want to create a<br />
branch for, and from the context menu select Team -> Branch.<br />
2. Enter a new branch name (for example, DebugLoginBranch), select Start<br />
working in the branch, and click OK.<br />
The new branch exists in your workspace and you can continue working with the<br />
project. Any commits you perform will be done to the new branch.<br />
If you want multiple projects associated with this branch, simply repeat these<br />
steps and enter the same branch name for each project.<br />
538 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: When you create a new branch, whether from the workspace or from<br />
the repository, a new version is created in the repository.<br />
15.7.2 Accessing the branch from another workbench<br />
Though the new branch exists in the repository, it is not automatically visible to<br />
other users. Anyone wanting to work in the same branch will have to manually<br />
add the branch name in the CVS Repositories view.<br />
1. Go to the CVS Repositories view and select the Branches folder under the<br />
repository where you want to create the new branch.<br />
2. From the context menu, select Refresh Branches....<br />
3. Select the corresponding projects from the available list of the Select Projects<br />
dialog and click Finish.<br />
Figure 15-12 Select project(s)<br />
Chapter 15. Development in a team environment 539
Tip: You can see existing branch names for a project by viewing the CVS<br />
resource history for a resource in the project. See 15.8, “Viewing resource<br />
history” on page 542.<br />
In the CVS Repositories view, expand Branches and observe that it now<br />
contains the new branch.<br />
To begin working with a project in the new branch, you will need to do one of two<br />
things:<br />
► If you do not already have the project in your workbench, choose the project<br />
under the new branch and select Check Out As Project from the context<br />
menu. Switch to the Web perspective and you will see the new project.<br />
► If you do have the project in your workspace and want to associate it with the<br />
new branch:<br />
a. Switch to the Web perspective and select the project in the Project<br />
Navigator view. From the context menu, select Team -> Branch.<br />
b. Enter the new branch name. If you need a reminder of the branch names,<br />
click Details. Click OK.<br />
If the above operation does not result in the discovery of any tags, it is probable<br />
that the folder in the repository does not have a .project file in it. The .project file<br />
is the default file used by the tag discovery process. The file can be changed for<br />
individual projects using Configure Branches and Versions.<br />
To discover existing branch and version tags for a single project folder:<br />
1. Switch to the CVS Repository Exploring perspective or add the CVS<br />
Repositories view to the current perspective.<br />
2. In the CVS Repositories view, expand the repository location.<br />
3. Expand HEAD and select the root folder whose tags are to be discovered.<br />
4. From the pop-up menu for the CVS Repositories view, select Configure<br />
Branches and Versions. The Tag Configuration dialog will open.<br />
5. In the top pane on the left (titled Browse files for tags), expand one or more<br />
projects to find a file that is known to have tags that should be added to the<br />
CVS Repositories view.<br />
6. Select a file in the top left pane. If the file selected has tags defined on it, they<br />
will be displayed in the right top pane (titled New tags found in selected files).<br />
7. Select or deselect the tags in the right pane as desired.<br />
8. Click Add Checked Tags to add the checked tags to the list of remembered<br />
tags.<br />
540 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
9. Click OK to add the remembered tags to the selected repository location or<br />
project.<br />
15.7.3 Merging branches<br />
Merging two branches involves identifying changes that have been made<br />
between two points in the new branch and merging them into a workspace that<br />
contains the HEAD branch.<br />
Note: It is important to realize that the destination of the merge is always the<br />
project in your workspace. After the merge has completed, you should first test<br />
the changes locally and only then commit them to the new branch.<br />
The following is a scenario for working with multiple branches. It assumes that a<br />
new branch was created to add maintenance fixes. Once the maintenance is<br />
complete, the new branch is merged back into the HEAD branch.<br />
Table 15-1 Working with multiple branches<br />
Developer 1 (maintenance developer) Developer 2<br />
Checks out the project from the HEAD<br />
branch<br />
► Defines a branch tag (BeginMaint)<br />
► Tags project in workspace as new<br />
branch<br />
A new version called Root_BeginMaint is<br />
also created<br />
Adds & changes files in the BeginMaint<br />
branch<br />
Commits changes to the BeginMaint<br />
branch<br />
Loads the HEAD branch into the<br />
workspace<br />
► Select the project in the Web<br />
perspective.<br />
► Select Replace with -> Another<br />
Branch or Version from the context<br />
menu.<br />
► Select the HEAD branch.<br />
Checks out the project from the HEAD<br />
branch<br />
Adds and changes files in the HEAD<br />
branch<br />
Commits changes to the HEAD branch<br />
Chapter 15. Development in a team environment 541
Developer 1 (maintenance developer) Developer 2<br />
Merges changes made to the HEAD<br />
branch since the new branch was created<br />
into the workspace<br />
► Select project in Web perspective.<br />
► Team -> Merge.<br />
► Merge start point is Root_BeginMaint.<br />
► Merge changes from BeginMaint<br />
branch.<br />
Uses the Structure Compare and Text<br />
Compare views to update from the<br />
repository and to resolve conflicts<br />
Adds new files picked up during the merge<br />
to version control and commits the newly<br />
merged code to the HEAD branch<br />
Deletes the BeginMaint branch<br />
15.8 Viewing resource history<br />
You can view the history of a resource in the CVS Repositories view from almost<br />
any navigator where you can select a project resource. The history will show you<br />
a list of all revisions, who created the revision, the date and time, revision<br />
comments, and associated tags. Versions will be indicated by the associated<br />
tags.<br />
To see the CVS server history for a resource select Team -> Show in Resource<br />
History from the context menu of the resource in the navigator view. If you are in<br />
the CVS Repository Exploring this is simply Show in Resource History.<br />
542 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Synchronizes with HEAD to pick up the<br />
fixes
Figure 15-13 shows an example of the history of a resource.<br />
Figure 15-13 Viewing the CVS repository history of a resource<br />
Chapter 15. Development in a team environment 543
You will find the following information in the CVS Resource History view:<br />
► Revision: The repository-generated revision number. Each revision<br />
represents a commit for the resource. The commit only happens when the<br />
resource is changed so a revision indicates a change in the resource.<br />
► Tags: When a new version or branch is created the resources involved have a<br />
tag associated with that revision. The tag is entered by the person making the<br />
change. When you select a project and then tag it as a version, you enter the<br />
tag name. For a branch, it is the branch name.<br />
When a resource is associated with a new branch and committed, a tag is<br />
added to the revision indicating the branch. For example, you can see in<br />
Figure 15-13 on page 543 that revision 1.6 was used as the basis for two new<br />
branches. The first branch name is Dev2sBranch. The version created when<br />
the project was committed to the branch is Root_Dev2sBranch. The second<br />
branch is Dev1sBranch.<br />
► Date: When the revision was created (committed).<br />
► Author: Who created (committed) this version.<br />
► Comment: If any were added by its author.<br />
You might need to maximize this view in your perspective to be able to see the<br />
complete information. Each column can be sorted in ascending order by clicking<br />
the column heading.<br />
Tip: You can compare two revision levels of the resource in this view by<br />
selecting both entries (Ctrl+click each) and select Compare from the context<br />
menu.<br />
15.9 Comparing resources<br />
You can compare two selected resources to view the differences between them.<br />
You can do the compare at the file, folder, or project level. You can also compare<br />
a resource with other states in the local edit history or with other versions of that<br />
resource.<br />
When a comparison is performed, all applicable compare editors appear in the<br />
editor area. You can browse through the differences and copy/move the<br />
highlighted differences between the compared resources. You can then save<br />
changes to resources that were made in the compare editor.<br />
544 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
15.9.1 Comparing a resource<br />
The first type of compare you can perform is to compare a resource to another<br />
state of the same resource. To do this:<br />
1. Select the resource in a navigator, and then select one of the following from<br />
the context menu:<br />
– Compare a workbench resource with a branch or version: When you<br />
select a resource in the workbench, you can compare it with a branch or<br />
version of the resource that has been committed to the repository.<br />
– Compare a workbench resource with the latest from the repository:<br />
When you select a resource in the workbench, you can compare it with the<br />
the copy of the resource currently committed to the branch.<br />
– Compare a workbench resource with its local history: When you<br />
select a resource in the workbench that has been modified, you can<br />
compare it with its state prior to modification. This is because the base<br />
version denotes the version that you have loaded.<br />
2. In the compare dialog that will be opened, you can now browse to select the<br />
version with which you want to compare the workbench resource. Notice you<br />
can see the differences between the version and the workbench resource in<br />
the text compare area.<br />
15.9.2 Comparing two selected files<br />
A two-way compare shows the differences between two selected files. To<br />
compare two resources in the workspace:<br />
1. Ctrl+click to multi-select two resources in a navigator or the CVS Repositories<br />
view.<br />
2. From the resources context menu, select Compare.<br />
3. The Comparison editor displays, showing the differences between the<br />
resources.<br />
15.9.3 Three-way compare<br />
Note: If you have not added the resource to version control then you will<br />
only see the option to compare to local history.<br />
Three-way compare shows the differences between two resources and their<br />
common ancestor. This feature is most useful when merging or synchronizing<br />
resources.<br />
Chapter 15. Development in a team environment 545
When such a situation occurs, you will be able to view the differences between<br />
these three different resource versions:<br />
► The resource in the workbench<br />
► The version of the resource that is committed in the branch<br />
► The common ancestor on which the two conflicting versions is based<br />
The differences that will be highlighted show you what has been changed in the<br />
workbench resource as compared to the common ancestor, and what has been<br />
changed in the branch resource as compared to the common ancestor.<br />
A typical scenario to do this comparison would be:<br />
1. Synchronize with the repository.<br />
2. Open the Show only conflicts.<br />
3. Select a resource that is in conflict and open it in the Text Compare area by<br />
double-clicking it.<br />
Figure 15-14 Two-way compare<br />
4. Select the Show Ancestor button to have the original file come up.<br />
546 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 15-15 Three-way compare<br />
15.9.4 Working with the comparison<br />
Any comparison will cause a comparison editor to open.<br />
Chapter 15. Development in a team environment 547
Figure 15-16 File (text) compare editor<br />
There are two parts in the compare editor's local toolbar. The right group of local<br />
toolbar buttons allows you to move to the next or previous change:<br />
► Click the Select Next Change button to select the next change.<br />
► Click the Select Previous Change button to move to the previous change.<br />
The left group of local toolbar buttons allows you to merge changes from the left<br />
file to the right file and vice versa. There are four types of merges you can<br />
perform:<br />
► Copy whole document from left to right.<br />
► Copy whole document from right to left.<br />
► Copy current change from left to right.<br />
► Copy current change from right to left.<br />
Typically the copy whole document actions are used when you are sure that the<br />
entire file on either the left or right can just be replaced by the contents of the<br />
other file. The Copy current change button allows you to merge the single<br />
changes one by one.<br />
You can close and save the workspace copy by selecting Save from the context<br />
menu of the left comparison window.<br />
548 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
15.10 Determining which files are managed<br />
Files are not automatically managed by the repository. As you have seen in the<br />
previous discussions, adding a file to version control is a conscious decision. If<br />
you do not add a file to version control, it is not copied to the repository, even<br />
though you may commit the entire project.<br />
When you first commit a project, you are given the opportunity to add the<br />
resources currently in the project to version control. If you select this option all<br />
files will be included.<br />
However, there may be some files that you never want to send to the repository,<br />
for example, .class files. You can automatically exclude these from any commits<br />
by doing one of the following:<br />
► Use the global ignore facility to specify file names or patterns that apply to all<br />
projects in the workbench.<br />
To add a global ignore pattern for the workbench, simply select Window -><br />
Preferences to open the Workbench preferences dialog and select the Team<br />
-> Ignored Resources category. Click Add to add the pattern to ignore.<br />
► Use the CVS Ignore facility to specify file names or patterns that apply to a<br />
specific project directory.<br />
Note: The ignore file only relates to the files and folders contained in that<br />
directory, so you may require many .cvsignore files throughout the project.<br />
For example, if you want to create a .cvsignore file that will keep anything in<br />
the classes folder from being sent to the repository:<br />
a. Select the WEB-INF/classes folder, and select Team -> Add to<br />
.cvsignore from the context menu.<br />
b. Select the wildcard extension option. This will create an entry in .cvsignore<br />
to exclude all files with an extension like the one you selected, or if you<br />
selected a folder, all files in the folder.<br />
c. Click OK.<br />
To work with the .cvsignore file you will need to switch to the Resource<br />
perspective. You will not see it in the Project Navigator view. When using this<br />
method, it is a good idea to:<br />
a. Create the .cvsignore files before you commit for the first time.<br />
b. Add the .cvsignore files to version control so they are copied to the<br />
repository and others pick them up with the project.<br />
Chapter 15. Development in a team environment 549
550 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Chapter 16. Security<br />
As new business practices emerge, most enterprises are finding that their<br />
existing security infrastructure is not capable of meeting the rapidly changing and<br />
more rigorous demands of business over the Internet. The demands of network<br />
security have now gone far beyond simply managing user accounts and<br />
restricting access between internal and external networks.<br />
Physical security is the most basic type of security, providing protection against<br />
physical access to the computers. Logical security involves protecting the<br />
applications and network from unauthorized access or harm. This normally<br />
involves the use of firewalls and other security products that filter out unwanted<br />
network traffic and ensure that only valid users can access the applications and<br />
resources that constitute the business.<br />
This chapter will address the security options provided by <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express.<br />
16<br />
© Copyright <strong>IBM</strong> Corp. 2003 551
16.1 Terms<br />
Before starting this topic, take a minute to review the following security terms:<br />
► Authentication: The process of establishing whether a client is valid in a<br />
particular context. A client can be an end user, a machine, or an application.<br />
Typically you would think of this as a login process.<br />
► Authorization: The process of checking whether the authenticated user has<br />
access to the requested resource.<br />
► Principal: an entity in the computer system to which permissions are granted.<br />
► Realm: A collection of users that are controlled by the same authentication<br />
policy.<br />
As we discuss the security options in <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express,<br />
you will see these terms and should have an understanding of what they mean.<br />
16.2 Securing applications in <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express<br />
Implementing security in <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express is relatively<br />
easy. The basic steps needed to secure your applications are:<br />
► Determine the authentication method.<br />
► Determine the actions that you want to restrict and define a scheme of roles<br />
that can be used for authorization purposes. If you simply want to restrict<br />
access to certain pieces of JSP or servlet code, you can do this without<br />
changing any application code. For more advanced techniques, you can<br />
introduce code in your application that will perform authorization before<br />
allowing the user to perform certain actions.<br />
► Define users and groups to the <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express<br />
operating system and assign those users and groups to the roles you have<br />
defined.<br />
► Enable <strong>WebSphere</strong> security and/or code applications to implement security.<br />
552 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express can only secure components<br />
that it owns. In many instances, you will be providing an HTML interface into<br />
your applications using an external Web server. Any static pages that are<br />
served from the Web server must be protected using Web server related<br />
security mechanisms. These mechanisms are transparent to the <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express.<br />
16.3 Authenticating users<br />
Authentication is the process of identifying a user and determining whether the<br />
user is who he claims to be. This is typically the first security check done in a<br />
Web application, and is done by collecting a user ID and password from the user<br />
and comparing that to a user registry. The login ID becomes the principal used in<br />
future authorization actions.<br />
► Basic authentication<br />
The user is challenged and must enter a user ID and password. The user ID<br />
and password are encoded by the browser and included in the HTTP request<br />
to the server. If you select basic authentication, Express <strong>Application</strong> <strong>Server</strong><br />
provides the login forms and authenticates using the operating system<br />
security.<br />
► Form-based authentication<br />
This method allows the developer to control the authentication process. This<br />
means that whenever a resource is accessed and authentication is required,<br />
your form will be used to collect and process the login information. By default,<br />
the user ID and password values supplied by the end user are transmitted in<br />
clear text as parameter values in the HTTP request. To secure the user<br />
information during transmission, this channel should be encrypted.<br />
Note: For any type of authentication to take place, you must have enabled<br />
<strong>WebSphere</strong> security and secured at least one resource.<br />
The authentication method is configured in the Web deployment descriptor under<br />
the Pages tab.<br />
Chapter 16. Security 553
Figure 16-1 Web module deployment descriptor: Pages<br />
16.3.1 Form-based authentication<br />
Form-based authentication (login) enables the application developer to<br />
customize the login process and present an application-specific form for login.<br />
Form login works in the following manner:<br />
1. An unauthenticated user requests a protected resource.<br />
2. The application server redirects the request to the login form defined by the<br />
Web deployment descriptor.<br />
3. The user is presented with the HTML login form, enters a user ID and<br />
password, and submits the form.<br />
4. The form submission triggers a special <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express servlet called j_security_check. After receiving a request for the<br />
j_security_check servlet, the Web container dispatches the request into<br />
another <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express servlet that authenticates<br />
the user.<br />
5. If the servlet authenticates the user successfully, the requested resource is<br />
displayed.<br />
554 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
The following steps illustrate how to implement a form-based login.<br />
1. Create a login form. In this case we will create a login form called login.html.<br />
– The action required for the HTTP POST method is j_security_check. This<br />
method automatically registered on the level of the context root.<br />
– j_username should be the input field in which a user will write the user ID.<br />
– j_password should be the input filed into which a user will write the<br />
password.<br />
Example 16-1 shows a sample login form.<br />
Example 16-1 Sample custom login form<br />
<br />
<br />
<br />
Userid:<br />
<br />
Password:<br />
<br />
<br />
<br />
<br />
<br />
Note: The j_security_check servlet will not work when global security is<br />
disabled; the application server will return a page not found error. See<br />
“Enable <strong>WebSphere</strong> global security” on page 566.<br />
2. Open the Web deployment descriptor (web.xml) for the project and select the<br />
Pages tab.<br />
a. Enter a realm name.<br />
b. Click the drop-down list and select FORM as the authentication method.<br />
c. In the Login page click Browse and select login.html.<br />
d. In the Error page click Browse and select loginerror.html. (We have used<br />
the same page for log in and error. You can define a custom error.jsp page<br />
that will present an actual error code and error message.)<br />
3. Save and close the deployment descriptor.<br />
Chapter 16. Security 555
16.4 Securing applications with role-based security<br />
<strong>Application</strong> security is implemented using J2EE role-based security. Security<br />
roles provide a mechanism whereby application developers determine the<br />
security policies for an application by creating named sets of users (for example,<br />
managers, customers, employees) that will have access to secure resources and<br />
methods.<br />
At application development time, these sets of users, or security roles, are not<br />
tied to any real users or groups of users. Instead, they are placeholders that are<br />
later mapped to real users and groups at application deployment time, during a<br />
process called security role mapping.<br />
Principals and Groups<br />
Daffa<br />
Iza<br />
Department XYZ<br />
Figure 16-2 Security roles<br />
Security Role<br />
Mapping<br />
Security Roles<br />
Manager<br />
Consultant<br />
Accountant<br />
This two-phase security administration approach allows for a great deal of<br />
flexibility and portability. Deployers of an application have full control over how<br />
their local users and groups are mapped to the application’s security roles, and<br />
over what authorization and authentication mechanisms are used to determine<br />
role membership.<br />
556 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
Staff<br />
Web Component Resources<br />
JSPs<br />
Servlets<br />
Static Content
At deployment time, security roles can be mapped to users, groups of users, or to<br />
two special subjects available in Express <strong>Application</strong> <strong>Server</strong>:<br />
► All authenticated users<br />
► Everyone<br />
Role-based security can be implemented in one of two ways:<br />
► Declarative security means the security policies are configured at application<br />
assembly time, external to the application code.<br />
► Programmatic security is used when an application must be “security aware”.<br />
For instance, a method might need to know the identity of the caller for<br />
logging purposes, or it might perform additional actions based on the caller’s<br />
role. The J2EE specification provides an API that includes methods for<br />
determining both the caller’s identity and the caller’s role.<br />
For many applications, securing methods using declarative security will be<br />
sufficient. However, there may be times when you need more specific control<br />
than declarative security provides. For example, if you have a servlet that<br />
handles the transfer of money from one account to another, you can protect the<br />
methods in the servlet so that only users with the Customer role can execute it.<br />
This means that only users with the Customer role can transfer money.<br />
With programmatic security, you can go further by checking the roles before<br />
allowing certain actions to take place. For example, if a customer tried to transfer<br />
over 50 percent of her balance from one account to another, the servlet could<br />
check to see if the customer had the GoldenClub role and only allow the transfer<br />
if true.<br />
16.4.1 Declarative security<br />
When using declarative security, application developers are free to write<br />
component methods that are completely unaware of security. By making<br />
changes to the deployment descriptor, an application’s security environment can<br />
be radically changed without requiring any changes in application code.<br />
Servlets can be protected at the method level by naming roles that are<br />
authorized to use the method. The key here is to remember that when it comes to<br />
running a JSP on a server, the JSP is actually executed as a servlet. So when we<br />
talk about securing servlets, you can mentally include JSPs in the discussion.<br />
Protecting servlet methods using J2EE security involves the following steps:<br />
1. Define users and groups to the server operating system. Express <strong>Application</strong><br />
<strong>Server</strong> will use the security system of the server’s local operating system to<br />
authenticate users and groups.<br />
Chapter 16. Security 557
2. Define roles to represent a logical grouping of users. Example roles would be<br />
Customer, Administrator, Operator. Roles are defined in both the Web<br />
deployment descriptor and EAR deployment descriptor.<br />
3. Define constraints to protect servlet and JSP HTTP methods by role. This is<br />
done in the Web deployment descriptor.<br />
4. Assign users or groups to roles. Real users and groups defined to the<br />
operating system must be associated to the roles defined in the application.<br />
This is done in the enterprise application deployment descriptor.<br />
5. Enable <strong>WebSphere</strong> global security. <strong>WebSphere</strong> global security must be<br />
enabled to activate the role-based security checking. This is done in the<br />
server configuration.<br />
Example: Securing a JSP<br />
As an example, let us take the Online Catalog application and introduce security<br />
measures. It is easy to see several logical roles that could be used, for example,<br />
shoppers, catalog administrators, and order department.<br />
Note: In this example we are actually adding a second layer to the our<br />
application security. The first layer is programmed using the login servlet. To<br />
get past that checkpoint, they need to know the user ID and password stored<br />
in the application database (admin/admin). This method was used to illustrate<br />
a simple login procedure based on information stored in a user database and<br />
is not related to <strong>WebSphere</strong> security.<br />
In the second layer of security we are going to ignore this first login and secure<br />
the application at the JSP level using J2EE role-based security.<br />
The process will consist of:<br />
1. Defining the role.<br />
2. Defining a constraint.<br />
3. Assigning the role to the constraint.<br />
4. Identifying the authentication method and the realm.<br />
5. Defining the roles to the enterprise application.<br />
6. Identifying real users defined to the local operating system that have the<br />
CatalogAdmin role.<br />
7. Enabling global security on Express <strong>Application</strong> <strong>Server</strong>.<br />
Figure 16-3 on page 559 shows an overview of the security settings for an<br />
application and their relation to each other.<br />
558 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
application.xml (security tab)<br />
user-role<br />
CatalogAdmin<br />
admin1<br />
OrderDept<br />
orderadmin1<br />
web.xml (servlets tab)<br />
servlets<br />
MasterCatalogView<br />
URLs<br />
/MasterCatalogView<br />
/Administration/MasterCatalogView<br />
OrderCatalogView<br />
URLs<br />
/Administration/OrderCatalogView<br />
web.xml (security tab)<br />
roles<br />
CatalogAdmin<br />
OrderDept<br />
Authorized roles<br />
CatalogAdmin<br />
OrderDept<br />
(optional)<br />
Authorized roles<br />
CatalogAdmin<br />
OrderDept<br />
(optional - can be used<br />
for programmatic<br />
security)<br />
Figure 16-3 Web module deployment descriptor security options<br />
Security constraint (1)<br />
Methods<br />
Get method<br />
Put method<br />
URLs<br />
/MasterCatalogView<br />
/Administration/MasterCatalogView<br />
/AddNewItemProcess<br />
Security constraint (2)<br />
Methods<br />
Get method<br />
Put method<br />
URLs<br />
/Administration/OrderCatalogView<br />
Define the role<br />
Roles are defined in the Web deployment descriptor for each Web module, then<br />
later rolled up into the application deployment descriptor. We will start by defining<br />
the CatalogAdmin role.<br />
1. Open Web Content/META-INF/web.xml.<br />
2. Select the Security tab.<br />
3. Select security roles at the top and click Add below the window.<br />
4. Type in the name of the role, CatalogAdmin.<br />
Chapter 16. Security 559
Figure 16-4 Add a role<br />
Define the constraint<br />
The security constraints define the URLs and methods whose execution is<br />
limited to users who have the appropriate role(s). In this case we will say that<br />
only users with the CatalogAdmin role can view customers. To do this, we will<br />
secure CustomerMasterView.jsp.<br />
1. The first thing you will need to know is the URL(s) of the servlet that you want<br />
to protect. In the Servlets tab of web.xml you can see the registered JSPs and<br />
servlets. Note that there are two URL mappings for CustomerMasterView.<br />
560 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 16-5 Noting the servlet URLs<br />
Note: You may notice the Security Role References box on the servlets<br />
page. This is used with programmatic security. It allows the developer to<br />
hardcode roles in the application that may not match the roles defined to<br />
the Web module. The role used in the application are linked to real roles in<br />
the deployment descriptor. For this exercise you will not use this. At this<br />
level of Studio Site Developer, this feature is not very useful. As you<br />
migrate up to more complex levels of <strong>WebSphere</strong> Studio and <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong>, you will most likely implement this, if necessary, in the<br />
AAT tool provided with the higher level servers.<br />
2. Switch back to the Security tab, select the Security Constraints tab, and<br />
click Add below the window. A new Security Constraint entry will appear in<br />
the box and a new New Web Resource Collection entry in the panel beside it.<br />
Chapter 16. Security 561
Figure 16-6 Adding a constraint<br />
3. Select the New Web Resource Collection entry and click Edit. This allows<br />
you to enter the URL(s) or URL patterns for the Web resources you want to<br />
protect. Enter the patterns and select the HTTP methods you want to protect.<br />
562 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Tip: If a servlet is called using some type of redirection on the server side,<br />
security will be bypassed. A good example is the front controller created by the<br />
Database Web Pages wizard. Let us say you used the wizard to create the<br />
following:<br />
► ListCatalogInputForm.html<br />
► ListCatalogController.class<br />
► ListCatalogMasterView.jsp<br />
► ListCatalogDetailsView.jsp<br />
The user starts with ListCatalogInputForm.html where the following code is<br />
used to invoke ListCatalogMasterView.jsp (via ListCatalogController.class):<br />
<br />
You must secure ListCatalogController.class in order to get an authentication<br />
challenge.<br />
Figure 16-7 Add the servlets and methods to protect<br />
In this case it is sufficient to select the GET and POST methods, but it does<br />
not hurt to specify all of them.<br />
Click OK.<br />
Chapter 16. Security 563
Assign a role to the constraint<br />
With the constraint still highlighted, click Edit beside the Authorized Roles box.<br />
When the window opens, select the roles allowed to access the servlets. In order<br />
to access the Web resource, the user must have been granted at least one of the<br />
roles selected.<br />
Figure 16-8 Associate the role with the constraint<br />
Note: You also have a user data constraint option on the Security page. The<br />
user data constraint options allow you to chose a transport guarantee, which<br />
defines how the communication between the client and the server is to be<br />
protected. There are three options to choose from:<br />
► None<br />
No constraint indicates that the application does not require any transport<br />
guarantee.<br />
► Integral<br />
This ensures that data cannot be changed in transit. In practice, this means<br />
that a request must be transmitted over an SSL-encrypted channel.<br />
► Confidential<br />
This ensures that data cannot be changed or viewed in transit. In practice,<br />
this means that the request must be transmitted over an SSL-encrypted<br />
channel.<br />
Define the authentication method<br />
To define the authentication method:<br />
564 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
1. Select the Pages tab in the Web deployment descriptor.<br />
2. Select Basic for the authentication method.<br />
3. Enter a realm name. The realm name basically identifies the user registry that<br />
will be used to authenticate. A user that accesses resources in multiple<br />
realms can simply look at the realm name presented with the challenge<br />
screen to know which system, and thus user ID/password combination, to<br />
use.<br />
Figure 16-9 Define the authentication method<br />
Gather the roles and assign real users<br />
The next step is to update the EAR deployment descriptor with the roles you<br />
have defined.<br />
1. Open the EAR deployment descriptor and select the Security tab.<br />
Chapter 16. Security 565
Figure 16-10 Enterprise application security settings<br />
2. Click Gather to collect the roles defined in the Web modules. Note that this<br />
allows you to define the roles in multiple Web modules that belong to this<br />
enterprise application and easily collect all roles with the click of a single<br />
button.<br />
3. Assign users to the roles. If you want to select individual users or groups<br />
select the Users/Groups box. Two other special categories are available,<br />
Everyone and All authenticated users. Selecting Everyone is effectively the<br />
same as not securing the resource. Selecting All authenticated users has the<br />
effect of allowing anyone who successfully logged in to access the resource.<br />
Note: The “Security Role Run as Bindings” settings only apply to EJBs.<br />
Enable <strong>WebSphere</strong> global security<br />
The user registry used for authentication is the local operating system. Basically<br />
this means that all security authentication is done by requesting that the user<br />
supply a user ID and password and then authenticating that against users<br />
defined in the local operating system.<br />
566 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
In order to use the J2EE role-based security mechanisms provided by Express<br />
<strong>Application</strong> <strong>Server</strong>, you first must turn on <strong>WebSphere</strong> global security for the<br />
server. You can do this from the server configuration.<br />
1. Switch to the <strong>Server</strong> perspective.<br />
2. Open the appropriate server configuration in the <strong>Server</strong> Configuration view.<br />
3. Switch to the Security tab.<br />
4. Select the Enable Security option.<br />
5. Enter a user ID and password. This can be any valid user on the server<br />
operating system. The user ID and password will be used when starting the<br />
server. Note that if you leave this blank or fill in a user ID/password<br />
combination that is not valid, you will not be able to start the server.<br />
Figure 16-11 Global security<br />
You will need to republish the application and restart the server for all changes to<br />
take effect. The next time you attempt to execute the JSP, you will be challenged<br />
for a user ID and password. The user ID you enter must be assigned the<br />
CatalogAdmin role.<br />
Chapter 16. Security 567
Tip: If you are using Internet Explorer, once you have authenticated with basic<br />
authentication, the Web browser remembers this. There is no logout<br />
mechanism. You will not be challenged on subsequent accesses to secure<br />
resources. This is OK if you are accessing a resource that requires the same<br />
user ID and password, but may cause a problem if you need a second<br />
challenge to enter a new user ID/password. The only way to force a new<br />
challenge is to close the browser and reopen it.<br />
With form-based authentication, the user has the option to log out of one user<br />
ID and log in with another.<br />
16.4.2 Programmatic security<br />
The declarative J2EE security provided by <strong>WebSphere</strong> provides a security<br />
infrastructure for application security that is transparent to the application<br />
developer. That is, the developer does not need to code for security, since it will<br />
all be handled at deployment and runtime.<br />
Having said that, when developing servlets there are a few security calls<br />
available if the developer wants greater control of what the end user is allowed to<br />
do than is provided by the infrastructure. Programmatic security can be used as<br />
an extension of declarative security.<br />
The Servlet 2.3 specification defines three methods that allow programmatic<br />
access to the caller’s security information of the HttpServletRequest interface:<br />
► String getRemoteUser()<br />
The getRemoteUser method returns the user name that the client used to log<br />
in.<br />
String user = request.getRemoteUser()<br />
► Boolean isUserInRole(String roleName)<br />
The isUserInRole method allows the developer to perform additional checks<br />
on the authorization rights of a user, which is not possible (or is more difficult)<br />
to perform through the deployment descriptor of the servlet.<br />
if (request.isUserInRole("Manager")) {<br />
// the user is in the manager role<br />
// ...<br />
}<br />
568 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► java.security.Principal getUserPrincipal()<br />
The getUserPrincipal method allows the developer to get the name of the<br />
current caller. To do this, you need to call getName() on the<br />
java.security.Principal object returned.<br />
Principal principal=request.getUserPrincipal();<br />
String username=principal.getName();<br />
Important: getRemoteUser() and getUserPrincipal() return null as a result,<br />
even if the user is logged in, unless the servlet or the JSP itself is secured.<br />
If you opt to program J2EE calls into your application, you need to do the<br />
following:<br />
1. Define users and groups to the Express <strong>Application</strong> <strong>Server</strong> operating system.<br />
2. Define roles for the application in the Web module deployment descriptor.<br />
3. Define constraints (optional).<br />
4. Assign users or groups to roles in the Web module deployment descriptor.<br />
5. Define the authentication method.<br />
6. Code the servlets to retrieve and check the user role.<br />
7. Enable global security on the Express <strong>Application</strong> <strong>Server</strong>.<br />
Note that the first four steps are the same as those needed to implement<br />
declarative security. The difference is that you do not need to enable <strong>WebSphere</strong><br />
global security and you must add code into your application to provide<br />
authorization.<br />
Sample usage of security methods<br />
Example 16-2 shows a sample of implementing programmatic security. In the<br />
following code the servlet checks to see if the principal attempting to execute the<br />
code is in the proper role before allowing the code to be executed.<br />
Example 16-2 Sample code using the servlet security methods<br />
// getting the environment variables for restricted role<br />
// and for maximum transferable amount<br />
restrictedRole=(String)environment.lookup("RestrictedRole");<br />
maxWebTransferAmount=(Integer)environment.lookup("MaximumWebTransferAmount");<br />
// checking if the user is restricted to a certain amount of transfer<br />
if(request.isUserInRole(restrictedRole) &&<br />
transferAmount>maxWebTransferAmount.intValue()) {<br />
// create an error message<br />
// the user cannot transfer the requested amount<br />
// forward the request to the response page with the message<br />
Chapter 16. Security 569
}<br />
// get the principal from the request<br />
Principal principal=req.getUserPrincipal();<br />
// print out the user information about the servlet invocation<br />
System.out.println("Transfer Servlet was invoked by user:<br />
"+req.getRemoteUser()+", principal: "+principal.getName());<br />
16.5 JAAS security<br />
Java Authentication and Authorization Services (JAAS) is an alternative to the<br />
built-in security support in <strong>WebSphere</strong> allowing programmatic authentication and<br />
authorization to be used within an application. It is a standard extension to the<br />
Java 2 SDK Version 1.3 and it is part of Java 2 SDK Version 1.4. The current<br />
version for JAAS is 1.0.<br />
To illustrated this type of security, let us take an example from the Online Catalog<br />
sample. As supplied with this publication, the sample uses two different methods<br />
of authenticating to the SALESAPP database.<br />
In the first method, the user ID and password required to access the database<br />
are coded within the Web module. The JSPs generated by the Database Web<br />
Pages wizard use this method. The wizard registers each JSP as a servlet in the<br />
Web deployment descriptor and defines three initialization parameters to hold<br />
values for accessing the database: The data source name, the user ID, and<br />
password.<br />
When the JSP connects to the database, the user ID and password are retrieved<br />
from the initialization parameters and used by the jspsql taglib to authenticate to<br />
the database. This method is a little awkward in larger applications because<br />
every JSP that accesses the database need to have the user name and<br />
password initialization parameters defined in the deployment descriptor. The<br />
wizard does this for you automatically, but if you ever need to change the values<br />
you have to update every servlet. Secondly, the password is stored in the clear.<br />
In the second method, JAAS security is used for authentication. This is shown in<br />
Figure 16-12 on page 571. In this case, you do not supply the user ID or<br />
password for database authentication in the application. They are stored under<br />
an alias in the server configuration, and a pointer to that alias is put in the data<br />
source. Whenever the database is accessed, the user ID and password<br />
information in the alias is used for authentication. The advantage is that the user<br />
ID and password are stored in one place and the password is encrypted.<br />
570 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
LoginJSP.jsp<br />
<br />
<br />
<br />
.....<br />
<br />
<strong>Server</strong> configuration<br />
Data source<br />
Security<br />
Name: SALESAPP<br />
JNDI name: jdbc/SALESAPP<br />
Component-managed authentication alias: salesAlias<br />
JAAS authentication entry:<br />
Alias: salesAlias<br />
User ID: db2admin<br />
Password: ********<br />
Figure 16-12 Using JAAS authentication entries<br />
16.5.1 Adding JAAS authentication to a server<br />
The development environment supports the JAAS architecture and extends the<br />
access control architecture to support role-based authorization for J2EE<br />
resources, including servlet, JSP, and EJB components. JAAS maps an<br />
authenticated <strong>WebSphere</strong> user identity to a set of user authentication data (user<br />
ID and password) for a specified back-end Enterprise Information System (EIS).<br />
Note: JAAS authentication can only be added to a <strong>WebSphere</strong> V5.0 server.<br />
To add JAAS authentication, follow these steps:<br />
1. Expand <strong>Server</strong>s in the <strong>Server</strong> Configuration view.<br />
2. Double-click your <strong>WebSphere</strong> server. The server editor opens.<br />
3. Click the Security tab at the bottom of the editor.<br />
4. Click the Add button beside the JAAS authentication entries list table. The<br />
Add JAAS Authentication Entry dialog box opens.<br />
5. In the dialog box, fill in an alias, user ID, password, and description for the<br />
authentication entry. For example, you could enter the alias, DB2 user ID, and<br />
DB2 password to access a DB2 database. For more information about any of<br />
the fields on this dialog box, select the field and then press F1. Click OK.<br />
Chapter 16. Security 571
Figure 16-13 JAAS security<br />
6. Save your changes and close the editor. A JAAS authentication alias has<br />
been added to the server.<br />
16.5.2 Setting up a datasource using JAAS<br />
Setting up a datasoure using JAAS is done in the same manner as setting up a<br />
standard datasource (see 6.2.7, “Database connections” on page 194), but you<br />
must select a value for the Container-managed authentication alias.<br />
572 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 16-14 Enabling JAAS within a datasource<br />
16.6 Securing the <strong>IBM</strong> Agent Controller<br />
You will need to secure the <strong>IBM</strong> Agent Controller for a production environment.<br />
This is achieved by restricting access to the agent to certain hosts or addresses.<br />
You can restrict access using the Hosts setting in the serviceConfig.xml file in the<br />
/config directory.<br />
The default configuration is as follows:<br />
<br />
<br />
<br />
Chapter 16. Security 573
This configuration allows access to all hosts. To limit access, list the hosts and<br />
network mask that identify the addresses and use the Allow or Deny keywords.<br />
For example:<br />
<br />
<br />
<br />
<br />
<br />
This configuration will allow access from all machines in the 192.168.0.0 C-class<br />
network except 192.168.0.1. It will also allow access from the host “steamboat”.<br />
All other requests are denied.<br />
16.6.1 Implementing SSL for <strong>IBM</strong> Agent Controller communications<br />
When you install the application server component of <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express, the system is inspected for a copy of the Global Security<br />
ToolKit (GSK). If one is not already installed, a copy will be installed with Express.<br />
Express installs the GSK at the following locations:<br />
► Windows: C:\Program Files\<strong>IBM</strong>\GSK5<br />
► Linux: /usr/local/ibm/gsk5<br />
By default, SSL is not used between Studio and the agent.<br />
To turn on this function in Linux, do the following:<br />
cd /opt/<strong>IBM</strong>RAC/bin<br />
export JAVA_HOME=/opt/<strong>IBM</strong>/<strong>WebSphere</strong>/Express/App<strong>Server</strong>/java<br />
./RACSecurityOn.bat<br />
To turn on this function in Windows:<br />
1. Execute /bin/RACSecurityOn.bat on the application server. You<br />
will need to include the install path for <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express as part of the command:<br />
\bin\RACSecurityOn.bat <br />
(If you want to turn security off, use RACSecurityOff.bat.)<br />
2. The script will ask you to enter the directory path of the GSK. Once you enter<br />
the path, the RAC configuration file will be updated with a security stanza and<br />
RAC will be restarted.<br />
Figure 16-15 on page 575 shows an example of executing the command.<br />
574 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
C:\<strong>WebSphere</strong>\Express\RAC\bin>racsecurityon c:\websphere\express<br />
Turning RAC Security on<br />
GSK installed location: c:\program files\ibm\gsk5<br />
The <strong>IBM</strong> Agent Controller service was stopped successfully.<br />
The <strong>IBM</strong> Agent Controller service is starting.<br />
The <strong>IBM</strong> Agent Controller service was started successfully.<br />
RAC security now on, only users of this computer may access RAC<br />
Figure 16-15 Turning on RAC security<br />
Once security is turned on and RAC has been restarted, you will receive a logon<br />
prompt when you attempt to access the server. RAC authenticates against the<br />
operating system security so the user must be a valid user on the server<br />
operating system. On Windows, domain name passwords will not be<br />
authenticated. You must provide local user name and password pairs. An internal<br />
certificate is used so there is no need to obtain one.<br />
The security settings for RAC are found in /config/serviceconfig.xml.<br />
When you run RACSecurityOn, a new Security stanza will be added.<br />
Example 16-3 serviceconfig.xml<br />
<br />
<br />
<br />
The user definition elements define a single user with ANY being a wildcard for<br />
any user with a user ID on the host system. If you want to restrict access to<br />
specific users, you would need to define a <br />
element for each user (see Example 16-4).<br />
Example 16-4 Restricting access to specific users<br />
<br />
<br />
<br />
<br />
Chapter 16. Security 575
Enabling security when installing<br />
During the installation of the Agent Controller, you can choose to enable the<br />
communications security protocol. By enabling the security, you ensure that<br />
communication to the Agent Controller will be encrypted, and that all connections<br />
will be forced to authenticate using Secure Sockets Layer (SSL) technology. The<br />
SSL security protocol ensures elements such as data encryption, authentication,<br />
and authorization.<br />
To enable the communications security protocol during the installation process,<br />
follow these steps:<br />
1. From the Agent Controller InstallShield Wizard, click Enable Security<br />
(Recommended for Production Systems). Click the Next button.<br />
2. The Secure User Access window opens. Enter the user names that should<br />
be granted access to the Agent Controller. Click the Next button when<br />
finished.<br />
3. The Host List window opens. Choose the hosts that will be able to access the<br />
Agent Controller. Click the Next button when finished.<br />
After you have enabled (or disabled) the security, you can continue with the<br />
installation process.<br />
Note: Enabling the security is recommended. If, during the installation<br />
process, you choose to disable the security, communication to the Agent<br />
Controller will not be encrypted and access control will be limited to the<br />
defined host list.<br />
16.6.2 Importing a security certificate into the Workbench<br />
Security certificates are used during the authentication process to provide secure<br />
connections when using the Agent Controller. A security certificate is essentially<br />
a digital statement that confirms the identity of an entity (such as a person or a<br />
company). By using security certificates, you ensure that all connections using<br />
the Agent Controller will be forced to authenticate using Secure Sockets Layer<br />
(SSL) technology.<br />
To import a security certificate into the Workbench, follow these steps:<br />
1. From the Workbench, open the Preferences window by clicking the Windows<br />
menu item, and then by clicking Preferences.<br />
2. From the Preferences window, select Agent Controller from the left pane.<br />
576 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure 16-16 Agent contoller preferences<br />
3. To add a certificate, click Add and then locate the Security Certificate and<br />
specify an Alias name in the Add Certificate window. You may create more<br />
than one if required.<br />
Figure 16-17 Add certificate window<br />
4. Click Apply and then OK when you are finished.<br />
Chapter 16. Security 577
16.7 Using SSL with applications<br />
Three things are required for the use of SSL with applications.<br />
► The application must be coded to use SSL through the use of security taglibs<br />
or other programming techniques (not covered in this publication).<br />
► The server must be configured so SSL is supported on the ports the<br />
application uses for SSL.<br />
► A certificate must be obtained and stored for use by the server.<br />
Configuring the server ports for SSL<br />
The configuration of SSL for the server is done on the Ports tab of the Configure<br />
<strong>Server</strong> Screen in Studio Site Developer.<br />
To enable SSL:<br />
1. Select the Sever perspective and open the server configuration.<br />
2. Select the Ports tab.<br />
3. Click Add next to the HTTP transport list in the <strong>Server</strong> Settings section.<br />
Figure 16-18 HTTP Transport configuration<br />
4. Enter the port number and select the Enable SSL check box.<br />
5. Click OK.<br />
This will add a new port to your server. If the Enable SSL check box is checked,<br />
then this port will be used in a secure environment. Now the applications that are<br />
running on this port will be accessible using SSL only.<br />
Adding a certificate to your application server<br />
In order to use SSL you will need to get a certificate. These can be obtained from<br />
Certification authorities and service providers that provide security certificates.<br />
578 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
In order to use this certificate you need to add it to your <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express server configuration:<br />
1. Open the server configuration and select the Security tab.<br />
2. Under SSL Configuration Repertoires, click Add.<br />
Figure 16-19 Certificate configuration<br />
3. Enter the certificate information and click OK.<br />
4. Save your server configuration, republish, and restart the server.<br />
Chapter 16. Security 579
Note: For additional SSL information, please see <strong>IBM</strong> <strong>WebSphere</strong> V5.0<br />
Security <strong>WebSphere</strong> Handbook Series, SG24-6573<br />
16.8 For more information<br />
For information on <strong>WebSphere</strong> security, we recommend the following resources:<br />
► <strong>IBM</strong> <strong>WebSphere</strong> Version 5.0 Security <strong>WebSphere</strong> Handbook Series,<br />
SG24-6573<br />
► The sample application that comes with JAAS v1.0; you can download the<br />
extension from Sun’s Java site:<br />
http://java.sun.com/products/jaas<br />
580 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Appendix A. <strong>Application</strong> templates<br />
The Template <strong>Application</strong> feature provided with Studio Site Developer allows you<br />
to use a wizard to step you through the process of customizing a predefined<br />
application template. An application template is really the skeleton of an<br />
application. It includes the entire application and may be either fully configured or<br />
may have certain parts that remain to be specified. This enables users with<br />
minimal or no programming skills to quickly build a fully operational application<br />
based on simple wizard-guided settings.<br />
At the time of writing, Studio Site Developer V5.1 included four solution<br />
templates, two IT templates, and one tutorial template. Aside from these seven<br />
templates, the wizard also enables you to download additional templates from:<br />
http://www7b.software.ibm.com/wsdd/zones/studio/rad/<br />
A<br />
After the Template application wizard has been used, a Web project is added to<br />
the workbench that includes all the necessary JSPs, HTML pages, Java Beans,<br />
etc. to form a viable end-to-end Web application. All of the resources related to<br />
the project can be modified and deleted in the same manner as they would in a<br />
new Web project. You can also expand on the foundation of the Web project and<br />
added resources were required.<br />
© Copyright <strong>IBM</strong> Corp. 2003 581
Wizard<br />
The Template application wizard is comprised of two distinct display areas. The<br />
right side of the wizard displays the content area where the wizard prompts you<br />
to fill in the parameters required by the selected template. It also gives you the<br />
opportunity to enter parameters, labels, and Web page titles that control the<br />
functionality and look of the resulting application. The left side of the wizard<br />
displays the wizard roadmap. This roadmap presents a list of the tasks you need<br />
to perform in order to produce a viable application.<br />
Roadmap<br />
Figure A-1 Template application wizard<br />
Content area<br />
The roadmap provides visual cues as to your progress through the wizard. You<br />
can use the roadmap icons to see which tasks you have completed and what<br />
remains to be done. An arrow indicates your current position in the task<br />
sequence. You can return to a previously completed task of the roadmap by<br />
582 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
clicking the relevant icon. If you make changes that conflict with other task<br />
information you have already entered, the Template <strong>Application</strong> Wizard will<br />
display a message indicating the wizard pages where changes must be made.<br />
These pages will be visually marked with an error symbol on the roadmap.<br />
Below is a table describing the task icons that appear in the Template <strong>Application</strong><br />
Wizard roadmap.<br />
Table A-1 Template application wizard icons<br />
Icon Name Description<br />
Information Enter a project name,<br />
description, and author,<br />
and select a location for<br />
the generated<br />
application.<br />
Properties Specify aspects of the<br />
generated application,<br />
such as the type of<br />
generated code, style,<br />
and logo.<br />
Features Define features of the<br />
generated application,<br />
with the help of<br />
displayed feature<br />
descriptions.<br />
Database Connection Set database<br />
information and view the<br />
database requirements.<br />
Menus Section title for the<br />
menus of the generated<br />
application, which<br />
appear indented below<br />
this icon.<br />
Menu configuration pages View the menu structure<br />
presented on the Web<br />
pages and change the<br />
menu labels.<br />
Appendix A. <strong>Application</strong> templates 583
Icon Name Description<br />
Web Pages Section title for the Web<br />
pages of the generated<br />
application, which<br />
appear indented below<br />
this icon.<br />
Web content pages Set appearance and<br />
content for the<br />
generated application's<br />
Web pages.<br />
Additional Data Map fields that are used<br />
for application logic, but<br />
are not displayed on any<br />
Web page.<br />
Using the Template application wizard<br />
For this tutorial we are going to use the Resource Reservation application<br />
template provided in Studio Site Developer. The Resource Reservation template<br />
will generate an application that lets users reserve resources such as rooms,<br />
equipment, parking, and so forth. Users are prompted to reserve their selection<br />
for a specific date and time. Every reserved time slot is equal to one hour.<br />
1. Select File -> New -> Project from the main menu of the workbench. This<br />
displays the New Project dialog.<br />
2. From the left page of the dialog select Web and then select Template<br />
<strong>Application</strong> from the right pane.<br />
3. Click Next. The Template <strong>Application</strong> wizard is invoked.<br />
584 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Preview button<br />
Template folders<br />
Figure A-2 Template application wizard<br />
Template options<br />
The Templates page is comprised of three folders: Solution Templates, IT<br />
Templates, and Tutorial. Selecting a template folder displays different<br />
template application options. To see a preview of a template application select<br />
one of the template options and then click Preview .... For example, if we select the Self Service Insurance template<br />
option we can click Preview Self Service Insurance... to see a preview of the<br />
application within a browser.<br />
Appendix A. <strong>Application</strong> templates 585
Figure A-3 Template application preview<br />
If you want to see additional template applications click Download.... This<br />
requires Internet access. Once you click the button a browser opens and the<br />
RAD Technologies is displayed. Scroll to the bottom of the page and click<br />
Downloads. Click GA Templates to forward to a page that displays a list of<br />
template applications. Once you have located a template you wish to use,<br />
download the zip file to your local system. Close the browser. From the wizard<br />
click Add... and locate the zip that was just downloaded and click Open. The<br />
template application is added to an Imported Templates folder.<br />
586 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: Some templates have an associated database that you can download<br />
and use to map your data sources and fields for the template. Download this<br />
database and unzip it under the TemplateLibrary\Sample Data Sources<br />
directory. This directory is located in the default template library location<br />
specified in your RAD preferences (Window -> Preferences -> RAD -><br />
Template <strong>Application</strong>s). Make sure that you have run the Template Wizard at<br />
least once before unzipping this database to ensure that the template library<br />
exists in the location specified in your preferences.<br />
Figure A-4 Downloading templates<br />
4. Select the Solution Templates folder and then select the Resource<br />
Reservation template option.<br />
Appendix A. <strong>Application</strong> templates 587
Figure A-5 Template selection<br />
5. Click Next.<br />
6. On the <strong>Application</strong> Information page, specify the Project name or keep the<br />
default. You can also specify a Description and/or Author for the project. For<br />
this tutorial, we keep the default values. Notice the roadmap on the left side of<br />
the wizard. An arrow is placed beside your current location in the roadmap.<br />
588 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Note: If you make changes that conflict with other task information you have<br />
already entered, the wizard will display a message indicating the wizard pages<br />
where changes must be made. These pages will be visually marked with an<br />
error symbol of the roadmap.<br />
If there are no conflicts, the pages in the roadmap will be visually marked with<br />
a checkmark symbol once they are completed.<br />
Figure A-6 <strong>Application</strong> information page<br />
Note: At any point during the wizard, click Preview <strong>Application</strong>... to view the<br />
current look of the application. The preview will reflect the wizard<br />
customizations that have been specified.<br />
7. On the <strong>Application</strong> Properties page, you can specify the type of application<br />
generated. If the template has defined these features as adjustable, you can<br />
also choose a style and a logo that will determine the application's<br />
appearance. We keep the defaults for this tutorial.<br />
Appendix A. <strong>Application</strong> templates 589
Figure A-7 <strong>Application</strong> properties page<br />
8. Click Next.<br />
9. The <strong>Application</strong> Features page allows you to select the features that affect the<br />
structure and flow of the generated application.You can check any feature to<br />
see its description at the bottom of the page, and to see how it affects the<br />
structure of the application, as reflected in the roadmap at left. Check those<br />
features that you want to include in your application. This page will be slightly<br />
different for each template. We keep the defaults for this tutorial.<br />
590 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure A-8 <strong>Application</strong> features<br />
10.Click Next.<br />
11.The Database Connection page allows you to define the database to which<br />
your application is connected. Verify whether the database that is specified is<br />
the one you want to use. If you need to change the database connection, click<br />
Set Database... and define the connection parameters. To see the structure<br />
of the database click Database Requirements.... A window will open that<br />
displays a list of the tables and columns for the database. Click OK to close<br />
the window. We keep the defaults for this tutorial.<br />
Appendix A. <strong>Application</strong> templates 591
Figure A-9 Database connection page<br />
12.Click Next.<br />
13.The Menu Configuration page presents the menu (navigation bar) of the<br />
application and allows you to edit the labels of the menus presented on the<br />
various pages of the generated application. To edit the menu labels select the<br />
menu item and click Rename.... Enter in the label name and click OK. We<br />
keep the defaults for this tutorial.<br />
592 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure A-10 Menu configuration page<br />
Note: Aside from being able to preview the application you can also preview<br />
the individual web pages. To do this, click Preview Page... and then select the<br />
page that you wish to view. This option is only available in the Menu<br />
Configuration page and each of the Web Page Content pages.<br />
14.Click Next.<br />
15.The Web Page Content page allows you to edit adjustable data for the Web<br />
pages of your application. If adjustable, you can modify the title of the Web<br />
pages and the title of the Web pages' views. You can also edit the label, type,<br />
and order of the widgets in the Web page, as well as the mapping of the<br />
widgets to the tables and columns in your database. The various buttons are<br />
enabled only if that function is available for the selected Web page object.<br />
– Use Add to place additional widgets in your application.<br />
– Use Edit to change the settings for the type, label, table or column of each<br />
field. When editing the field properties, remember to replace items only<br />
with other compatible items.<br />
– Use Remove to remove a custom data element from the Web page<br />
(widgets predefined by the template cannot be removed).<br />
Appendix A. <strong>Application</strong> templates 593
– Up moves the widget up within the Web page, while Down moves the<br />
widget down within the Web page.<br />
Figure A-11 Web page content pages<br />
16.Click Next for each of the Web Page Content page as we are keeping the<br />
defaults for this tutorial.<br />
17.The Additional Data page allows you to map data fields that are used for the<br />
internal logic of the application, and are not displayed in the application's<br />
interface for user input or information. Depending on the features and<br />
properties you selected in previous tasks, these fields may or may not require<br />
configuration. To configure the fields click Edit.... We keep the defaults for this<br />
tutorial.<br />
594 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure A-12 Additional data page<br />
18.Click Finish. This saves your template customizations and then generates the<br />
code for the application. A notification window will be displayed indicating to<br />
you that the code was generated successfully. The window will ask if you<br />
would like to run the application on the server. Click Yes to run the application<br />
in a test server or click No to close the wizard. The Web project will be added<br />
to the workspace and will be displayed in any navigator view.<br />
Figure A-13 Project has been added to the workspace<br />
Appendix A. <strong>Application</strong> templates 595
596 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Appendix B. Updating Studio Site<br />
Developer<br />
This section demonstrates how to search for updates and how to install updates<br />
for <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express.<br />
Using the Update Manager<br />
B<br />
Note: If updating a remote server installation of <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express, please visit:<br />
http://www-3.ibm.com/software/webservers/appserv/express/support/<br />
This site will provide a listing of PTFs available for download. Follow the<br />
installation instructions provided with the PTF.<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express contains an Update Manager. The<br />
update manager can be used to discover, download, and install updated features<br />
and plug-ins from special Web-based update sites.<br />
The basic underlying mechanism of the update manager is simple:<br />
► The files for a feature or plug-in are always stored in a subdirectory whose<br />
name includes a version identifier (for example, 2.0.0).<br />
© Copyright <strong>IBM</strong> Corp. 2003 597
► Different versions of a feature or plug-in are always given different version<br />
identifiers, thereby ensuring that the multiple versions of the same feature or<br />
plug-in can co-exist on disk.<br />
► This means that installing or updating features and plug-ins requires adding<br />
more files, but never requires deleting or overwriting existing files.<br />
► Once the files are installed on the local computer, the new feature and plug-in<br />
versions are available to be configured.<br />
► The same installed base of files is therefore capable of supporting many<br />
different configurations simultaneously. Installing and upgrading an existing<br />
product are reduced to formulating a configuration incrementally newer than<br />
the current one.<br />
► Important configurations can be saved and restored to active service in the<br />
event of an unsuccessful upgrade.<br />
You can launch the update manager by selecting Help -> Software Updates -><br />
Update Manager from the menu bar. This opens the Install/Update Perspective.<br />
Note that you can also open the perspective Install/Update directly.<br />
Figure B-1 Update Manager<br />
598 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Install/update perspective<br />
The Install/Update perspective allows you to check to see whether there are<br />
updates for a product's existing features. Working with this perspective usually<br />
requires access to the Internet.<br />
Figure B-2 Install/Update perspective<br />
The Install/Update perspective contains these views:<br />
Install configuration<br />
This view allows you to manage your workspace configuration. The Current<br />
Configuration folder shows which local installation locations are part of the<br />
workspace configuration, and which features are installed in those locations. The<br />
Configuration History folder shows a history of changes made to your workspace<br />
configuration. The Saved Configurations folder show any configurations that<br />
were preserved.<br />
Appendix B. Updating Studio Site Developer 599
Figure B-3 Install configuration view<br />
Feature updates<br />
This view allows you to locate and install new features and feature updates.<br />
Selected Updates<br />
This view displays a list of all selected updates. Updates are added and removed<br />
from this list by checking or unchecking the Install by adding to the Selected<br />
Updates check box on the update preview pages.<br />
Figure B-4 Selected updates view<br />
If you right-click an update you can install it by selecting Process from the<br />
context menu. If you wish to install all of the updates in the view right-click inside<br />
the view and select Process All from the context menu.<br />
600 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Updating features<br />
Feature Search Results<br />
This view displays information about the available updates after a feature update<br />
search has been completed.<br />
Preview<br />
This view displays detailed information about the current active selection. Its<br />
content changes according to your selection.<br />
External preview<br />
The External Preview view, which is part of the Install/Update perspective, is an<br />
embedded browser used to display HTML information. This view is available only<br />
on Windows systems. In general, the External Preview is used when links are<br />
followed to HTML pages.<br />
There are two ways to update features using <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> -<br />
Express:<br />
► New updates feature<br />
► Feature updates view<br />
New updates feature<br />
To check to see whether there are updates for a product's existing features<br />
(requires Internet access):<br />
1. Click Help -> Software Updates -> New Updates. This will contact the Web<br />
sites associated with the product's features to discover what versions of those<br />
features are available. The potential upgrades are presented in an Available<br />
Updates page.<br />
2. Select the feature versions that you wish to upgrade, and click Next.<br />
3. Carefully review the license agreements for the upgraded features. If the<br />
terms of all these licenses are acceptable, check "I accept the terms in the<br />
license agreements." Do not proceed to download the features if the license<br />
terms are not acceptable.<br />
4. Feature versions can be digitally signed by the company that provides them.<br />
This allows the user to verify more easily that the features and plug-ins that<br />
are about to be downloaded and installed are coming from a trusted supplier.<br />
Click Install to allow the downloading and installing to proceed.<br />
5. Once all the features and plug-ins have been downloaded successfully and<br />
their files installed into the product on the local computer, a new configuration<br />
that incorporates these features and plug-ins will be formulated. Click Yes<br />
when asked to exit and restart the Workbench for the changes to take effect.<br />
Appendix B. Updating Studio Site Developer 601
Feature updates view<br />
The Feature updates view provides three different techniques for updating<br />
features. The view contains three standard folders. The Sites to Visit folder<br />
contains update sites pre-configured by the product you are using. The Available<br />
Updates is a built-in search results folder used for searching update sites. The<br />
My Computer folder is a file explorer that can be used to navigate to updates<br />
located in the file system.<br />
Figure B-5 Feature updates view<br />
Tip: When an update feature is displayed in the Preview view you can check<br />
the Install by adding to the Selected Updates check box to add the update<br />
to the Selected Updates view.<br />
Site to visit folder<br />
This folder contains updates sites preconfigured by the product you are using. By<br />
default there are three site bookmarks set:<br />
► <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express Discovery<br />
► <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express Discovery<br />
► <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express Fixes<br />
To check to see whether there are updates for a product's existing features<br />
(requires Internet access):<br />
1. Expand a site bookmark to locate feature updates.<br />
2. Click an update to open it in the Preview view<br />
602 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
.<br />
Figure B-6 Site to visit folder<br />
3. Click Install Now to install the update. The Feature Install wizard opens.<br />
4. The Feature Install wizard confirms the details of the feature you are about to<br />
install. Click Next.<br />
Appendix B. Updating Studio Site Developer 603
Figure B-7 Feature install wizard - 1<br />
5. Carefully review the license agreements for the upgraded features. If the<br />
terms of all these licenses are acceptable, check “I accept the terms in the<br />
license agreements”. Do not proceed to download the features if the license<br />
terms are not acceptable.<br />
604 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure B-8 Feature install wizard - 2<br />
6. If a feature selected for install include optional features, a page will show up<br />
allowing you to select whether you want them installed or not. Optional<br />
features typically carry functionality that is not essential for proper functioning<br />
of the main feature.<br />
7. The Install Location page controls where the new feature's files are to be<br />
installed on the local computer. Select the directory into which the product is<br />
installed and click Next (If the product is installed in a directory to which you<br />
do not have write access, you should contact your system administrator and<br />
get them to install this feature so that it will be generally available. The other<br />
option is to click Add and point to a directory to which you do have write<br />
access; however, features installed there are only available when using the<br />
current workspace.).<br />
Appendix B. Updating Studio Site Developer 605
Figure B-9 Feature install wizard - 3<br />
8. Feature versions can be digitally signed by the company that provides them.<br />
This allows you to verify more easily that the features and plug-ins that are<br />
about to be downloaded and installed are coming from a trusted supplier.<br />
9. Click Install to allow the downloading and installing to proceed.<br />
10.Once the new feature and plug-ins have been downloaded successfully and<br />
their files installed into the product on the local computer, a new configuration<br />
that incorporates these features and plug-ins will be formulated. Click Yes<br />
when asked to exit and restart the workbench for the changes to take effect.<br />
To add other new features at the same time before restarting, click No and<br />
repeat.<br />
You can also add site bookmarks by right-clicking the Site to visit folder and<br />
selecting New -> Site Bookmark.... This opens the New Site Bookmark dialog.<br />
Specify the Name and URL for the bookmark. You can also specify the type of<br />
bookmark as an Eclipse update site or a Web site. Lastly, you can specify which<br />
folder to add the bookmark to. If no value is entered the bookmark will be added<br />
to the root of the Feature updates view.<br />
606 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Figure B-10 Adding a site bookmark<br />
Available updates folder<br />
This feature is very similar to the new updates tool mentioned above. To check to<br />
see whether there are updates for a product's existing features (requires Internet<br />
access):<br />
1. Click the folder title to open the Available updates search window in the<br />
Preview view.<br />
Appendix B. Updating Studio Site Developer 607
Figure B-11 Available updates search page<br />
2. Specify your Query and Scope settings:<br />
Query settings<br />
Available Updates allows search for available updates to selected<br />
features.<br />
Regular Expression allows search for features using expression<br />
matching.<br />
Plug-ins in Features allows search for features containing specified<br />
plug-ins.<br />
Scope settings<br />
Include My Computer in search will cause the selected local roots to<br />
be searched for local update sites containing features<br />
Search sites in "Sites to Visit" folder will cause the preconfigured<br />
sites to be searched<br />
Search bookmarked sites will cause bookmarked sites to be<br />
searched<br />
Only include features applicable to this environment will only<br />
consider features that match the current runtime environment to be<br />
included in the results<br />
608 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
3. Once you have set your query and scope settings click Search Now to search<br />
for updates. Any updates that are found will be displayed in the Feature<br />
search results view.<br />
4. Click an item from the Feature search results view to open it in the Preview<br />
pane and then click Install Now to install the update using the Feature Install<br />
wizard. Follow steps 4 to 10 from “Site to visit folder” on page 602 to install the<br />
update.<br />
My computer folder<br />
This folder is a file explorer that can be used to navigate to updates located in the<br />
file system. This method is used if you previously dowloaded updates from the<br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express and/or <strong>WebSphere</strong> Studio Site<br />
Developer support Web sites:<br />
http://www-3.ibm.com/software/webservers/appserv/express/support/<br />
http://www-3.ibm.com/software/awdtools/studiositedev/support/<br />
Once you have download the update file(s), you receive a ZIP file. To install this<br />
update, you have to extract the ZIP file.<br />
Expand the My Computer tree to the folder where you have unzipped the<br />
package and click Install Now in the Preview view to open the Feature Install<br />
wizard. Follow steps 4 to 10 from “Site to visit folder” on page 602 to install the<br />
update.<br />
Appendix B. Updating Studio Site Developer 609
Figure B-12 My computer folder<br />
610 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
C<br />
Appendix C. Online Catalog application<br />
Throughout this publication we use the Online Catalog sample to illustrate the<br />
various features of <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express. The application is a<br />
simple one that provides a means of publishing an inventory of goods on the<br />
Web and allowing customers to place orders via e-mail or by phone. This is by no<br />
means a replacement for <strong>WebSphere</strong> Commerce applications, but simply a way<br />
for small businesses to make their products known to potential customers.<br />
The application will provide a simple interface for non-programmers to enter<br />
information. Certain items can be identified as feature items. Customers can<br />
browse the information and e-mail the company for information.<br />
The application will be generic enough to apply to a variety of businesses. For<br />
example:<br />
► A business that sells RVs can publish a current inventory of the campers on<br />
its lot.<br />
► A restaurant can publish a takeout menu and provide a call-in number or fax<br />
number.<br />
► A cleaning service can provide a list of services and prices.<br />
© Copyright <strong>IBM</strong> Corp. 2003 611
Online Catalog sample application overview<br />
Database architecture<br />
The Online Catalog application is a simplified shopping-cart application.<br />
Navigating through the application with a Web browser, users can view the<br />
catalog, search for products, request information, create and manage a wishlist,<br />
and submit the wishlist.<br />
From a lower-level perspective, we can outline the list of components that provide<br />
the aforementioned functionality:<br />
► A main application menu, which lists the options available to the user<br />
► A registration process where new users enter their details<br />
► A search mechanism, which provides shoppers with a fast means to find<br />
items of interest, based on a keyword description<br />
► A shopping cart, which lists the items currently selected by the user, and also<br />
provides editing functionality for the user to modify his choices<br />
► An order completion mechanism<br />
Persistent data from our sample application is maintained in database tables. In<br />
keeping with our intent to keep things simple, the tables were designed with a<br />
basic approach in mind, with columns clearly labeled and constraints kept to a<br />
minimum. One may notice that, in some places, the use of constraints and<br />
triggers might have been justified. However, in cases where implementing these<br />
features might have complicated the issue and distracted us from our initial<br />
purpose, we took a conscious decision to do away with them.<br />
User information was not stored directly in our application database. Since<br />
<strong>WebSphere</strong> provides functionality to store user profiles in a predesigned<br />
SALESAPP database, we decided to make use of this feature to simplify the<br />
implementation of an authentication mechanism and storage of user-related<br />
data.<br />
Important: The FeaturedItem.xst and db.properties files all contain the<br />
database connection parameters. If you are not using the same parameters<br />
we specified you must change the values in these files.<br />
Other types of data are stored in the following tables in a custom-designed<br />
database: CUSTOMERS, USERS, SHIPPING_ORDER, and ITEM.<br />
612 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
ITEM table<br />
The ITEM table contains the inventory items.<br />
Table C-1 ITEM table<br />
Column type Length Nullable Key<br />
ITEM_NUMBER character 5 N Y<br />
ITEM_SHORT_DESC varchar 50 Y N<br />
ITEM_LONG_DESC varchar 150 Y N<br />
QUANTITY integer Y N<br />
PRICE decimal 9,2 Y N<br />
SOTD_FLAG character 1 Y N<br />
CUSTOMER table<br />
The CUSTOMER table contains information about registered customers.<br />
Table C-2 CuSTOMER table<br />
Column type Length Nullable Key<br />
CUSTOMER_ID character 10 N Y<br />
CUSTOMER_NAME varchar 40 Y N<br />
ADDRESS varchar 40 Y N<br />
CITY varchar 40 Y N<br />
STATE character 2 Y N<br />
EMAIL_ADDRESS varchar 20 Y N<br />
PHONE character 10 Y N<br />
CC_TYPE character 2 Y N<br />
CC_NUMBER varchar 20 Y N<br />
ZIP character 5 Y N<br />
INTEREST1 character 1 Y N<br />
INTEREST2 character 1 Y N<br />
PASSWORD character 10 N N<br />
Appendix C. Online Catalog application 613
SHIPPING_ORDER table<br />
The SHIPPING_ORDER table contains orders submitted by customers.<br />
Table C-3 SHIPPING_ORDER table<br />
USERS table<br />
The USERS table contains users with administrative capabilities.<br />
Table C-4 USERS table<br />
<strong>Application</strong> components<br />
<strong>Application</strong> root<br />
Column type Length Nullable Key<br />
ORDER_NUMBER integer N Y<br />
CUSTOMER_ID character 10 N N<br />
ITEM_NUMBER character 5 N N<br />
QUANTITY smallint Y N<br />
SALE_PRICE decimal 9,2 Y N<br />
ORDER_DATE date Y N<br />
STATUS character 1 Y<br />
Column type Length Nullable Key<br />
USERNAME character 8 N Y<br />
PASSWORD character 8 N N<br />
The following sections give an overview of the Online Catalog application<br />
components.<br />
The index.html page is the entry point of the application and it is located in the<br />
WebContent folder. This page contains links to the other main components of the<br />
site. For additional information about this component please see “Adding HTML<br />
pages to the Online Catalog sample” on page 135.<br />
614 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Featured item<br />
Figure C-1 Web site diagram view of application root<br />
The Featured item component of the application is comprised of a servlet and<br />
XST file. The servlet takes information from the XST file and creates HTML<br />
output for the user. The output is a table that lists the feature items as indicated<br />
by the SOTD_FLAG field of the ITEMS table. The diagram below illustrates the<br />
flow of the different components in this process.<br />
Appendix C. Online Catalog application 615
Homepage<br />
XST file<br />
calls<br />
Servlet<br />
Figure C-2 Flow diagram for XML component of sample<br />
The table below lists the main files involved in this portion of the application.<br />
Table C-5 Featured item items<br />
ITEM table<br />
requests queries<br />
creates<br />
Item Folder/Package Description<br />
FeaturedItemXMLServlet.java featureditem This servlet is used to create<br />
the HTML output of the featured<br />
item list. It uses the query and<br />
database connection<br />
information supplied from the<br />
FeaturedItem.xst file.<br />
FeaturedItem.xst featured_item This file contains the query and<br />
database connection<br />
information used by the<br />
FeaturedItemXMLServlet<br />
servlet to create the featured<br />
item list.<br />
FeaturedItem.xsl featured_item Though this file is not physically<br />
used by the<br />
FeaturedItemXMLServlet<br />
servlet, the content within it was<br />
used to create the string within<br />
the servlet.<br />
616 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
XML and XSL strings<br />
transforms<br />
HTML string<br />
(output to user)
Site administration<br />
Note: For additional information about this component please see “Using XML<br />
in the Online Catalog sample” on page 332.<br />
Administrators can update the catalog by going through the Site administration<br />
option. This prompts a login. By default the application uses a simple login<br />
mechanism that requests the user ID and password, then compares that to<br />
entries in the SALESAPP database.<br />
Figure C-3 Web site diagram view of administration component<br />
The table below lists the main files involved in this portion of the application.<br />
Table C-6 Site administration items<br />
Item Folder/Package Description<br />
login.jsp administration This page is accessed from<br />
index.html, and it allows the<br />
user to log into the site<br />
administration main page by<br />
submitting a user ID and<br />
password to<br />
LoginServlet.java.<br />
LoginJSP.jsp administration This page verifies (from the<br />
SALESAPP database) the<br />
user ID and password values<br />
submitted from login.jsp. If<br />
the values are correct the<br />
user is forwarded to<br />
admin.html. If not, the user is<br />
redirected to login.jsp.<br />
Appendix C. Online Catalog application 617
Item Folder/Package Description<br />
admin.html administration This page has links to<br />
ModDelItem.jsp (Modify or<br />
Delete Item),<br />
AddNewItem.html (Add<br />
Item),<br />
CustomerMasterView.jsp<br />
(View Customers), and<br />
OrderMasterView.jsp (View<br />
Orders).<br />
AddNewItem.html administration This page is used to add a<br />
new item to the SALESAPP<br />
database using an HTML<br />
form. The user submits item<br />
information to<br />
AddNewItemProcess.jsp for<br />
processing. This page is<br />
accessed from admin.html.<br />
AddNewItemProcess.jsp administration This page takes the new item<br />
information from<br />
AddNewItem.html for<br />
processing. The data is first<br />
validated. If the data passes<br />
the validation it is submitted<br />
into the SALESAPP<br />
database. If the data does<br />
not pass validation, then the<br />
user is informed of the error<br />
and then sent back to the<br />
previous page.<br />
ModDelItem.jsp administration This page displays all the<br />
items from the SALESAPP<br />
database and gives the user<br />
the option to modify or delete<br />
the item. If the user clicks<br />
Modify for an item then the<br />
item information is sent to<br />
ModifyItem.jsp to be<br />
modified. If the user clicks<br />
Delete for an item, the item<br />
information is sent to<br />
DeleteItem.jsp to be deleted.<br />
This page is accessed from<br />
admin.html.<br />
618 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Item Folder/Package Description<br />
ModifyItem.jsp administration This page gets the item<br />
information from<br />
ModDelItem.jsp and allows<br />
the user to modify the item<br />
information. Once the user<br />
submits the page the<br />
information is sent to<br />
DoModifyItem.jsp for<br />
processing.<br />
DoModifyItem.jsp administration This page gets the item<br />
information from<br />
ModifyItem.jsp and updates<br />
the item in the SALESAPP<br />
database. The user is then<br />
forwarded back to<br />
ModDelItem.jsp.<br />
DeleteItem.jsp administration This page gets the item<br />
information from<br />
ModDelItem.jsp and allows<br />
the user to delete an item.<br />
Once the user submits the<br />
page the information is sent<br />
to DoDeleteItem.jsp for<br />
processing.<br />
DoDeleteItem.jsp administration This page gets the item<br />
information from<br />
DeleteItem.jsp and deletes<br />
the item from the SALESAPP<br />
database. The user is then<br />
forwarded back to<br />
ModDelItem.jsp.<br />
OrderMasterView.jsp administration This page is linked from<br />
admin.html. It is one of the<br />
site administration functions<br />
and it allows the user to view<br />
all the orders in the<br />
SALESAPP database.<br />
Appendix C. Online Catalog application 619
Catalog<br />
Item Folder/Package Description<br />
OrderDetailsView.jsp administration This page gives specific<br />
details on an order that was<br />
selected from<br />
OrderMasterView.jsp. As<br />
was the case in the master<br />
page, the data is retrieved<br />
from the SALESAPP<br />
database.<br />
CustomerMasterView.jsp administration This page is linked from<br />
admin.html. It is one of the<br />
site administration functions<br />
and it allows the user to view<br />
all the customers in the<br />
SALESAPP database.<br />
CustomerDetailsView.jsp administration This page gives specific<br />
details on a customer that<br />
was selected from<br />
CustomerMasterView.jsp. As<br />
was the case in the master<br />
page, the data is retrieved<br />
from the SALESAPP<br />
database.<br />
Users of the site can display the entire catalog or search for items in the catalog.<br />
If the user sees an item of interest, she can display the details of the item and<br />
then add it to a wishlist, if desired.<br />
Figure C-4 Web site diagram view of catalog component<br />
The table below lists the main files involved in this portion of the application.<br />
620 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Wishlist<br />
Table C-7 Catalog items<br />
Item Folder/Package Description<br />
catalog.html wishlist This page allows the user to view<br />
either a full list of the items in the<br />
SALESAPP database using<br />
ListCatalogMasterView.jsp, or the<br />
user can search the contents of<br />
the SALESAPP database by<br />
using SearchItemMasterView.jsp.<br />
This page is linked from the<br />
index.html page.<br />
ListCatalogMasterView.jsp wishlist This page lists all the items from<br />
the SALESAPP database. The<br />
user can select a specific item<br />
and view the details in<br />
ListCatalogDetailsView.jsp.<br />
ListCatalogDetailsView.jsp wishlist This page displays details on a<br />
specific item as per selected in<br />
ListCatalogMasterView.jsp. The<br />
user can add the viewed item to a<br />
wishlist if he wishes.<br />
SearchItemMasterView.jsp wishlist This page lists all the items from<br />
the SALESAPP database as per<br />
the search criteria submitted from<br />
catalog.html. The user can select<br />
a specific item and view the<br />
details in<br />
SearchItemDetailsView.jsp.<br />
SearchItemDetailsView.jsp wishlist This page displays details on a<br />
specific item as per selected in<br />
the SearchItemMasterView.jsp.<br />
The user can add the viewed item<br />
to a wishlist if he wishes.<br />
Once the user has added items to the wishlist, this list can be sent to the<br />
company by adding it to the Orders table in the SALESAPP database. In order to<br />
do this, the customer must be a registered user. Being registered means that an<br />
entry with customer information has been stored in the Customers table of the<br />
SALESAPP database.<br />
Appendix C. Online Catalog application 621
Note: To add items to the wishlist the HTTPSession class was used. For more<br />
information please see “HttpSession” on page 623.<br />
Figure C-5 Web site diagram view of wishlist component<br />
The table below lists the main files involved in this portion of the application.<br />
Table C-8 Wishlist items<br />
Item Folder/Package Description<br />
managewishlist.jsp wishlist This page is accessed from<br />
index.html and is used to display the<br />
contents of a user’s wishlist. The<br />
user can also remove the items from<br />
his wishlist if he wishes. It also<br />
allows the user to submit there<br />
wishlist if he is a current customer of<br />
the site, or he can register as a new<br />
customer.<br />
AddNewCustomer.html wishlist This page allows users to add a new<br />
customer to the SALESAPP<br />
database using an HTML form. The<br />
user submits customer information<br />
to NewCustomer.jsp for validation<br />
and processing.<br />
NewCustomer.jsp wishlist This page takes the customer<br />
information from<br />
AddNewCustomer.html for<br />
processing. The data is first<br />
validated. If the data passes the<br />
validation, it is submitted into the<br />
SALESAPP database. If the data<br />
does not pass validation then the<br />
user is informed of the error and<br />
then sent back to the previous page.<br />
622 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Item Folder/Package Description<br />
CurrentCustomer.jsp wishlist This page receives the user and<br />
password information from<br />
managewishlist.jsp. The page<br />
verifies that the user exists and<br />
submits the wishlist contents and<br />
customer information to the order<br />
table. Is also updates the quantity<br />
item table in the SALESAPP<br />
database and removes all the items<br />
from the wishlist. If the user does not<br />
exist then the user is informed of the<br />
error and is asked to try again or to<br />
register as a new customer using<br />
AddNewCustomer.html.<br />
HttpSession<br />
The HttpSession class supports built-in session tracking between the client and<br />
the server, by user. The Web container provides an implementation of the<br />
HTTPSession interface giving the application’s Web components access to the<br />
methods of the HTTPSession interface.<br />
The container recognizes a user by assigning him or her a unique session<br />
identifier. An object is associated with this identifier and the servlet may store,<br />
retrieve, and remove objects from this user session. The objects belong to a<br />
particular session and represent the session data for a particular user.<br />
Every time the client makes a request, the servlet gets the session object<br />
associated to him or her through the identifier (a new session is created if the<br />
user does not have any) and performs operations on it.<br />
The session identifiers are managed by the container which ensures that there is<br />
one session for each user. The API provides methods to destroy a session,<br />
typically used when a user logs out.<br />
The following shows an example of handling the HttpSession objects; this code<br />
can be included in the service method of a servlet.<br />
Example: C-1 Using the HttpSession interface<br />
HttpSession session = request.getSession(true);<br />
if (session.isNew()) {<br />
// perform actions for a new user<br />
...<br />
// set an attribute in the user session<br />
Appendix C. Online Catalog application 623
session.setAttribute("att1", o);<br />
...<br />
}<br />
else {<br />
// perform actions for a user identified<br />
...<br />
// retrieve an attribute from the session<br />
Object o = session.getAttribute("att1");<br />
...<br />
}<br />
There are two getSession methods in the HttpServletRequest interface which can<br />
provide the session to the servlet:<br />
► public HttpSession getSession(): This method returns the session associated<br />
with the request and creates one if there is not one already.<br />
► public HttpSession getSession(boolean create): This method does the same<br />
thing unless create is set to false. In that case, the method returns null if there<br />
is no session associated with the request.<br />
Here are some of the more useful methods of HttpSession:<br />
► public boolean isNew(): This method returns a value that indicates whether<br />
the session was just created or not.<br />
► public void setAttribute(String name, Object value): This method is used to<br />
add the object specified to the session, it will be retrieved by its name.<br />
► public Object getAttribute(String name): This method is called to retrieve an<br />
object by its name.<br />
► public void invalidate(): This method “destroys” a session. All the objects<br />
stored in the session are unbound.<br />
► public void removeAttribute(String name): This method is used to remove the<br />
name-value pair from the hashtable. In order to manage scarce server<br />
resources, it is important to remove state information that is no longer<br />
required.<br />
Session objects are stored on the server and provide the standard interface to<br />
manage sessions in applications. Session data objects (that is to say, the objects<br />
stored in the sessions) must implement the Serializable interface and they are<br />
stored on the server (within the HttpSession instances).<br />
624 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Information request<br />
Currency conversion<br />
The Web container recognizes a user with the identifier attached to its requests.<br />
This identifier is stored in the user’s browser and is the only piece of data stored<br />
in the client-side.<br />
The Java Servlet API supports two ways to associate multiple requests with a<br />
session: cookies and URL rewriting. In either case, the implementation details in<br />
the servlet are the same. The unique session ID is used to track multiple<br />
requests from the same client to the server, and this is what is passed as the<br />
URL or cookie parameter. The actual session object that we are tracking is<br />
maintained on the server.<br />
Customers can request additional information by sending an e-mail to the<br />
company.<br />
Figure C-6 Web site diagram view of information request component<br />
The table below lists the main files involved in this portion of the application.<br />
Table C-9 Information request items<br />
Item Folder/Package Description<br />
inforequest.html info_request This page allows users to request<br />
information pertaining to a product or<br />
products using a HTML form. The user<br />
submits the information to mailer.jsp for<br />
validation and processing. This page is<br />
accessed from index.html.<br />
mailer.jsp info_request This page receives the data passed<br />
from inforequest.html and e-mails it if it<br />
passes the validation.<br />
Note: For additional information about this component please see “Using a<br />
tag library in the Online Catalog sample” on page 301.<br />
The currency exchange option uses a Web service to convert amounts from one<br />
country’s currency to another’s.<br />
Appendix C. Online Catalog application 625
Figure C-7 Web site diagram view of currency conversion components<br />
The table below lists the main files involved in this portion of the application.<br />
Table C-10 Currency conversion items<br />
Item Folder/Package Description<br />
conversion.html currency_conversion This page is accessed<br />
from menu.html and is<br />
the main page used for<br />
the currency exchange<br />
Web service. This page<br />
is a frameset that is<br />
comprised of two<br />
frames, Input.jsp and<br />
Result.jsp. Input.jsp and<br />
Result.jsp are displayed<br />
in these frames<br />
respectively.<br />
Input.jsp currency_conversion This page allows the<br />
user to enter in an<br />
amount to be converted,<br />
a target, and a source<br />
country, and then<br />
passes the information<br />
to Result.jsp for<br />
processing.<br />
626 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Template and images<br />
Item Folder/Package Description<br />
Result.jsp currency_conversion This page takes the<br />
data that is passed from<br />
Input.jsp and calls a<br />
java proxy bean<br />
(CurrencyExchangePro<br />
xy.java), which makes a<br />
call to the Web service.<br />
The page then gets the<br />
result back from the<br />
bean and displays the<br />
converted amount by<br />
multiplying the original<br />
amount by the rate as<br />
retrieved from the bean.<br />
CurrencyExchangeProxy.java proxy.soap This JavaBean gets<br />
installed by the Web<br />
service and is called<br />
from Result.jsp. It uses<br />
the source and target<br />
country’s parameters<br />
from Input.jsp and<br />
makes the call to<br />
xmethods (Web service<br />
provider) Web service. If<br />
successful, it gets the<br />
conversion rate, which it<br />
passes back to<br />
Result.jsp.<br />
Note: For additional information about this component please see “Using Web<br />
services in the Online Catalog sample” on page 372.<br />
The themes folder in the WebContent directory of the project contains all the<br />
template and image files that are used throughout the application. For additional<br />
information about this component please see “Adding HTML pages to the Online<br />
Catalog sample” on page 135.<br />
Appendix C. Online Catalog application 627
Figure C-8 theme folder<br />
Deployment descriptor<br />
Numerous URL mappings have been set in the Web deployment descriptor. Click<br />
the entries of the Servlets and JSPs page to see the mappings. If these<br />
mappings are not set, you will see warnings in the Tasks view indicating that<br />
broken links exist. All of the database driven JSPs also have an initialization<br />
parameter set for the data source. The action entry also has initialization<br />
parameters set that are required for the Struts login component.<br />
Figure C-9 Servlets and JSPs page of deployment descriptor<br />
628 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Miscellaneous<br />
Servlet login<br />
There are two additional files included with the project that are used in the<br />
application. One of which are used in numerous locations throughout the<br />
application. The help.html file (located in WebContent) contains a legend of<br />
button images and descriptions. This file is linked from every list and detail<br />
database driven JSPs (for example, CustomerMasterView.jsp,<br />
SearchItemDetailsView.jsp, etc.). The second file (aboutus.html) is located in<br />
the corporate_information folder and is accessed from index.html. This file<br />
contains information about the company.<br />
The first step in the login process is login.html. This page collects the user name<br />
and password from the user and passes control to LoginServlet. LoginServlet<br />
captures the user name and password from the login.html form, verifies them<br />
using additional database connection wizards, and then forwards the user to the<br />
site administration selection page; admin.html.<br />
USER table of SALESAPP<br />
DBDriver.java<br />
DBConnection.java<br />
Database connection servlets<br />
login.html LoginServlet.java admin.html<br />
Figure C-10 Servlet login process - LogWriter.java not shown<br />
The table below lists the main files involved in this portion of the application.<br />
Appendix C. Online Catalog application 629
Table C-11 Servlet login items<br />
Item Folder/Package Description<br />
login.html servlet_login Provides the interface to login to the<br />
administration page.<br />
LoginServlet.java common This servlet gets the login data from<br />
login.html and verifies that the user<br />
and password exist in the<br />
SALESAPP database. If they are<br />
verified, the user is sent to<br />
admin.html (in the administration<br />
folder). If not, the user is sent to a<br />
servlet-generated page that asks the<br />
user to try logging in again. This is all<br />
done using the database connection<br />
established by DBConnection.java.<br />
LogWriter.java common This servlet outputs any errors that<br />
occur in the login process. If an<br />
invalid user or password is entered in<br />
LoginServlet.java, this servlet<br />
outputs it in a login file as specified in<br />
the util.properties file. This servlet<br />
will also output any database<br />
connection errors that occur in<br />
DBConnection.java or<br />
DBDriver.java.<br />
db.properties JavaSource This file contains the database<br />
connection information for<br />
DBDriver.java.<br />
util.properties JavaSource This file contains the path where log<br />
files are created by LogWriter.java.<br />
DBConnection.java common This servlet gets the database<br />
connection information from<br />
DBDriver.java and creates a<br />
connection to the SALESAPP<br />
database.<br />
DBDriver.java common This servlet gets the database<br />
connection information from the<br />
db.properties file.<br />
Note: For additional information about this component please see “Using<br />
servlets in the Online Catalog sample” on page 232.<br />
630 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Struts login<br />
Depending on the user name and password submitted, the user will see a<br />
different administrative maintenance page. The “read access” administrator<br />
(admin1) will see options to view customers and orders. The “write access”<br />
administrator (admin2) will see the options to view, edit, and delete products.<br />
Struts will be used to first validate the user name and password entries and then,<br />
depending on the submitted values, the action will forward the user to the<br />
appropriate page. A Struts action will also be used to log the user out of the<br />
administrative section of the site.<br />
LoginAction.java<br />
Figure C-11 Web diagram of Struts login component<br />
The table below lists the main files involved in this portion of the application.<br />
Table C-12 Struts login items<br />
LoginForm.java<br />
Item Folder/Package Description<br />
LogoutAction.java<br />
login.jsp struts_login Provides the interface to login to<br />
the administration page.<br />
admin1.jsp struts_login Displays the options to view a<br />
customer or an order.<br />
admin2.sjp struts_login Displays the options to view, edit,<br />
and delete products.<br />
Appendix C. Online Catalog application 631
Item Folder/Package Description<br />
LoginAction.java onlinecatalog.actions An instance of this class is used to<br />
authenticate the user. The user ID<br />
and password data is retrieved<br />
from the LoginForm.java class.<br />
Using forwards, this class<br />
determines which administration<br />
page to forward the user to.<br />
LoginForm.java onlinecatalog.forms An instance of this class is used to<br />
validate the user input parameters<br />
from the login.jsp page. If the<br />
validation is successful the login<br />
data is sent to the LoginAction<br />
class for authentication.<br />
LogoutAction.jsp onlinecatalog.actions An instance of this class is used to<br />
logout the user from the<br />
administration page and redirect<br />
to the login page.<br />
Note: For additional information about this component please see “Using<br />
Struts in a sample” on page 425.<br />
632 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Appendix D. Additional material<br />
This redbook refers to additional material that can be downloaded from the<br />
Internet as described below.<br />
Locating the Web material<br />
The Web material associated with this redbook is available in softcopy on the<br />
Internet from the <strong>IBM</strong> <strong>Redbooks</strong> Web server. Point your Web browser to:<br />
ftp://www.redbooks.ibm.com/redbooks/SG246555<br />
Alternatively, you can go to the <strong>IBM</strong> <strong>Redbooks</strong> Web site at:<br />
ibm.com/redbooks<br />
D<br />
Select Additional materials and open the directory that corresponds with the<br />
redbook form number, SG24-6555.<br />
© Copyright <strong>IBM</strong> Corp. 2003 633
Using the Web material<br />
The additional Web material that accompanies this redbook includes the<br />
following files. These files are included in the sg246555.zip file.<br />
Table D-1 <strong>Application</strong> files<br />
Filename Description<br />
OnlineCatalog.war Sample application Web module.<br />
.website-config This is the Web site diagram for the<br />
application.<br />
Step 1-RunCreateDB.cmd Creates the database used by the sample<br />
application.<br />
Step 2-RunSalesapp.cmd Creates and populates the tables used by<br />
the sample application.<br />
How to use the Web material<br />
Important: This sample was created during the redbook project as a way of<br />
discovering things about the product. It is provided for your convenience in<br />
case you want to browse through the code. It is a “living” sample, which means<br />
it may change over time. What you see in the downloaded sample may or may<br />
not be exactly the same as you see in the book. We can also almost<br />
guarantee that you will find bugs in the code that were not fixed during the<br />
project.<br />
After you have installed the Studio Site Developer component of <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> - Express, perform the steps described in the following<br />
section.<br />
Download the additional materials zip file<br />
To download the additional materials zip file:<br />
1. Download the zip file from the <strong>IBM</strong> <strong>Redbooks</strong> site and store it in a temporary<br />
directory. The application can be found by going to the following Web site:<br />
http://www.redbooks.ibm.com/abstracts/sg246555.html<br />
2. Select the Additional Material link.<br />
3. Create a subdirectory (folder) on your workstation and unzip the contents of<br />
the sg246555.zip file into this folder.<br />
634 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Import the sample<br />
The OnlineCatalog application is contained in OnlineCatalog.war. To view or run<br />
the sample you need to import it into Studio Site Developer.<br />
To import the sample:<br />
1. Start Studio Site Developer by selecting Start -> Programs -> <strong>IBM</strong><br />
<strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 -> Studio Site Developer<br />
on Windows, or by /opt/<strong>IBM</strong>/<strong>WebSphere</strong>Studio/wasexpress on Linux.<br />
2. Take the default workspace location.<br />
3. Open the Web perspective by selecting Window -> Open Perspective -><br />
Web.<br />
4. Select File -> Import.<br />
5. Select WAR file and click Next. This opens the Import dialog.<br />
6. Browse to the OnlineCatalog.war file you downloaded and click Open.<br />
7. Click New... to define the new project name. Enter OnlineCatalog. Check the<br />
Configure advanced options box and click Next.<br />
8. Enter OnlineCatalogEAR as the EAR project name. Verify that the J2EE level<br />
is 1.3.<br />
9. Click Next.<br />
10.On the Features page, check Add Struts support and JSP Tag Libraries<br />
and uncheck Default style sheet (CSS file).<br />
11.Click Finish. This creates the OnlineCatalog Web project and the<br />
OnlineCatalogEAR enterprise application project.<br />
12.Click Finish to complete the import process. The OnlineCatalog WAR file will<br />
be imported and added to the OnlineCatalogEAR application.<br />
Import the .website-config file<br />
The .website-config file is used to define the structure and navigation site and is<br />
placed in the root of the Web project.<br />
1. While still in the Web perspective, right-click the OnlineCatalog project and<br />
select Import... from the context menu. This opens the Import dialog.<br />
2. Select File system and then click Next.<br />
3. Locate the .website-config file and verify that the Into folder field is specified<br />
as OnlineCatalog.<br />
4. Click Finish. When prompted to overwrite the file click Yes.<br />
Appendix D. Additional material 635
Update the FeaturedItemXMLServlet servlet<br />
The FeaturedItemXMLSevlet.java file has the path to the FeaturedItem.xst file<br />
hardcoded. The current path in the servlet is set to the path of our test machine.<br />
You must change the path to point to your local machine.<br />
1. In the Web perspective, expand the JavaSource folder and then expand the<br />
featureditem package.<br />
2. Double-click FeaturedItemXMLServlet.java to open the servlet in the Java<br />
editor.<br />
3. Locate the line in the servlet that sets the xstFile variable and change the<br />
/Documents and Settings/bogers/My<br />
Documents/<strong>IBM</strong>/wasexpress51/workspace value to point to the<br />
workspace path on your local machine.<br />
4. Save your changes and close the editor.<br />
Set up the database<br />
The sample uses a DB2 database called SALESAPP. If you do not have DB2, a<br />
development copy is supplied with <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express.<br />
1. Install DB2. During the installation you will be asked to provide a name and<br />
password for the administrator. Use db2admin for both the name and<br />
password. This user will be created for you on the operating system.<br />
Note: If you use a user ID and password other than db2admin, you may<br />
run into problems. These are assumed several places in the application. If<br />
you use something else, be sure to change the dbconn.jspinc,<br />
FeaturedItem.xst, and db.properties files in the application.<br />
By default, the db2java.zip file does not support the JDBC 2.0 specification.<br />
You need to open the sqllib\java12 folder and execute usejdbc2.bat to copy<br />
the correct drivers to the zip file.<br />
2. Open a command window and change to the directory where you unzipped<br />
the additional materials file.<br />
3. Execute Step 1-RunCreateDB.cmd.<br />
4. Open the DB2 Control Center. Right click the SALESAPP database and<br />
select Authorities.<br />
5. Click Add User.<br />
6. Select the DB2ADMIN user and click OK.<br />
7. Select (highlight) DB2ADMIN in the list of users and click Grant All.<br />
8. Close the Control Center.<br />
636 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
9. Execute Step 2 -RunSalesapp.cmd.<br />
Create the test server environment<br />
To create the test server environment:<br />
1. In the Web perspective, open the <strong>Server</strong>s view.<br />
2. Right-click in the view and select New -> <strong>Server</strong> and <strong>Server</strong> Configuration.<br />
3. Enter a <strong>Server</strong> name (LocalTest<strong>Server</strong>, for example) and select the Express<br />
Test Environment option under <strong>WebSphere</strong> version 5.0.<br />
4. Click Finish.<br />
Configure a data source<br />
The JSPs used within the Online Catalog sample use a data source for all<br />
database connections. To setup a data source in Studio Site Developer:<br />
1. Open the <strong>Server</strong> perspective.<br />
2. From the <strong>Server</strong> Configuration view, right-click the <strong>WebSphere</strong> Express V5.0<br />
Test Environment server and select Open from the context menu. This opens<br />
the server configuration editor.<br />
3. Click the Data source tab. The Data sources page is displayed.<br />
4. Click Add... beside the JDBC provider list table. The Create a JDBC Provider<br />
dialog opens.<br />
5. Select <strong>IBM</strong> DB2 from the Database type select box and then select DB2<br />
JDBC Provider from the JDBC provider type select box.<br />
6. Click Next.<br />
7. Enter the value DB2 Driver in the Name field.<br />
8. Click Finish. The JDBC provider is added to the list box.<br />
9. Select the DB2 Driver entry from the JDBC provider list and then click Add...<br />
beside the Data source defined in the JDBC provider selected above<br />
table. The Create a Data Source dialog opens.<br />
10.Verify the DB2 Legacy CLI-based Type 2 JDBC Driver is selected as the<br />
JDBC provider type and verify that the Version 5.0 data source radio button<br />
is selected.<br />
11.Click Next.<br />
12.Enter SALESAPP in the Name field.<br />
13.Enter jdbc/salesapp in the JNDI name field.<br />
14.Click Next.<br />
Appendix D. Additional material 637
15.On the Create a Resource Properties page select the databaseName<br />
resource property and enter the value salesapp.<br />
16.Click Finish. The data source has now been added.<br />
17.Save the server configuration. Leave the configuration editor open as it is<br />
required for the next step.<br />
Enable JAAS authentication<br />
To enable JAAS authentication:<br />
1. With the server configuration editor still open click the Security tab. The<br />
Security Options page is displayed.<br />
2. Click Add... beside the JAAS Authentication Entries table. The Add JAAS<br />
Authentication Entry dialog is displayed.<br />
3. For the Alias, User ID, and Password fields enter the values SALESAPPJAAS,<br />
db2admin, and db2admin, respectively.<br />
4. Click OK. The JAAS entry is added.<br />
5. Click the Data source tab to display the Data sources page.<br />
6. Select the SALESAPP entry from the Data source defined in the JDBC<br />
provider selected above table and click Edit.... The Modify Data Source<br />
dialog opens.<br />
7. From the Container-managed authentication alias drop-down box, select<br />
SALESAPPJAAS.<br />
8. Click Finish. JAAS authentication has now been added to the SALESAPP<br />
data source.<br />
9. Save the server configuration.<br />
10.Close the server configuration editor.<br />
PUBLISH the sample<br />
To publish the sample:<br />
1. Select the server (LocalTest<strong>Server</strong>) in the <strong>Server</strong>s view, right-click, and select<br />
Add and remove projects.<br />
2. Select OnlineCatalogEAR from the Available Projects list and click Add.<br />
3. Click Finish.<br />
4. Select the server in the <strong>Server</strong> view, right-click, and select Control -><br />
Publish.<br />
638 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Start the server<br />
To start the server, select the server in the <strong>Server</strong> view, right-click, and select<br />
Start.<br />
Run the application<br />
To run the application:<br />
1. Switch the top left view back to the Project Navigator view.<br />
2. Find the OnlineCatalog Web project, right-click, and select Run on <strong>Server</strong>.<br />
3. If you select the Site Administration link, use admin as both the user ID and<br />
password.<br />
Appendix D. Additional material 639
640 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Related publications<br />
<strong>IBM</strong> <strong>Redbooks</strong><br />
The publications listed in this section are considered particularly suitable for a<br />
more detailed discussion of the topics covered in this redbook.<br />
For information on ordering these publications, see “How to get <strong>IBM</strong> <strong>Redbooks</strong>”<br />
on page 645.<br />
► <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express: A Development Example for New<br />
Developers, SG24-6301<br />
► <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.1 Administrator Handbook,<br />
SG24-6976<br />
► Migrating <strong>Application</strong>s from <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> Standard<br />
Edition to <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express Version 5, REDP3618<br />
► Migrating to <strong>WebSphere</strong> Version 5.0: An End-to-End Migration Guide,<br />
SG24-6910<br />
► <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> V5.0 System Management and<br />
Configuration, SG24-6195<br />
► <strong>IBM</strong> Framework for e-Business: Technology, Solution, and Design Overview<br />
SG24-6248<br />
► <strong>IBM</strong> <strong>WebSphere</strong> Version 5.0 Security <strong>WebSphere</strong> Handbook Series,<br />
SG24-6573<br />
► Servlet and JSP Programming with <strong>IBM</strong> <strong>WebSphere</strong> Studio and VisualAge for<br />
Java, SG24-5755<br />
► The XML Files: Development of XML/XSL <strong>Application</strong>s Using <strong>WebSphere</strong><br />
Studio Version 5, SG24-6586<br />
► <strong>WebSphere</strong> Version 5 Web Services Handbook, SG24-6891<br />
► <strong>WebSphere</strong> Studio <strong>Application</strong> Developer Version 5 Programming Guide,<br />
SG24-6957<br />
© Copyright <strong>IBM</strong> Corp. 2003 641
Other resources<br />
These publications are also relevant as further information sources:<br />
► Information roadmap for <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express<br />
http://www7b.boulder.ibm.com/wsdd/zones/was/roadmaps/express/<br />
► Apache Struts and VisualAge for Java, Part 1: Building Web-based<br />
<strong>Application</strong>s using Apache Struts, found in the VisualAge for Java zone of<br />
<strong>IBM</strong> <strong>WebSphere</strong> Developer Domain at (search on Struts)<br />
http://www7b.software.ibm.com/wsdd/<br />
► Apache Struts and VisualAge for Java, Part 2: Using Struts in VisualAge for<br />
Java 3.5.2 and 3.5.3 found in the VisualAge for Java zone of <strong>IBM</strong> <strong>WebSphere</strong><br />
Developer Domain (search on Struts)<br />
http://www7b.software.ibm.com/wsdd/<br />
► Core Servlets and Java<strong>Server</strong> Pages, ISBN 0-13-089340-4<br />
► Go-ForIt Chronicles, Part 19: Struttin' your stuff with <strong>WebSphere</strong> Studio<br />
tutorial from <strong>IBM</strong> DeveloperWorks<br />
http://www.ibm.com/developerworks/<br />
► J2EE Class Loading Demystified at:<br />
http://www7b.boulder.ibm.com/wsdd/library/techarticles/0112_deboer/deboer.h<br />
tml<br />
► SAMS Teach Yourself Java2 in 21 Days, 2nd Edition, ISBN 0-672-31958-6<br />
► Understanding Java<strong>Server</strong> Pages Model 2 Architecture<br />
http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html<br />
► Web service invocation sans SOAP<br />
Referenced Web sites<br />
http://www-106.ibm.com/developerworks/webservices/library/ws-wsif.html<br />
These Web sites are also relevant as further information sources:<br />
► akarta tag library information<br />
http://jakarta.apache.org/taglibs/index.html<br />
► Apache Jakarta Project<br />
http://jakarta.apache.org<br />
► Apache Jakarta Project Struts home page<br />
http://jakarta.apache.org/struts<br />
642 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
► Apache Jakarta Project taglib home page<br />
http://jakarta.apache.org/taglibs<br />
► Coldbeans Software Web site for Net presentations<br />
http://coldjava.hypermart.net<br />
► CVS home page<br />
http://www.cvshome.org<br />
► CVS NT <strong>Server</strong> download<br />
http://www.cvsnt.com<br />
► <strong>IBM</strong> DB2 XML Extender library<br />
http://www.ibm.com/software/data/db2/extenders/xmlext/library.html<br />
► <strong>IBM</strong> DeveloperWorks<br />
http://www.ibm.com/developerworks/<br />
► <strong>IBM</strong> developerWorks BSF project<br />
http://oss.software.ibm.com/developerworks/projects/bsf<br />
► <strong>IBM</strong> Patterns for e-business<br />
http://www.ibm.com/developerworks/patterns<br />
► <strong>IBM</strong> Web Services and UDDI home page<br />
http://www.ibm.com/services/uddi<br />
► <strong>IBM</strong> Web Services home page<br />
http://www-3.ibm.com/software/solutions/webservices/<br />
► <strong>IBM</strong> Web Services ToolKit<br />
http://www.ibm.com/software/solutions/webservices/wstk-info.html<br />
► <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express home page<br />
http://www-3.ibm.com/software/webservers/appserv/express/<br />
► <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express support page<br />
http://www.ibm.com/software/webservers/appserv/express/support.html<br />
► <strong>IBM</strong> <strong>WebSphere</strong> Developer Domain<br />
http://www7b.software.ibm.com/wsdd/<br />
► J2EE 1.3 specification<br />
http://java.sun.com/j2ee/1.3/docs/<br />
► J2EE Class Loading Demystified<br />
http://www7b.boulder.ibm.com/wsdd/library/techarticles/0112_deboer/deboer.h<br />
tml<br />
Related publications 643
► Java Authentication and Authorization Service (JAAS) at Sun’s Java site<br />
http://java.sun.com/products/jaas<br />
► Java Servlet 2.3 specification<br />
http://java.sun.com/products/servlet/<br />
► <br />
http://jsptags.com<br />
► MagicDraw home page<br />
http://www.magicdraw.com<br />
► Mailer taglib documentation<br />
http://jakarta.apache.org/taglibs/doc/mailer-doc/mailer-1.0/index.html<br />
► Object Management Group (OMG) home page<br />
http://www.omg.org<br />
► Rational home page<br />
http://www.rational.com<br />
► Tigris.org Open Source Software Engineering ArgoUML project<br />
http://argouml.tigris.org<br />
► UDDI.org home page<br />
http://www.uddi.org<br />
► Understanding Java<strong>Server</strong> Pages Model 2 architecture<br />
http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html<br />
► WSDL 1.1 specification<br />
http://www.w3.org/TR/wsdl<br />
► WSIF information<br />
http://www-106.ibm.com/developerworks/webservices/library/ws-wsif.html<br />
► XMethods home page<br />
http://www.xmethods.net<br />
► XML Schema home page at the W3C Architecture Domain<br />
http://www.w3.org/XML/Schema<br />
► XML schema layout<br />
http://www.uddi.org/schema/uddi_v1.xsd<br />
644 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
How to get <strong>IBM</strong> <strong>Redbooks</strong><br />
You can order hardcopy <strong>Redbooks</strong>, as well as view, download, or search for<br />
<strong>Redbooks</strong> at the following Web site:<br />
ibm.com/redbooks<br />
You can also download additional materials (code samples or diskette/CD-ROM<br />
images) from that site.<br />
<strong>IBM</strong> <strong>Redbooks</strong> collections<br />
<strong>Redbooks</strong> are also available on CD-ROMs. Click the CD-ROMs button on the<br />
<strong>Redbooks</strong> Web site for information about all the CD-ROMs offered, as well as<br />
updates and formats.<br />
Related publications 645
646 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
Index<br />
Symbols<br />
283–284<br />
Numerics<br />
404 error 494–495<br />
500 error 495–496, 500<br />
A<br />
access locators 366<br />
action 406<br />
action class 388, 406, 444, 447, 452<br />
action form 452<br />
action mapping 389, 400–401, 404, 406, 408–409,<br />
430<br />
action mappings 423<br />
action object 385<br />
action servlet 387–388<br />
ActionErrors 453<br />
ActionForm 386<br />
ActionForm class 388–389, 412–413<br />
ActionForm subclass 415<br />
ActionForward 453<br />
ActionServlet 452–453<br />
Add External JARS 197<br />
animated GIF 128<br />
AnimatedGif Designer 129–130<br />
animation 128, 132–133<br />
Apache<br />
Software Foundation 384<br />
applet 60<br />
application 33<br />
design 18<br />
object variable 246<br />
running 483<br />
scope 247<br />
application client module 58, 65<br />
application.xml 58<br />
<strong>Application</strong>Resources.properties 420, 432, 435,<br />
444<br />
attributes<br />
animated GIF 129<br />
autoFlush 249<br />
buffer 249<br />
contentType 249<br />
DTD 313, 323<br />
errorPage 249<br />
extends 248<br />
history 46<br />
image 119<br />
import 249<br />
info 249<br />
isErrorPage 249<br />
isThreadSafe 249<br />
JSP page directive 248<br />
language 248<br />
link 118<br />
quality of service 361<br />
schema 316<br />
servlet 219<br />
session 298<br />
table 117<br />
tag library 283, 294, 297–298, 302<br />
tModel 364<br />
view 80<br />
XML 310<br />
authentication 552–553, 555–556, 558, 563–564,<br />
569–570<br />
authorization 552, 556<br />
autoFlush attribute 249<br />
B<br />
basic authentication 553<br />
bean 60<br />
Bean Scripting Framework (BSF) 32<br />
BeanInfo class 280<br />
binding<br />
template 363<br />
branch 518, 524–526, 529–530, 532–533,<br />
535–541, 544–545<br />
comparing resources 545<br />
creating 537<br />
merging 541<br />
breakpoint 504–505, 507, 510<br />
condition 506<br />
properties 505<br />
© Copyright <strong>IBM</strong> Corp. 2003 647
oker 357<br />
BSF 32<br />
buffer attribute 249<br />
business<br />
entity 363<br />
service 363<br />
button 119, 124<br />
C<br />
canvas 123–125, 128<br />
CDATA section 311<br />
class<br />
HttpServletRequest 64, 218, 624<br />
HttpServletResponse 218<br />
HttpSession 623–624<br />
RequestDispatcher 256<br />
Servlet 243<br />
ServletConfig 219<br />
ServletContext 64, 219<br />
ServletRequest 218<br />
ServletResponse 218<br />
TagSupport 281<br />
classes directory 61, 74<br />
classloader 217, 485–486<br />
ClassNotFoundException 486<br />
classpath 481, 483, 485–487<br />
clip art 124<br />
Cloudscape 197, 200<br />
CMP 207<br />
color 83, 187–188<br />
WebArt Designer 126<br />
comment<br />
XML 311<br />
commit 517, 524–527, 531–533, 536–538, 541,<br />
544, 549<br />
compare<br />
three-way 545<br />
two-way 545<br />
complex data type 316<br />
component-managed authentication alias 207<br />
Concurrent Versions System (see CVS)<br />
condition<br />
breakpoint 506<br />
config 33<br />
object variable 246<br />
constraint 558, 560, 564, 569<br />
content assist 259, 329<br />
contentType attribute 249<br />
context menu 401, 403<br />
context path 64<br />
context root 69<br />
controller 220–221, 278<br />
MVC 31<br />
cookies 485<br />
CSS 120, 186–187<br />
CSS Designer 120<br />
CVS<br />
team development 515<br />
CVS Ignore 549<br />
648 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
D<br />
DAD 369<br />
DADX 369<br />
group 369<br />
Data perspective<br />
DB output view 157<br />
data source 154–156, 184–185, 194, 197–198,<br />
200–201, 203–204, 470, 482, 485<br />
componentmanaged authentication alias 207<br />
version 4 vs. version 5 205<br />
version 5 204<br />
database<br />
building SQL expressions 182<br />
connecting Studio to 159<br />
create DB2 158<br />
create Oracle 158<br />
creating columns 164<br />
creating tables 164, 166<br />
creating Web pages to access 174<br />
defining SQL conditions 181<br />
design 37<br />
import design into Studio 162<br />
key column 168<br />
reconnect 163<br />
schema 163–164, 166, 169<br />
databases directory 163, 166<br />
DataDirect Connect JDBC driver 162<br />
datatypes 39<br />
DB2 158, 169, 204, 477, 485<br />
DB2 App Driver 161<br />
DB2 XML Extender 320, 643<br />
DB2_JDBC_DRIVER_PATH 209, 485<br />
db2java.zip 203, 636<br />
dba 158<br />
DDL 155, 169–170<br />
executing 171
debugger 507, 509<br />
declarations 252<br />
declarative security 557<br />
deployment descriptor 65, 211, 286, 292, 555,<br />
558–559, 565<br />
application.xml 58<br />
created by wizard 65<br />
enterprise application 58, 72<br />
format 59<br />
servlet entry 269<br />
servlet initialization parameters 195<br />
Web application 61<br />
Web module 61–62<br />
web.xml 61<br />
welcome pages 135<br />
document type definition (see DTD)<br />
driver class 483<br />
driver manager 154, 194, 196–197<br />
DTD 283, 313, 315, 320–323, 325, 327, 329<br />
DynaActionForm 399, 413<br />
dynaform 399, 413<br />
E<br />
EAR file 58<br />
editor 49<br />
file associations 49<br />
editor marker bar 498, 505<br />
EJB module 58<br />
not supported in Express 58<br />
element<br />
XML 310<br />
e-mail 302<br />
Enable Hit Count 506<br />
encoding 362<br />
enterprise application 57–58, 220, 468, 481, 558<br />
enterprise application module 57<br />
enterprise application project 57<br />
creating 65<br />
Enterprise Information System (EIS) 20<br />
entity<br />
reference 311<br />
envelope 361<br />
error page 186, 555<br />
errorPage attribute 249<br />
EVAL_PAGE 282<br />
exception 33<br />
object variable 246<br />
expressions 252–253<br />
extends attribute 248<br />
eXtensible Markup Language (see also XML) 35,<br />
309<br />
F<br />
facade 30<br />
fast view 50–52, 54<br />
file transfer 478, 480–481<br />
filter<br />
limiting database schemas and tables 161<br />
form 119<br />
form bean 385–386, 399–401, 404, 408–409,<br />
412–415, 423<br />
form bean mapping 412–413<br />
form bean scope 408<br />
form-based authentication 553–554, 568<br />
formBean class 424<br />
forward tag 256<br />
frame 129<br />
animated GIFs 129, 133<br />
attribute 129<br />
comment 129<br />
image 129<br />
frameset 115, 118<br />
framesets 112, 114<br />
free-form surface 399<br />
front controller 176–177, 186–187<br />
FTP 479, 485<br />
G<br />
GET 563<br />
get method 412<br />
global classpath 486<br />
global security 558, 566<br />
grant 158<br />
GSK 574<br />
H<br />
HEAD 537<br />
help 55–56<br />
infopops 55<br />
online 54<br />
synchronize navigation 56<br />
history 515, 517, 525<br />
local 530, 544–545<br />
resource 527, 540, 542<br />
hit count 506<br />
Index 649
host variable 184, 187<br />
HTML 60<br />
creating pages 135<br />
HTTP 1.0 218<br />
HTTP request 216<br />
HttpServletRequest 254, 568<br />
HTTPSession 623<br />
HttpSession 298, 623–624<br />
I<br />
<strong>IBM</strong> Agent Controller 476–477, 491, 573<br />
image 60, 122, 127<br />
adding 118<br />
adding to animated GIF 131<br />
building with WebArt Designer 124<br />
map 118<br />
implicit object variables 254<br />
import attribute 249<br />
include directive 250<br />
include tag 255<br />
index 38<br />
info attribute 249<br />
input field 119<br />
installableApps 490<br />
interface 362<br />
isErrorPage attribute 249<br />
isThreadSafe attribute 249<br />
J<br />
j_password 555<br />
j_security_check 554–555<br />
j_username 555<br />
J2EE Publishing server 465<br />
JAAS 207, 470, 482, 570<br />
JAR 60<br />
Java build path 486<br />
Java Native Directory Interface (see JNDI)<br />
Java package 176<br />
Java scriptlets 34<br />
Java Source directory 73, 233<br />
java.lang.* 249<br />
JavaScript 32, 242<br />
javax.servlet.* 249<br />
javax.servlet.http.* 249<br />
javax.servlet.jsp.* 249<br />
JDBC 2.0 Standard Extension API 154<br />
JDBC driver 483<br />
JDBC driver class 161, 196–197<br />
650 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
JDBC overview 154<br />
JDBC provider 156, 196, 200–202<br />
JNDI 62, 155, 196, 206, 278–279, 485<br />
JNDI name 185, 207<br />
JSP<br />
actions 246<br />
directives 246, 248<br />
elements 246<br />
expressions 253<br />
forward 254<br />
getProperty 254<br />
include 254<br />
include directive 251<br />
overview 242<br />
page directive 250<br />
param 254<br />
plugin 254<br />
request phase 243–244<br />
root 245<br />
scripting elements 246, 252<br />
setProperty 254<br />
syntax 244<br />
tags 250<br />
translation phase 243, 250<br />
useBean 254<br />
XML syntax 252<br />
JVM 486<br />
JVM arguments 485<br />
K<br />
key<br />
foreign 169<br />
primary 168<br />
L<br />
language attribute 248<br />
lib directory 61, 74<br />
Libraries directory 74<br />
link<br />
adding 117<br />
image 118<br />
text 117<br />
local history 45–46<br />
comparing with 45<br />
log file 219<br />
logos 124
M<br />
merge 517, 532–533, 536–537, 541–542, 548<br />
branches 541<br />
from a stream 541<br />
message<br />
J2CA0122I 211<br />
SOAP 361<br />
META-INF 286, 559<br />
META-INF directory 74<br />
methods<br />
destroy() 218<br />
doEndTag 282<br />
endTag() 281<br />
forward() 256<br />
getAttribute() 247<br />
getRemoteUser() 568–569<br />
getServletConfig 219<br />
getServletContext() 219<br />
getSession 624<br />
getUserPrincipal() 569<br />
include() 256<br />
init() 217<br />
invalidate 624<br />
isNew 624<br />
isUserInRole() 568<br />
jspService() 253<br />
removeAttribute 624<br />
service 623<br />
service() 217–218<br />
setAttribute 624<br />
setAttribute() 247<br />
Microsoft SQL <strong>Server</strong> 158, 162<br />
MIME 462<br />
model 30<br />
Model 1 architecture 26, 220<br />
Model 2 architecture 26–27, 220<br />
Model-View-Controller (see MVC)<br />
MQSeries 361<br />
MVC 27, 36, 278, 384–385<br />
controller 31<br />
model 30<br />
pattern 32<br />
view 31<br />
N<br />
namespace 314–315, 318<br />
XML 314<br />
native path 202<br />
navigation bar 96, 104–105<br />
navigation candidate 151, 452<br />
navigation root 151<br />
navigation trail 106<br />
normalization 37<br />
O<br />
object scope 247<br />
object stack area 125<br />
operating system support 4<br />
Oracle 158, 160–161<br />
connecting Studio to 161<br />
create a user 158<br />
defining a data source 211<br />
defining JDBC provider 211<br />
out 33<br />
object variable 246<br />
P<br />
page 33<br />
object variable 246<br />
scope 247<br />
Page Designer 498<br />
page directive 248, 256<br />
page-centric 26<br />
PageContext 298<br />
object variable 246<br />
pageContext<br />
JavaScript 33<br />
param tag 255<br />
pattern<br />
MVC 28<br />
Patterns for e-business 21<br />
perspective 50<br />
customize 52<br />
CVS Repository 49<br />
CVS Repository Exploring 519, 525–527, 538<br />
Data 49, 159<br />
data 156<br />
Debug 500–501<br />
definition 47<br />
J2EE 50<br />
performance 50<br />
preferences 53<br />
Resource 549<br />
<strong>Server</strong> 47, 49, 455, 459–460, 466, 480, 487,<br />
567<br />
Web 47, 49, 66, 78–79, 175, 200, 233, 266,<br />
Index 651
460, 466, 522, 527, 529, 540–541<br />
XML 49, 320<br />
photo frames 124<br />
plug-in 423<br />
port 467, 476, 481, 483, 485<br />
POST 555, 563<br />
preferences<br />
file associations 50<br />
HTML files 149<br />
<strong>Server</strong> perspective 460<br />
validation 92<br />
principal 552, 569<br />
processing instructions 311<br />
profiling mode 489<br />
programmatic security 557, 561, 568<br />
Project Navigator 66<br />
provider 357<br />
proxy 374, 379–380<br />
publish 460–461, 470–471, 475, 478, 481, 483,<br />
487<br />
Q<br />
Quick Fix 499<br />
R<br />
readme file 11<br />
realm 552, 555, 558, 565<br />
<strong>Redbooks</strong> Web site 645<br />
Contact us xvii<br />
redirection 563<br />
remote procedure call (see RPC)<br />
repository 516–531, 533, 535–537, 539, 542–545,<br />
549<br />
request 33, 186<br />
object variable 246<br />
scope 247<br />
requestor 357<br />
resource 420<br />
resource bundle 420<br />
resource reference 198, 211<br />
response 33<br />
object variable 246<br />
revision tag 524, 527<br />
Rhino ECMAScript 32<br />
role 552, 556, 558, 560, 564, 566–567<br />
security 59, 556<br />
root element 311<br />
RPC 356, 361–362<br />
rtexprvalue 285<br />
652 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
S<br />
SAX2 320<br />
schema 163–164, 166, 169<br />
schemaLocation 318<br />
scope<br />
application 247<br />
page 247<br />
request 247<br />
session 247<br />
scripting elements 252<br />
scriptlet 252–253, 276–277, 299<br />
sequence 317<br />
server<br />
defining 462<br />
starting 471, 482, 487<br />
state 469<br />
stopping 488<br />
server configuration 459, 461–462, 469, 484–486,<br />
488<br />
server-side Java 215<br />
server-side logic 34<br />
service<br />
broker 358<br />
provider 358<br />
registry 358<br />
requestor 359<br />
servlet 195, 215, 243–244, 246, 557–558, 563,<br />
568–569<br />
configuration 219<br />
context 219<br />
initialization parameters 197, 269<br />
life cycle 216<br />
overview 216<br />
servlet container 59, 217–219<br />
servlet context 62<br />
servlet path 64<br />
ServletContext 297<br />
servlets<br />
initialization parameter 206<br />
session 33, 186<br />
object variable 246<br />
scope 247<br />
session attribute<br />
attributes<br />
session 249<br />
session management 462, 485
set method 412<br />
SGML 310<br />
shapes 124<br />
simple counter servlet 216<br />
simple type 316<br />
Simple <strong>WebSphere</strong> Authentication Method (see<br />
SWAM)<br />
SingleThreadModel 218<br />
site map 96, 106–107, 151<br />
site map candidate 151<br />
site part 107<br />
Site Parts drawer 96, 105–106<br />
SKIP_PAGE 282<br />
smart publish 461<br />
SOA 377<br />
SOAP 314, 320, 356, 359, 362<br />
encoding 362<br />
envelope 361<br />
introduction 360<br />
message 361<br />
over HTTP 361<br />
RPC 361<br />
sound 60<br />
SQL<br />
testing 184<br />
using saved statements 177<br />
SQL Query Builder 211–212, 333<br />
SQL <strong>Server</strong> 158<br />
connecting Studio to 162<br />
create a database 159<br />
SQL to XML 333<br />
SQLPLUS 158<br />
SSL 564, 578<br />
Static Web publishing server 465<br />
step-by-step mode 507<br />
Struts 36–37, 384, 642<br />
Action 399<br />
Action mapping 399<br />
Configuration file 452<br />
configuration file editor 422<br />
Deployment descriptor 453<br />
exception 417<br />
exceptions 399, 417, 423<br />
forwards 400, 409, 423<br />
Module 399, 419<br />
node 399<br />
preferences 393<br />
validation 424<br />
struts-config.xml 422, 452<br />
style sheet 120, 186, 320<br />
style sheets 120<br />
superclass 407<br />
SWAM 4<br />
synchronize 517, 519, 527, 530, 535, 542, 546<br />
synchronize navigation with help 56<br />
T<br />
table 116<br />
add 117<br />
attributes 117<br />
creating 117<br />
resize 117<br />
resizing 117<br />
tablespace<br />
create Oracle 158<br />
tag element 284–285<br />
tag handler 279, 283<br />
tag handler class 280–281, 283<br />
tag library 34, 267, 269<br />
see also taglib 275<br />
beans 386<br />
definition (see also TLD) 279<br />
HTML 386<br />
Jakarta project 276<br />
JSPSQL 192, 195, 269<br />
logic 386<br />
template 386<br />
utility taglibs 276<br />
TagExtraInfo 280<br />
taglib<br />
<strong>Application</strong> 297<br />
DateTime 297, 299–301<br />
directive 285, 287<br />
FileIO 300–301<br />
Fileserv 300–301<br />
Filter 300–301<br />
I18N 299<br />
I18n 297, 300–301<br />
importing 291<br />
JSP Standard tag library 299–300<br />
JSPSQL 297<br />
Jspsql 298<br />
Mailer 297, 299–300, 302, 644<br />
Page 297–298, 300–301<br />
Request 297–298, 300–301<br />
Response 297–298, 300–301<br />
Scrape 300–301<br />
Index 653
Session 297–298, 300–301<br />
Sslext 300<br />
String 297, 299–300<br />
tag libraries for accessing JSP objects 297<br />
tag libraries for database access 297<br />
tag libraries for internationalization 297<br />
Utility 297, 299–300<br />
utility tag libraries 297<br />
tags 544<br />
tasks<br />
adding to Tasks view 84<br />
TCP/IP monitoring server 465<br />
TEI 283<br />
template 71, 74<br />
application 75<br />
page 96, 105–106, 135<br />
page templates 94, 109–110<br />
template gallery 123<br />
text<br />
bold 116<br />
working with 116<br />
theme<br />
directory 74<br />
thin client 19<br />
thread 503, 506, 510<br />
tier 19–20<br />
TLD 279–280, 283–286, 294<br />
tModel 364, 366<br />
tools drawer 403<br />
trace 486<br />
transport guarantee 564<br />
U<br />
UDDI 356–357, 360<br />
API 365<br />
organization 366<br />
overview 363<br />
registry structure 363<br />
universal test client 485<br />
Universal Unique Identifier<br />
see UUID 365<br />
update 517, 519, 530, 532, 536, 542<br />
URI 65, 250, 284<br />
taglib 285–286, 293<br />
URL pattern 562<br />
URL rewriting 485<br />
use case 39<br />
usejdbc2.bat 203, 636<br />
utility classes 60<br />
654 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook<br />
V<br />
validation<br />
DTDs 330<br />
XML 314, 320, 327<br />
XML schema 329<br />
validators 92<br />
variable 209–210, 485, 503, 512<br />
version 515, 517–519, 521, 524–528, 532–534,<br />
537–539, 541–542, 544–546, 549<br />
version control 525, 527<br />
version from stream 526<br />
versioning 518<br />
video 60<br />
view<br />
adding 53<br />
Attributes 80, 116–118<br />
Breakpoint 501–502<br />
Breakpoints 506, 511<br />
Colors 83<br />
Console 459, 471, 475, 483, 487, 501<br />
CVS Repositories 520, 526–527, 529,<br />
537–539, 542, 545<br />
CVS Resource History 544<br />
Data Definition 157<br />
Data Mapping 424<br />
Data Mappings 424<br />
DB <strong>Server</strong>s 157, 159<br />
Debug 501, 503<br />
Design 81, 116, 321, 327–328<br />
fast 50–52<br />
floating 53<br />
Gallery 81<br />
icons 53<br />
Incoming/Outgoing 533<br />
J2EE Navigator 175<br />
Java Hierarchy 50<br />
Links 82<br />
MVC 31<br />
Outgoing 523, 525<br />
Outgoing Mode 524<br />
Outline 81, 157, 261, 321, 501<br />
Palette 104, 403<br />
Project Navigator 79–80, 122, 135, 233, 266,<br />
522, 524, 526–527, 530, 536, 538, 549<br />
Properties 51<br />
Repositories 519
<strong>Server</strong> 471, 481–482<br />
<strong>Server</strong> Configuration 200, 459, 481, 567<br />
<strong>Server</strong> Configurations 462<br />
<strong>Server</strong>s 459–460, 469–470, 487–489, 501<br />
Source 48, 116, 326, 328, 501<br />
Struts Explorer 408, 418–419, 423<br />
Synchronize 523–525, 530, 533, 535–536<br />
Tasks 84, 525<br />
Variables 501, 504, 512<br />
Web Structure 389<br />
W<br />
wallpaper 124–125<br />
WAR files 64<br />
WAS_HOME_V5 491<br />
Web<br />
services 359<br />
Web application 59<br />
see also Web module 57<br />
Web applications<br />
see also Web project 57<br />
Web container 4, 251, 456<br />
Web Content directory 74<br />
Web diagram 403, 420<br />
Web diagram editor 393, 398–399, 401, 404–405<br />
Web module 58, 65, 72, 488, 559, 566<br />
see also Web application 57<br />
see also Web project 57<br />
creating 66<br />
Web project 72, 524<br />
see also Web application 57<br />
see also Web module 57<br />
creating 66<br />
directory structure 72<br />
Web service client 369<br />
Web services 485<br />
binding 377<br />
overview 356<br />
Web Services Invocation Framework (see WSIF)<br />
Web site designer<br />
Context menu 97<br />
Page icons<br />
Border 103<br />
Code 103<br />
Navigation candidate 103<br />
Navigation label 103<br />
Navigation root 103<br />
Site map candidate 103<br />
web.xml 61, 270, 280, 284, 286, 292, 555, 559–560<br />
WEB_INF 163<br />
WebArt Designer 122, 124, 128<br />
grouping objects 127<br />
WebArt file 127<br />
WEB-INF 60–61, 74, 163, 166, 292–293, 299,<br />
485–486<br />
<strong>WebSphere</strong> test environment 455–456, 462, 465,<br />
475<br />
welcome page 62, 135<br />
well-formed XML document 313<br />
wizard<br />
Create XML File 322, 327<br />
Database Web Pages 174–175, 178, 206–207,<br />
563, 570<br />
New Database Connection 160<br />
New File 331<br />
workbench 48<br />
workload management 458<br />
workspace 44<br />
changing 45<br />
resetting startup option 44<br />
running multiple Studios 45<br />
ws.ext.dirs 486<br />
WSDL 356–357, 359, 362, 375, 377<br />
document 362<br />
implementation 362<br />
interface 362<br />
WSIF 363<br />
X<br />
XML 279, 283<br />
attribute 311<br />
comment 311<br />
document 310<br />
element 310<br />
markup 310<br />
namespace 314<br />
processor 311<br />
sample applications 331<br />
tag 311<br />
validation 314<br />
XML editor 326<br />
XML file 485<br />
XML schema 155, 314–315, 321–322, 327, 329,<br />
369<br />
XML schema (see also XSD) 315<br />
XML Schema Editor 328<br />
Index 655
XML schema editor<br />
graph view 328<br />
xmlns 314–315<br />
XPath 319<br />
XSD 315, 317–318, 321, 323, 329, 362<br />
XSL 318, 320<br />
transformation 318<br />
XSLT 318<br />
XSLT script 320<br />
656 <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong> <strong>Server</strong> - Express V5.0.2 Developer Handbook
<strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express V5.0.2 Developer Handbook
<strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express V5.0.2<br />
Developer Handbook<br />
Use <strong>WebSphere</strong><br />
<strong>Application</strong> <strong>Server</strong> -<br />
Express to develop<br />
applications<br />
Test and deploy<br />
applications<br />
Learn by example<br />
SG24-6555-01 ISBN 0738425184<br />
Back cover<br />
This <strong>IBM</strong> Redbook introduces <strong>IBM</strong> <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express V5, an <strong>IBM</strong> offering that provides a<br />
comprehensive development tool and a single-server<br />
application server environment designed for small and<br />
medium business customers who want to have a Web<br />
presence for their business.<br />
This publication shows how to use <strong>WebSphere</strong> <strong>Application</strong><br />
<strong>Server</strong> - Express to build, test, and deploy Web applications.<br />
It will help you install the product, build a simple Web<br />
application, and deploy that application to the server.<br />
This publication is applicable to the Linux and Windows<br />
platforms.<br />
INTERNATIONAL<br />
TECHNICAL<br />
SUPPORT<br />
ORGANIZATION<br />
®<br />
BUILDING TECHNICAL<br />
INFORMATION BASED ON<br />
PRACTICAL EXPERIENCE<br />
<strong>IBM</strong> <strong>Redbooks</strong> are developed by<br />
the <strong>IBM</strong> International Technical<br />
Support Organization. Experts<br />
from <strong>IBM</strong>, Customers and<br />
Partners from around the world<br />
create timely technical<br />
information based on realistic<br />
scenarios. Specific<br />
recommendations are provided<br />
to help you implement IT<br />
solutions more effectively in<br />
your environment.<br />
For more information:<br />
ibm.com/redbooks