Visual Age Pacbase

Front cover
VisualAge Pacbase
for e-business
Applications
An overview of VisualAge Pacbase V3
Step-by-by guide to develop an

e-business application
Develop JSPs and EJBs
Richard Brijde
Randall Holleger
David Quantin
ibm.com/redbooks
International Technical Support Organization
VisualAge Pacbase for e-business Applications
December 2002
SG24-6201-00
Note: Before using this information and the product it supports, read the information in
“Notices” on page xiii.
First Edition (December 2002)
This edition applies to VisualAge Pacbase Version 3 for use with the Microsoft NT 4.0 SP 5
operating system, VisualAge for Java 3.02, WebSphere Studio 3.0, and WebSphere Application
Server 3.02 Enterprise Edition.
© Copyright International Business Machines Corporation 2002. All rights reserved.

Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Part 1. e-business application development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1. VisualAge Pacbase overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1 Definitions and terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Methodology support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Support for e-business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 2. VisualAge Pacbase targeted application architecture . . . . . . . 7

2.1 About Web applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Main architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Commonly encountered problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4 JSPs/servlet architecture main components . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.1 HTML pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.2 Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.3 JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.4 JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.5 VisualAge Pacbase proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.6 Application architecture overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.6.1 Introduction to patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.6.2 Choosing the business pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.6.3 Choosing the application topology . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.6.4 Choosing a runtime topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.6.5 Product mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.7 Defining the application architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.7.1 Design techniques used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.7.2 Development approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.7.3 Development standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.8 Basic VisualAge Pacbase architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.8.1 Middleware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.8.2 Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
© Copyright IBM Corp. 2002. All rights reserved. iii

2.8.3 Communications monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 3. VisualAge Pacbase products: overview . . . . . . . . . . . . . . . . . . 29

3.1 VisualAge Pacbase 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.1.1 The Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.1.2 The repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.2 Other tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.1 About Rational Rose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.2 About VisualAge for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.2.3 About WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.2.4 About WebSphere Application Server. . . . . . . . . . . . . . . . . . . . . . . . 34
3.2.5 About DB2 Universal Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.2.6 About MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.3 Tools integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.3.1 Integration of Rational Rose with VisualAge Pacbase . . . . . . . . . . . 35
3.3.2 Integration of Rational Rose with VisualAge for Java . . . . . . . . . . . . 35
3.3.3 Integration of VisualAge for Java with WebSphere Studio . . . . . . . . 35
3.3.4 Integration of VisualAge for Java with WAS . . . . . . . . . . . . . . . . . . . 36
3.3.5 Integration of WebSphere Studio with WAS . . . . . . . . . . . . . . . . . . . 36
3.3.6 Integration of WebSphere Application Server with DB2 . . . . . . . . . . 36
3.3.7 Complete product environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Chapter 4. Environment setup, installation, and administration . . . . . . . 39

4.1 Installation/setup: VisualAge Pacbase 3.0 repository . . . . . . . . . . . . . . . . 40
4.1.1 Special considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.1.2 Running the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.2 Installing the VisualAge Pacbase Workbench . . . . . . . . . . . . . . . . . . . . . . 69
4.2.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
4.3 Impacts on other tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
4.3.1 Installing the WebSphere test environment feature . . . . . . . . . . . . . 92
4.3.2 Installing the VisualAge Pacbase Java environment . . . . . . . . . . . . 93
4.4 VisualAge Pacbase 3.0: Site administration . . . . . . . . . . . . . . . . . . . . . . 100
4.4.1 Starting the administrator Workbench . . . . . . . . . . . . . . . . . . . . . . . 101
4.4.2 Menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.4.3 Using the administrator Workbench . . . . . . . . . . . . . . . . . . . . . . . . 113
4.4.4 Command lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
4.4.5 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
4.4.6 Pac/Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4.4.7 Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
4.4.8 Tool bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
4.5 External controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
4.5.1 Validity controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
4.5.2 Initialization controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
iv VisualAge Pacbase for e-business Applications

4.6 VisualAge Pacbase 3.0: Base administration . . . . . . . . . . . . . . . . . . . . . 131
4.6.1 Menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
4.6.2 Base administration tab options . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
4.7 VisualAge Pacbase utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.7.1 Changes from previous releases . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.7.2 New to this release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Chapter 5. VisualAge Pacbase 3.0 development . . . . . . . . . . . . . . . . . . . 137

5.1 The Workbench in general . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5.1.1 Logging on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5.1.2 Quick tour of the Workbench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
5.2 The workspace manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.2.1 The local update tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.2.2 All problems tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.2.3 Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.2.4 Log tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.3 Generation manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.3.1 Generation command lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
5.3.2 JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.4 Programming concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.5 Development with the e-business Workbench . . . . . . . . . . . . . . . . . . . . 158
5.5.1 Data elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
5.5.2 Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
5.5.3 Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
5.5.4 Logical views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
5.5.5 Elementary components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
5.5.6 e-business application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
5.5.7 Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
5.5.8 Communication monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Chapter 6. Reuse and portability in VisualAge Pacbase . . . . . . . . . . . . . 185

6.1 Reusability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
6.1.1 Reusable components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
6.1.2 Organizing the repository for reusability . . . . . . . . . . . . . . . . . . . . . 187
6.1.3 Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
6.1.4 Positioning the repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.2 Data entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.2.1 Data elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.2.2 Data structures and segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
6.2.3 Database blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
6.3 Documentation entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
6.3.1 Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
6.3.2 Publishing facility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Contents v
6.3.3 Parameterized input aid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
6.4 Processing entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
6.4.1 e-business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
6.4.2 Batch programs and macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
6.4.3 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
6.5 Cross-references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
6.5.1 Available cross-references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
6.5.2 Maintenance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
6.5.3 Cross-reference considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
6.6 Portability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
6.6.1 Repository content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
6.6.2 Generated applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Chapter 7. VisualAge Pacbase development process . . . . . . . . . . . . . . . 201

7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
7.2 Development paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
7.2.1 Forward development path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
7.2.2 Analysis and design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
7.2.3 Backward development path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
7.3 Designing a VisualAge Pacbase application . . . . . . . . . . . . . . . . . . . . . . 204
7.3.1 Required components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
7.3.2 Relation to Unified Modeling Language (UML) . . . . . . . . . . . . . . . . 204
7.3.3 Relation to the Rational Rose Toolkit . . . . . . . . . . . . . . . . . . . . . . . 206
7.4 Server-side implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
7.4.1 Building a services node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
7.4.2 Building a services system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
7.4.3 Setting a technical context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
7.4.4 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
7.5 Client-side implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
7.5.1 Developing services components . . . . . . . . . . . . . . . . . . . . . . . . . . 208
7.5.2 Developing presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
7.5.3 Developing navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
7.5.4 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
7.6 Development process summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
7.7 Team considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
7.7.1 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Chapter 8. Building services and data access . . . . . . . . . . . . . . . . . . . . . 213

8.1 Logical view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
8.2 Elementary component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
8.3 The e-business application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
8.3.1 Error server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
8.4 Communication monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
vi VisualAge Pacbase for e-business Applications

8.5 Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
8.5.1 The Services Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.5.2 Folder view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.6 Technical considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
8.6.1 Technical environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
8.6.2 Building a proxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
8.6.3 Testing the e-business application . . . . . . . . . . . . . . . . . . . . . . . . . 227
Chapter 9. The VisualAge Pacbase proxy . . . . . . . . . . . . . . . . . . . . . . . . . 229

9.1 What is a VAP proxy? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
9.2 Proxy features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
9.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
9.2.2 Hierarchy of generated proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
9.2.3 Public services of generated proxies . . . . . . . . . . . . . . . . . . . . . . . 234
9.2.4 More about proxy dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Chapter 10. Building the model layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

10.1 Useful patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
10.1.1 Singleton pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
10.1.2 Implementing the singleton pattern in Java. . . . . . . . . . . . . . . . . . 246
10.1.3 Factory pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
10.1.4 Command pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
10.2 Command framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
10.2.1 Command interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
10.2.2 CommandException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
10.2.3 CommandFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
10.2.4 Command programming process . . . . . . . . . . . . . . . . . . . . . . . . . 252
10.3 Business object framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
10.3.1 BusinessObject interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
10.3.2 BusinessObjectFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
10.3.3 Business object programming process . . . . . . . . . . . . . . . . . . . . . 255
10.3.4 Relation to the command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
10.4 Model layer summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Chapter 11. Creating presentation with JSPs. . . . . . . . . . . . . . . . . . . . . . 257

11.1 Introduction to JavaServer pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
11.2 Components of JavaServer pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
11.2.1 JSP directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
11.2.2 Page directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
11.2.3 JSP scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
11.2.4 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
11.2.5 JSP actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
11.2.6 About WebSphere specific tags . . . . . . . . . . . . . . . . . . . . . . . . . . 263
11.3 Implementing the presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Contents vii
11.3.1 Programming process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
11.3.2 JSP tags guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
11.3.3 A very simple example using the DataDeliveryBean . . . . . . . . . . 264
11.4 Implementing wireless presentation using JSP . . . . . . . . . . . . . . . . . . . 265
11.4.1 About the Wireless Application Protocol (WAP) . . . . . . . . . . . . . . 265
11.4.2 Serving dynamic WML content using servlets and JSPs . . . . . . . 265
11.4.3 WAP relative to our e-business architecture . . . . . . . . . . . . . . . . . 266
Chapter 12. Implementing navigation with servlets. . . . . . . . . . . . . . . . . 267

12.1 Introduction to Java servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
12.1.1 Servlet process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
12.1.2 The Java Servlet API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
12.1.3 Persistency management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
12.1.4 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
12.2 Implementing the navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
12.2.1 Programming process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
12.2.2 Granularity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
12.2.3 Control mechanism and navigation . . . . . . . . . . . . . . . . . . . . . . . . 272
12.2.4 Non JSP resulting servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
12.2.5 A generic controller servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Chapter 13. Testing and deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

13.1 Using the VisualAge Pacbase Test Tool . . . . . . . . . . . . . . . . . . . . . . . . 278
13.1.1 Installing the tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
13.1.2 Configuring the tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
13.1.3 Running the tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
13.2 Other client-side test tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
13.3 Deploying an e-business application . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
13.3.1 Deploying server side components . . . . . . . . . . . . . . . . . . . . . . . . 284
13.3.2 Deploying HTML pages and JSPs . . . . . . . . . . . . . . . . . . . . . . . . 284
13.3.3 Deploying servlets and JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . 286
13.4 Runtime testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Part 2. VisualAge Pacbase Cruise Lines sample application . . . . . . . . . . . . . . . . . . . . . . 287
Chapter 14. VisualAge Cruise Lines application specifications . . . . . . . 289

14.1 VisualAge Cruise Lines background . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
14.2 VisualAge Cruise Lines requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 290
14.3 Data considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
14.3.1 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
14.3.2 Relationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
14.3.3 Data implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
14.4 Processing considerations and implementation . . . . . . . . . . . . . . . . . . 297
14.5 VisualAge Cruise Lines customer reservation. . . . . . . . . . . . . . . . . . . . 299
viii VisualAge Pacbase for e-business Applications

14.6 VisualAge Cruise Lines management . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Chapter 15. Bridging from Rational Rose . . . . . . . . . . . . . . . . . . . . . . . . . 309

15.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
15.2 Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
15.2.1 Using Rational Rose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
15.2.2 Using the bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
15.2.3 Using VisualAge Pacbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
15.3 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
15.3.1 Packages, diagrams, and folder . . . . . . . . . . . . . . . . . . . . . . . . . . 311
15.3.2 Class diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
15.3.3 Classes and attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
15.3.4 Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
15.3.5 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
15.3.6 Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
15.3.7 Aggregation and references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
15.3.8 Associatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
15.3.9 Installed bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
15.4 Operating the bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
15.4.1 Importing the Rose model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
15.4.2 Generating the VisualAge Pacbase entities . . . . . . . . . . . . . . . . . 320
15.4.3 Completing the imported entities. . . . . . . . . . . . . . . . . . . . . . . . . . 323
Chapter 16. Completing server development . . . . . . . . . . . . . . . . . . . . . . 325

16.1 Logical views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
16.1.1 Cruise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
16.1.2 CruiseLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
16.1.3 Reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
16.1.4 Ship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
16.2 Elementary components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
16.2.1 Cruise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
16.2.2 CruiseLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
16.2.3 Reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
16.2.4 Ship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
16.3 Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
16.3.1 Reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
16.3.2 CruiseLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
16.4 Generating. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
16.4.1 Proxy generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Chapter 17. Developing JavaBeans . . . . . . . . . . ...... ....... ...... . 343

17.1 Preparing the VisualAge environment . . . . . . ...... ....... ...... . 344
17.1.1 Creating the VisualAge projects . . . . . . ...... ....... ...... . 344
17.1.2 Creating the Java packages . . . . . . . . . ...... ....... ...... . 345
Contents ix
17.1.3 WebSphere Test Environment setup . . . . . . . . . . . . . . . . . . . . . . 346
17.1.4 Importing the VisualAge Pacbase proxies . . . . . . . . . . . . . . . . . . 348
17.2 Developing the business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
17.2.1 Identifying the business objects . . . . . . . . . . . . . . . . . . . . . . . . . . 349
17.2.2 Destination business object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
17.2.3 CruiseLineBusinessObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
17.2.4 ReservationBusinessObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
17.3 Developing commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
17.3.1 Identifying the commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
17.3.2 Destination commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
17.3.3 Cruise line commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
17.3.4 Reservation commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Chapter 18. Building JSPs and servlets . . . . . . . . . . . . . . . . . . . . . . . . . . 375

18.1 Preparing the WebSphere Studio environment . . . . . . . . . . . . . . . . . . . 376
18.1.1 Creating the WebSphere Studio project . . . . . . . . . . . . . . . . . . . . 376
18.1.2 Setting versions for the JSP and the application server . . . . . . . . 376
18.1.3 Creating the folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
18.1.4 Customizing the stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
18.2 Implementing HTML pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
18.3 Developing the JavaServer pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
18.3.1 Employee JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
18.3.2 Customer JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
18.3.3 CommandException.JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
18.4 Developing the DataDeliveryBeans. . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
18.4.1 Identifying the DataDeliveryBeans . . . . . . . . . . . . . . . . . . . . . . . . 388
18.4.2 Destination DataDeliveryBeans . . . . . . . . . . . . . . . . . . . . . . . . . . 388
18.4.3 Cruise line DataDeliveryBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
18.4.4 Reservation DataDeliveryBeans . . . . . . . . . . . . . . . . . . . . . . . . . . 391
18.5 Developing the servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
18.5.1 Identifying the servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
18.5.2 Destination servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
18.5.3 GetUniqueDestinationServlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
18.5.4 Cruise line servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
18.5.5 Reservation servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
18.6 Introducing the WAP application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
18.6.1 Adapting the presentation to the WAP . . . . . . . . . . . . . . . . . . . . . 409
18.6.2 Developing the WML-based JSPs . . . . . . . . . . . . . . . . . . . . . . . . 409
18.6.3 Subclassing the servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
18.6.4 Testing with the WAP application . . . . . . . . . . . . . . . . . . . . . . . . . 415
Chapter 19. Deploying the application . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

19.1 Deploying the VisualAge Cruise Lines Application . . . . . . . . . . . . . . . . 418
x VisualAge Pacbase for e-business Applications

19.1.1 Creating the VisualAge Cruise Lines Web application . . . . . . . . . 418
19.1.2 Creating the required Web application directories . . . . . . . . . . . . 422
19.1.3 Deploying files to WAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
19.1.4 Starting the Web application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
19.1.5 Defining servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
19.2 Additional deployment considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 426
19.2.1 The e-business application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
19.2.2 Communications monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
19.2.3 Working file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
19.2.4 Error server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
System requirements for downloading the Web material . . . . . . . . . . . . . 432
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Related publications . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 435

IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 435
Other resources . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 436
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 436
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 437
IBM Redbooks collections . . . . . . . . . . . . . . . . . ...... ....... ...... . 437
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Contents xi
xii VisualAge Pacbase for e-business Applications
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area.
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However, it is the user's
responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may
make improvements and/or changes in the product(s) and/or the program(s) described in this publication at
any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm
the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on
the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrates programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the
sample programs are written. These examples have not been thoroughly tested under all conditions. IBM,
therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to IBM's application
programming interfaces.
© Copyright IBM Corp. 2002. All rights reserved. xiii

Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Balance® IBM eServer™ Redbooks™

CICS® MQSeries® Redbooks (logo)™
DB2® MVS™ SP™
DB2 Universal Database™ Perform™ VisualAge®
IBM® RACF® WebSphere®
The following terms are trademarks of International Business Machines Corporation and Lotus Development
Corporation in the United States, other countries, or both:
Approach® Lotus® Word Pro®
The following terms are trademarks of other companies:
Rational Rose and UML are trademarks of the Rational Software Corporation in the United States, other
countries, or both.
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United
States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure
Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service marks of others.
xiv VisualAge Pacbase for e-business Applications

Preface
This IBM Redbook provides you with information that will allow you to use
VisualAge Pacbase 3.0 (VAP) to create, manage, and deploy e-business
applications in an application repository environment.
In Part 1, we focus on the installation of VisualAge Pacbase and the

administration and use of the product. We describe the targeted application
architecture and provide an overview of the products, other required tools, and
their integration with VisualAge Pacbase, as well as the VisualAge Pacbase
development model. We discuss how VisualAge Pacbase provides reuse and
portability of the application components and how to build services and
accomplish data access. We present the advantages of using the VisualAge
Pacbase proxy for e-business applications and explain how to build a view with
the proxy on the client side of the application. As part of the proxy discussion, we
cover the use of JSPs for presentation and explain how to use the VisualAge
Pacbase proxy to quickly develop JSPs using WebSphere Studio. Finally, we
show how to implement navigation in the servlets with WebSphere Studio and
Visual Age Java and how to test and deploy the completed e-business
application.
In Part 2, we develop an e-business application using VisualAge Pacbase 3.0,

WebSphere Studio, and VisualAge for Java. We discuss design, construction,
testing, and implementation. Our sample application establishes a Web site for
the VisualAge Cruise Line sample and provides a WAP version of the
implementation as well.
The team that wrote this redbook

This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, San Jose Center.
Richard Brijde is a VAP Specialist with New Age Consultancy in The

Netherlands. He teaches VAP classes and supports a variety of client projects.
Randall Holleger is a Product Implementation Manager with e-Applications

Solutions Group in the United States. He has 20 years of experience with the
VisualAge Pacbase products and teaches classes in VisualAge Pacbase
administration and development.
© Copyright IBM Corp. 2002. All rights reserved. xv

David Quantin is an e-business Specialist with IBM Global Services based in
Paris, France. He has 5 years of experience in software development and
consulting in both private and government sectors. He is currently working on
e-business projects centered around WebSphere technology and developed with
VisualAge for Java.
The redbook authors express their thanks to the following people for their
invaluable contributions to this project:
򐂰 Anne-Marie Hue, for her assistance in organizing the redbook, managing the
effort in Noisy Le Grand, and coordinating the activity between the
development team and the redbook authors
򐂰 Sebastien Alonzo, for his assistance in reviewing the content
򐂰 Bruno Charpentier, for his assistance in developing the sample application
򐂰 Joe DeCarlo, for his ongoing support in all aspects of redbook publishing and
ITSO project management
򐂰 IBM Paris Lab development team, for their timely assistance in various
aspects of the VisualAge Pacbase product
Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbook
dealing with specific products or solutions, while getting hands-on experience
with leading-edge technologies. You'll team with IBM technical professionals,
Business Partners and/or customers.
Your efforts will help increase product acceptance and customer satisfaction. As
a bonus, you'll develop a network of contacts in IBM development labs, and
increase your productivity and marketability.
Find out more about the residency program, browse the residency index, and
apply online at:
ibm.com/redbooks/residencies.html
xvi VisualAge Pacbase for e-business Applications

Comments welcome
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Send us your comments

about this or other Redbooks in one of the following ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an Internet note to:
redbook@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. 1WLB Building 80-E2
650 Harry Road
San Jose, California 95120-6099
Preface xvii
xviii VisualAge Pacbase for e-business Applications
Part 1
Part 1 e-business
application
development
In Part 1, we focus on the installation of VisualAge Pacbase and the
administration and use of the product. We describe the targeted application
architecture and provide an overview of the products, other required tools, and
their integration with VisualAge Pacbase, as well as the VisualAge Pacbase
development model. We discuss how VisualAge Pacbase provides reuse and
portability of the application components and how to build services and
accomplish data access. We present the advantages of using the VisualAge
Pacbase proxy for e-business applications and explain how to build a view with
the proxy on the client side of the application. As part of the proxy discussion, we
cover the use of JSPs for presentation and explain how to use the VisualAge
Pacbase proxy to quickly develop JSPs using WebSphere Studio. Finally, we
show how to implement navigation in the servlets with WebSphere Studio and
Visual Age Java and how to test and deploy the completed e-business
application.
© Copyright IBM Corp. 2002. All rights reserved. 1

2 VisualAge Pacbase for e-business Applications
1
Chapter 1. VisualAge Pacbase overview

In this chapter we provide an overview of the functional areas to be covered in
this redbook, which deals with VisualAge Pacbase 3.0 as it relates to VisualAge
Java and WebSphere Studio. Additional information on VisualAge Pacbase can
be obtained at:
http://www.ibm.com/software/ad/vapacbase

1.1 Definitions and terminology
VisualAge Pacbase is a repository-based application development tool that
supports the full range of e-business application development activity, including
analysis, design, construction, testing, and implementation, as well as ongoing
maintenance and enhancements.
VisualAge Pacbase offers the following advantages for e-business applications:

򐂰 Use of the proxy object
򐂰 Accelerated development and deployment of Web-based applications
򐂰 Integration with latest technology
򐂰 Reusability of application components
Proxy objects enable developers to directly access data, services, and events
available on the server. Using a proxy optimizes network traffic at runtime and
utilizes local cache management. The proxy establishes a public interface that
hides complex mechanisms associated with the middleware, local cache, paging,
and error management.
VisualAge Pacbase 3.0 implements a modern development environment

intended to provide a visual programming approach supported by SmartGuides.
This development environment consists of a set of files used to manage the
components of your applications. Collectively, these files and the software to
manage them are referred to as the VisualAge Pacbase repository. Developers
accomplish their activity within their own local versions of the repository. Local
repository versions are then synchronized with the server repository. This
establishes the server repository as the authoritative source of application
components. This approach enables application components to be reused by
other developers to build additional e-business applications and results in greater
reliability and presentation consistency of applications.
VisualAge Pacbase 3.0 operates on a variety of hardware platforms and

operating systems. The discussion in this redbook is limited to the version
running on Windows NT 4.0 on an IBM-compatible computer. WebSphere Studio
and VisualAge Pacbase are complementary solutions for building scalable
e-business applications. We used VisualAge Java 3.02 and WebSphere Studio
3.0 to demonstrate the proxy capabilities of VisualAge Pacbase.
This redbook assumes that you have very little previous knowledge of VisualAge
Pacbase. Using this redbook, you can install and use the product. If you have
experience with VisualAge Pacbase you will recognize many new features in this
complete new design of the product. These include:
򐂰 Improved administration through the administrator Workbench
򐂰 Physical restructuring of the repository

򐂰 Additional validation and initialization of entity definitions and descriptions
through the use of customizable scripts
򐂰 Separation of the report entity from the data structure entity
򐂰 A facility to document macro parameters
򐂰 Classification of the general documentation screen into comments, options,
and its use to specify error messages
򐂰 A facility to duplicate an entire entity rather than having to copy each part of
the entity
򐂰 User profiles to manage repository access
򐂰 Consolidation of batch administrative procedures
Both the developer’s and administrator’s Workbenches have been completely

redesigned to create a more natural flow of activity. SmartGuides have been
included to guide the developer and administrator through complex tasks.
1.2 Methodology support

Unified Modeling Language (UML) is supported in addition to more traditional
methodologies such as OMT, Merise, and Yourdon. VisualAge Pacbase 3.0
integrates easily with VisualAge Java and includes the capability to transfer
information from Rational Rose in order to begin establishing application
components in the repository.
1.3 Components
The following optional VisualAge Pacbase 3.0 features are not part of the scope
of this redbook:
򐂰 Production Environment Interface (PEI) for managing the transition of
application components into the production environment
򐂰 Development Support Management System (DSMS) for managing
maintenance and enhancement activity
򐂰 Pacbase Update Facility (PUF) for directly updating the repository content
򐂰 Graphical design support (Pacdesign) for producing diagrams and
documentation using the conventions of a specific methodology such as the
Unified Modeling Language (UML)
򐂰 Meta-entities (formerly user-entities) that extend the standard set of things
managed by the VisualAge Pacbase repository
Chapter 1. VisualAge Pacbase overview 5

VisualAge Pacbase 3.0 requires workstations with a recommended 128 MB RAM
supporting a Java runtime environment and the appropriate middleware or a
gateway accessible through TCP-IP. A processor speed of 233 mhz is
recommended along with 500 MB of free disk space. 128 MB of RAM is specified
with 256 MB recommended for optimal performance. In addition, VisualAge
Pacbase 3.0 requires Internet Explorer 4.0 or later, or Netscape Navigator 4.0 or
later, as the browser for on-line help.
1.4 Support for e-business

VisualAge Pacbase supports e-business development projects with any number
of developers for projects of all sizes and levels of complexity within any industry.
VisualAge Pacbase 3.0 runs in both IBM and non-IBM environments. For more
information concerning any specific hardware environment or operating system
contact IBM or visit the IBM VisualAge Pacbase Web site at:
http://www.software.ibm.com/ad/
Developers customize their VisualAge Pacbase development workstations to a

look and feel that will increase the productivity of the developer. VisualAge
Pacbase 3.0 supports both English and French language development. Inquiries
regarding other language support should be directed to IBM.
VisualAge Pacbase offers a practical solution to increase the use of Java

technology while providing a multi-user repository-based approach to e-business
application development.
You can easily Web-enable existing applications with VisualAge Pacbase. By

defining a minimal number of entities within the VisualAge Pacbase repository,
the necessary components can be generated and deployed to successfully
interact with pre-existing applications.

2
Chapter 2. VisualAge Pacbase targeted

application architecture
In this chapter we present a short overview of the type of Web applications we
intend to develop in terms of runtime environment and physical structure. We
cover the problems commonly encountered during such development.
Also, we describe the details of the client architecture we intend to use for the
VisualAge Cruise Lines sample application.

2.1 About Web applications
In this topic we introduce the main types of Web architectures and discuss
common problems that you may encounter.
2.2 Main architectures

During the last five years, a variety of architectures have been designed and
tested for Web applications.
In this section, we review the ones used most often.
One-layer architecture
The one-layer architecture refers to an architecture that is local to the client and
does not involve the server. In this architecture, the HTML browser or the client
application present local files to the user.
Figure 2-1 illustrates this one-layer architecture.
Client Server
HTML
Browser URL
Files
* HTML
* GIF/JPEG
* MOV/AVI
* Javascript
* Java Applet
Figure 2-1 One-layer architecture

Two-layer architecture
The two-layer architecture is referred to as client/server. Here, the HTML browser
can present, to the user, files that come from an HTTP server.
Figure 2-2 illustrates this two-layer architecture.
Client Server
HTML
Browser HTTP HTML
Server
* HTML
* GIF/JPEG
* MOV/AVI
* Javascript
* Java Applet
Figure 2-2 Two-layer architecture
Chapter 2. VisualAge Pacbase targeted application architecture 9

Two-layer architecture with applets and JDBC
Another variation of the client/server architecture can be described as a two-layer
architecture with applets and JDBC (Java Data Base Connectivity). In this
architecture, the HTML browser typically presents files to the user which come
from an HTTP server. In addition, applets can run on the client and access server
data through JDBC. Figure 2-3 illustrates this two-layer architecture.
Client Server
HTML
Browser
HTTP HTML
Server Files
* HTML
* GIF/JPEG
* MOV/AVI
* Javascript
Database
Java
Applet
JDBC
Figure 2-3 Two-layer architecture with applet and JDBC

Three-layer architecture: applet/servlet
The three-layer architecture is known as applet/servlet. The HTML browser
typically presents files to the user which come from an HTTP Server.
On the client, applets run and access server data through an applet/servlet
communication. Most of the business logic is implemented on the server part and
executes in a Java application server.
Figure 2-4 illustrates this applet/servlet architecture.
Client Server
HTML
Browser HTTP HTML
Server Files
* HTML Application Server

* GIF/JPEG
* MOV/AVI
* Javascript Java
Servlet
Java Applet JDBC

Database
RMI
RMI
Figure 2-4 Three-layer architecture with applet-servlet communications

Three-layer architecture: JSP/servlet
Another form of the three-layer architecture is referred to as JSPs/servlet or thin
client architecture. Here, the HTML browser presents files to the user which
come from an HTTP Server. The business logic is implemented on the server.
The graphic part is processed on the server (JSPs or XML) and delivered to the
client as HTML.
Figure 2-5 illustrates this thin client architecture.
Client Server
Application Server
Application Server
Java
HTML HTTP Servlet
Browser
Java
HTT Legacy
P Bean
JSPs
Files Database
Figure 2-5 Three-layer architecture with JSPs and servlets
This thin client architecture is popular because of the following considerations:

򐂰 Performance: Processing capability is generally greater on the server than
on most client machines.
򐂰 Deployment: The application is installed and configured for the server as
opposed to a variety of client environments.
򐂰 Maintenance: Locating the processing on the server means that the
application components need only to be re-deployed on the server when
changes occur.

2.3 Commonly encountered problems
Regardless of the architecture, the following issues and problems are usually
encountered and need to be addressed:
򐂰 Communication/middleware
򐂰 Performance
򐂰 Traffic loads
򐂰 Security
򐂰 Data integrity
򐂰 Existing legacy applications
򐂰 Persistence management
Communication/middleware
Communication/middleware problems result when an architecture is chosen that
distributes processing between the client and the server. Basically, each client
environment can have its own characteristics, specifically the communication
protocol that it uses to communicate with other servers. All of the machines that
need to interact must have some common basis for communication. This is
referred to as the middleware. The middleware must be capable of handling the
communications efficiently between all of the machines that participate in the
application’s architecture.
Performance
Performance problems can result when an architecture is chosen that distributes
processing, particularly data access, between the client and the server.
Response time can be hindered as a slow client processor attempts to retrieve
and present data that is not local. Presentation is also affected by the client
processor. Applications that perform well on one client can be frustrating on
another.
Traffic loads
Traffic loads can result when an architecture is chosen that places the processing
and data access on the server. This occurs when the server environment is not
sufficient to handle the processing and communication load presented by the
multitude of clients it services.

Security
Security issues can result when an architecture is chosen that distributes
processing, particularly data access, between the client and the server. This
occurs because of the possibility of having local copies of data that contain
sensitive information. It is generally more difficult to protect the client machines
from unauthorized use than it is to safeguard a server. In addition, disaster
recovery issues can become more complex when several clients need to be
re-synchronized in the event of a catastrophic failure.
Data integrity
Data integrity issues can result when an architecture is chosen that distributes
processing and particularly, data access, between the client and the server. This
occurs because of the possibility of having local copies of data and the possibility
that two clients can make local changes to the same data. Eventually, when this
data is synchronized to a common data source, a conflict results because the
synchronization process has no way of knowing which version of the data should
take precedence. In addition, data integrity may be compromised on the client
machine through the use of tools and utilities that may manipulate the data from
outside the application.
Interfaces to legacy applications

Another problem area concerns legacy applications. Deployed applications
generally are not independent in terms of the data that they use and normally
need to support an overall workflow for an end-user. The workflow is made up of
a variety of applications that need to interact. The complexity of this interaction is
a function of how distributed the data and processing are for a given architecture.
Persistence management
Depending on the design of an application, some data and objects may need to
be persistent. This means that they need to be retained from one part of an
application to another or from one execution of the application to a subsequent
execution of that application. The problem occurs because an end-user may not
necessarily use the same machine each time the application is needed and yet
certain data or objects must remain persistent. The degree that the processing
and data are distributed in the architecture can add to the complexity of making
persistent data and objects available.
2.4 JSPs/servlet architecture main components

In this topic we present an overview of the JSPs/servlet main components.

2.4.1 HTML pages
HTML (HyperText Markup Language) is the language used to tag various parts of
a Web document. The term “hypertext” is somewhat misleading since Web
documents now contain much more than just text. In addition to text, HTML
pages can contain:
򐂰 Links (hyperlinks) to other Web documents or other Web sites
򐂰 Graphics such as images, charts, and diagrams
򐂰 Attached media to produce audible sounds and to play audio or video clips
HTML instructs the browsing software regarding how to present a Web

document's text, hyperlinks, graphics, and attached media.
An HTML page is a document written in HyperText Markup Language.
2.4.2 Servlets
Servlets are protocol and platform independent server-side software
components, which are written in Java. Servlets run inside a Java enabled server
or application server, such as the WebSphere Application Server. Servlets are
loaded and executed within the Java Virtual Machine (JVM) of the Web server or
application server.
Servlets implement a common request/response paradigm for the handling of the

messaging between the client and server. The Java Servlet API defines a
standard interface for the handling of these request and response messages
between the client and server.
2.4.3 JavaBeans
The JavaBeans API makes it possible to write component software in the Java
programming language. Components are self-contained, reusable software units
that can be visually assembled into composite components, applets,
applications, and servlets using visual application builder tools (for example,
VisualAge for Java). JavaBean components are known simply as Beans.
Beans expose their features (for example, public methods and events) to builder
tools for visual manipulation. This is possible because a Bean's feature name
conforms to specific design patterns. A “JavaBean-enabled” builder tool can then
examine the Bean's patterns, discern its features, and make those features
available for visual manipulation.

The builder tool maintains Beans in a palette or toolbox. You can select a Bean
from the toolbox, drop it into a form, modify its appearance and behavior, and
define its interaction with other Beans. The Bean, along with other Beans, can be
composed into an applet, application, or even a new Bean. Working with a visual
programming tool, all this can be done without writing a line of code.
2.4.4 JSPs
A basic HTML page is a static document and its content is the same each time it
is presented. JavaServer Pages (JSPs) are similar to HTML files, but provide the
ability to display dynamic content within Web pages.
JSPs are made operable by having their contents (HTML tags, JSP tags and
scripts) translated into a servlet by the application server. This process is
responsible for translating both the dynamic and static elements declared in the
JSP file into Java servlet code that delivers the translated contents through the
Web server output stream to the browser.
The architecture of a JSP/servlet-enabled Web site is often referred to as

thin-client because most of the business logic is executed on the server.
2.5 VisualAge Pacbase proxy

This is an overview of the VisualAge Pacbase Proxy concept. Later in this
redbook, we provide a more complete discussion about the VisualAge Pacbase
Proxy.
Basically, the Proxy is a generated JavaBean that represents a server-side

VisualAge Pacbase Folder. This JavaBean has a public API that hides complex
mechanisms such as:
򐂰 Locking mechanisms
򐂰 Middleware, management of the local cache, paging
򐂰 Network traffic and message optimization
򐂰 Error management
򐂰 Multi-user access
򐂰 Multi-services requests
Figure 2-6 and Figure 2-7 illustrate the VisualAge Pacbase proxy components.

Generation
Folder
methods attributes
events
Folder PROXY Java Bean
Figure 2-6 VisualAge Pacbase proxy is generated
Client
Proxy
Communication Folder Elementary

Monitor Server Servers
Figure 2-7 VisualAge Pacbase proxy as an interface for the server
Note: A Session Enterprise JavaBean (EJB) may be generated instead of a

Proxy in VisualAge Pacbase 3.0. (You should be aware of this, even though
the topic is not discussed in this redbook.)
2.6 Application architecture overview

In this topic we provide an overview of the targeted application architecture using
VisualAge Pacbase.

2.6.1 Introduction to patterns
For better understanding of underlying points, refer to Patterns for e-business:
User to Business Patterns for Topology 1 and 2 using WebSphere Advanced
Edition, SG24-5864.
Patterns for e-business aim to communicate in a highly accessible fashion the

business pattern, systems architecture (application and runtime topologies),
product mappings, and guidelines required for different classes of applications.
Patterns can be likened to templates which allow you to develop e-business
applications based on a proven approach rather than having to design your
application without any guidance.
When using patterns, the following design process is used:

1. Defining the runtime context
a. Choosing the business pattern
b. Choosing the application topology
c. Choosing the runtime topology
2. Defining the products
a. Within the development context
b. Within the runtime context
3. Defining the application architecture
a. Development framework
b. Development standards
2.6.2 Choosing the business pattern

In Patterns for e-business: User to Business Patterns for Topology 1 and 2 using
WebSphere Advanced Edition, the patterns are cataloged according to the
following business patterns:
򐂰 User-to-business
򐂰 User-to-online buying
򐂰 Business-to-business
򐂰 User-to-data
򐂰 User-to-user
򐂰 Application integration
You can see that these patterns cover a wide range of e-business scenarios.
VisualAge Pacbase allows you to work with any of these patterns.
In this redbook, we focus on the user-to-business pattern that we intend to use

for the VisualAge Cruise Lines sample application.

2.6.3 Choosing the application topology
After the business pattern is determined and the design activity has identified the
application components, these application components need to be distributed
across some form of application topology. The application topology describes
how the application components are arranged based on the application’s logic
and associated data.
The e-business applications developed with VisualAge Pacbase are Web-centric.

Web-centric means that the application components are organized with a clean
separation between the presentation and application logic, while optionally
allowing for connections to legacy applications or databases in a three-layer
architecture. A sample topology, user-to-business, is shown in Figure 2-8.
synchronous synchronous /
Presentation Application asynchronous
Application
Read/Write data Application node Application node containing

containing new or existing components with
modified no need for modification or
components which cannot be changed
Figure 2-8 User-to-business application topology
2.6.4 Choosing a runtime topology

The runtime topology identifies the physical environment which supports your
functional requirements. When describing the runtime topology you need to
identify:
򐂰 The operating system
򐂰 The communications
򐂰 The database management system
VisualAge Pacbase gives you the ability to generate application components

targeted for a wide variety of combinations from each of these areas. What is
more, application components developed with VisualAge Pacbase can easily be
ported to another combination as they are generated.

It should also be mentioned that you may be limited in choosing your runtime
topology to an environment that is already in place for your organization. Rarely
will your design result in a decision to change either the operating system,
communications, or database management system for your organization.
2.6.5 Product mapping

We have a good idea of the underlying architecture for our application. We now
need to define the products that will be used to map to this architecture.
Development products
The development products are:
򐂰 VisualAge for Java (Java development)
򐂰 WebSphere Studio (HTML and JSPs development)
򐂰 VisualAge Pacbase (Servers)
򐂰 VisualAge for COBOL (Compiling COBOL servers)
򐂰 DB2 Universal Database (database development)
Runtime products
The runtime products are:
򐂰 Windows NT 4.0 (operating system)
򐂰 WebSphere Application Server Advanced Edition (Java application server)
򐂰 IBM HTTP Server (HTTP server)
򐂰 JDK1.1.7 (Java Virtual Machine)
򐂰 DB2 Universal Database 5.0 (database management)
2.7 Defining the application architecture

We are limiting our discussion of defining the application architecture to the
client-side logical architecture. In this section we will introduce design
techniques, the development framework, and development guidelines.
2.7.1 Design techniques used

To provide robust and scalable software, we have to base our solution design
around some universally-accepted design techniques. The two prominent ones
are:
򐂰 Model-View-Controller framework
򐂰 Command bean design pattern

Model-View-Controller framework
Designing an application requires an understanding of how your various
components are going to interact and how they need to be structured to
accomplish that interaction.
The Model-View-Controller (MVC) framework provides guidelines for such a

design:
򐂰 The model is responsible for the underlying data, and for managing any
transactions that are associated with it. This is the business logic.
򐂰 The view is responsible for displaying the data. This is the presentation logic.
򐂰 The controller is responsible for decoupling the interactions between the
model and the view. The controller manages the end-user interactions and
calls the appropriate business logic to complete the functional request. This
allows the model to be reused with different views.
Command bean design pattern

The Command bean design pattern is a type of behavioral design pattern, which
means it manages how objects relate to and communicate with each other.
This is accomplished by taking a command and making it an object of the defined

class (Command) which responds to an execute method. During the execution of
your application, the object that requests the command needs to populate the
command object with any required data, and then simply call the execute
method. In this scenario, the calling object is unconcerned with the mechanics of
how the command is actually completed.
One of the problems encountered in the use of the Command bean is that
satisfying a particular request can involve a complex set of hierarchical methods.
In order to simplify the work of the Command bean and make responding to the
request more efficient, we use the concept of a business object. A business
object is derived from a proxy and serves as a filter for services. It is called a
business object because the services it contains are specific to the business
logic for the application. The purpose of the business object is to act as a filter for
the services that are available through the proxy. The result is that the application
only implements the services that it has a use for. The business object also
serves to group related services from the proxy.
For more information on the Command pattern and design patterns in general,
please refer to the book “Design Patterns - Elements of Reusable
Object-Oriented Software”, by Gamma, Helm, Johnson and Vlissides, ISBN
0201633612.

2.7.2 Development approach
Next we outline a brief development approach.
Introduction
We use a structured development approach to produce robust, reusable, and
highly maintainable software. This structured development approach is rather
simplistic and is based on the Model-View-Controller and the Command bean
patterns. This approach may need to be modified for large development efforts or
more complex e-business applications.
Figure 2-9 provides an overview of our framework for our e-business application.
Controller Business
Command Proxy
Servlet Object
HttpRequest 1 2
XController
XCommandBean XBusinessObject
Servlet
HttpResponse 4 3
6 5
DataDeliveryBean
7
JSPs XDataDeliveryBean
1 Generic request for services
2 Specific request for services
3 Return of data
,4
5 Constraint for data deliver
inherits from
6 Request for presentation
Request for specific data

implements 7
Figure 2-9 Framework overview
Model: Command bean and business objects

In our structured development approach, we use the model to implement the
business logic. The VisualAge Pacbase proxy is responsible for providing access
to both services and data related to the business logic and guides our
implementation of the model.

In our framework we use the servlet for the controller. The servlet issues generic
requests to the command bean, which acts as an interface between the
controller (Servlet) and the model (Business Object from the Proxy). The
Command bean is based on the Command pattern and provides the following
services:
򐂰 It validates the request and associated parameters from the controller
(servlet).
򐂰 It instantiates needed business objects and executes business logic through
specific services inherited from its corresponding proxy.
򐂰 It communicates the results of the execution of the business logic to the
controller (servlet).
View: JSPs
When the controller (servlet) obtains the results from the execution of the
business logic (the Command Bean, Business Object), these results need to be
presented to the end user. This is done by having the controller (servlet) manage
the view (JSPs and HTML pages) and instantiate the DataDeliveryBean. The
view is referred to as the presentation logic and is fully independent of the
Command bean-business object interaction. This approach allows us to reuse
the view components (JSPs, HTML pages) even if we change the way the
Command bean satisfies the controller (servlet) request to execute the business
logic. The reverse is also true. We can reuse the business logic and Command
bean as the view components change over time.
Controller: servlet
To summarize, we use a servlet for the controller, which provides the following
services:
򐂰 It validates the request and session parameters.
򐂰 It instantiates the Command bean and executes the business logic.
򐂰 It instantiates and populates the DataDeliveryBean.
򐂰 It calls the appropriate JSP to complete the presentation logic.
򐂰 It manages the presentation of the JSPs to add the navigation logic for our
e-business application
Error handling
As you will see later in this book, our development framework works with a
simplified approach to error handling. Basically, we introduce the
CommandException class to handle command exceptions.

However, we recommend that you consider the following points when designing
your structured development approach:
򐂰 Make a distinction between runtime errors and errors that are exceptions
within the context of the application. This simplified approach to error
handling should allow you to display runtime errors on a new HTML error
page, and application exceptions on the current interactive HTML.
򐂰 Errors related to your application exception messages should be contained in
a Java properties file located on the server. An ErrorsManager Java class
could be responsible for providing the appropriate message for a given key
representing the application exception error. This would permit your
e-business application to be NLS (National Language Support) compliant.
򐂰 The Java properties file for error messages should be populated with the
generated error messages text from the VisualAge Pacbase repository that
corresponds to the error server.
򐂰 Errors could be represented by an ErrorBean. This ErrorBean would
encapsulate the key, the label and the ErrorContext. ErrorBeans would be
instantiated through an ErrorBeanFactory.
2.7.3 Development standards

Our structured development approach includes the use of standards, which
provide consistency for our application components and increase the productivity
of our developers. Standards also make our application components more
maintainable and reusable.
We highly recommend addressing the issue of development standards before

you begin your first e-business application and before writing any code.
In the following sections, we present some of the standards we used when

coding the VisualAge Cruise Lines sample application. Many of our standards
are based on the hungarian notation .
VisualAge project standards

The VisualAge project standards are as follows:
򐂰 The name of a project should be semantic and begin with a capital letter.
򐂰 VisualAge for Java permits you to attach comments to any version or edition
of a project. These comments should describe:
– Purpose of the project
– Known bugs and limitations
– History of delivery
– History of changes

Java package standards
The Java package standards are as follows:
򐂰 The name of a package is lowercase, and separate words are indicated by a
capital letter with no intervening spaces or characters. It should be similar to
this: com.companyName.projectName.domainName.semanticName.
򐂰 VisualAge for Java permits you to attach comments to any version or edition
of a package. These comments should describe:
– Purpose of the package and its contents
– Known bugs and limitations
– History of changes
Java class standards

The Java class standards are as follows:
򐂰 The name of a class begins with a capital letter. It should be semantic, explicit
and singular. For example, ThisIsAGoodNameForAClass.
򐂰 Whenever we use a Java class, we import it explicitly in our Java code. We do
not import an entire package (import xxx.*). We find that being explicit makes
our code more self-documenting and eases future maintenance because the
maintainer can see exactly which classes are being used by our e-business
application.
Java method standards

The Java method standards are as follows:
򐂰 The name of a method begins with a lowercase letter. It should be semantic,
explicit and use verbs whenever possible.
򐂰 Always use the prefix get when the method returns a non-boolean result.
򐂰 Always use the prefix is when the method returns a boolean result.
򐂰 Always use the prefix set when the method sets a value.
򐂰 Always comment methods using Javadoc tags.
Java variables standards

The Java variables standards are as follows:
򐂰 The name of a variable begins with a lowercase letter. It should be semantic
and explicit.
򐂰 Always use the prefix iv when the variable is an instance variable.
򐂰 Always use the prefix cv when the variable is static (it means that is a class
variable).

򐂰 Proper usage of variables avoids protected and public modifiers. A variable
should always be private and visibility should be given by accessors
(get/set/is methods).
Class and method comments standards

The class and method comments standards are as follows:
򐂰 Use // inside code to comment the following line.
򐂰 Use /* and */ to disable parts of code during development and testing.
򐂰 Use /** and */ for classes and methods headings. These can be used by
Javadoc to generate the online documentation in HTML format.
򐂰 The following Javadoc tags should always be used for a class:
򐂰 @author
򐂰 @see
򐂰 The following Javadoc tags should always be used for a method:
򐂰 @param
򐂰 @return
򐂰 @exception
򐂰 @see
VisualAge version names standards

We recommend the following rules for version number, regardless of whether the
versioning concerns a class, package, or project:
򐂰 The version number is composed of three numbers separated by dots.
򐂰 The last number (on the right) is incremented whenever a bug is corrected.
򐂰 The second number (in the middle) is incremented for each real change of the
component.
򐂰 The first number (on the left) is incremented for each major change that can
provoke a new release of the project
Example: 1.3.14
򐂰 A stretch comment is added within brackets to describe the change or
correction that provoked the incrementing of the version number.
Example: [bug number 12 corrected] 1.3.15

2.8 Basic VisualAge Pacbase architecture
In this section we introduce the basic VisualAge Pacbase architecture for the
e-business application.
The architecture relates to the sequence of events that handles the message that
originates from the browser, through the proxy, and is processed through the
elementary component under the control of the communication monitor.
The process begins with the HTML post (or get) method. The servlet reacts to
the post and determines the task to execute which relates to a command bean.
The command bean, in turn utilizes the VisualAge Pacbase proxy.
2.8.1 Middleware
The middleware component ensures the communication between the client and
the server using standard communication protocol. This is done by the VisualAge
Pacbase proxy through the vaplocat.ini file. The proxy uses the vaplocat.ini file to
get parameters that are specific to the middleware in use and to pass these
parameters to the DLL which will use the parameters along with the data from the
post to format the message for the specific middleware (for example CICS,
Socket, Tuxedo, or MQSeries).
2.8.2 Listener
The listener recognizes and responds to the message from the middleware by
passing the content of the message to the appropriate communications monitor
which is named as a parameter in the middleware message.
2.8.3 Communications monitor

The communications monitor is triggered by the listener. Once triggered, the
communication manager is responsible for:
򐂰 Services manager
򐂰 Error message server
򐂰 Work file
The services manager handles all of the elementary components associated with
this e-business application.
As the e-business application executes, the work file is used to control and make
available data that needs to be retained throughout the execution of the various
parts of the e-business application.

The error message server is used to handle errors that are specific to the
e-business application by building the key and retrieving the associated text for
an error message to be displayed to the end user.
In summary, the communications monitor is responsible for the following:

򐂰 Message sending and receiving and checking each message (according to
the specific environment). Communication monitors relate to a particular
execution environment and can involve a variety of communication protocols.
򐂰 Controlling the send and receive for each query and managing the work file
associated with the temporary storage for the current query.
򐂰 Interaction with the services manager to handle the sequential processing of
services for a received query.
򐂰 Managing the transaction with regard to commit/rollback so that the server
component controls database integrity issues.

3
Chapter 3. VisualAge Pacbase products:

overview
In this chapter we briefly describe the products that are used throughout this
redbook:
򐂰 VisualAge Pacbase 3.0
򐂰 Rational Rose
򐂰 VisualAge for Java
򐂰 WebSphere Studio
򐂰 WebSphere Application Server
򐂰 DB2 Universal Database
򐂰 MQSeries

3.1 VisualAge Pacbase 3.0
VisualAge Pacbase is a repository-based application development (AD)
environment designed for enterprise-wide scalability, reliability and performance.
VisualAge Pacbase is a proven integrated offering for managing and
industrializing management information system projects of any size. VisualAge
Pacbase offers life-cycle coverage of AD needs from analysis and design to
distribution and production of complete applications of all types (batch,
client/server, and Web). These applications can be generated for a variety of IBM
and non-IBM platforms.
Our VisualAge Pacbase repository and the VisualAge Pacbase server which we
used for our application were both located on a Windows NT server. We gained
access to the repository using the Workbench which was installed on the
Windows NT-workstations we used.
3.1.1 The Workbench

The Workbench is the new user interface replacing the old Paclink, the VisualAge
2.5 Workstation, and even the old VisualAge Pacbase Administrator textual user
interface (TUI). There are in fact three different types of Workbenches: one for
batch programming, one for client/server programming, and one for the
VisualAge Pacbase administrator.
Figure 3-1 illustrates the batch programming Workbench.
Figure 3-1 Batch programming Workbench

Each of the three different Workbenches will be explained in later chapters.
3.1.2 The repository

The consistency of VisualAge Pacbase is ensured by storing all the data in one
specifications database, the repository. All the data means that everything that is
coded within the VisualAge Pacbase environment will be stored in the repository.
This includes:
򐂰 Methodology
򐂰 Data elements
򐂰 Data structures
򐂰 Segments
򐂰 Database blocks
򐂰 Batch programs
򐂰 e-business programs
򐂰 Documentation
򐂰 Reports
򐂰 Libraries
򐂰 Users
All of these can be accessed by one or more of the Workbenches. The fact that
all of these are stored in one database does not mean that everyone on the
system has access to all entities. The repository has an adequate security
system that allows a user to access only those parts of the repository that they
need to do their work. This security system is built around the library structure
that VisualAge Pacbase uses to store all the parts needed to build an application.
The VisualAge Pacbase administrator grants developers certain rights to certain
libraries they need to work. Those rights vary from read only access to being able
to alter the code even in a historical session.
VisualAge Pacbase works with sessions. Sessions are part of the key which
VisualAge Pacbase uses to store lines of code in the repository. A session is a
view of the repository as of a certain point in time. You could compare the
VisualAge Pacbase repository with a collector, for example, a coin collector. This
coin collector makes a daily picture of his collection starting from day one until
the present. As time goes by the collection changes, some coins will be sold and
others will be purchased.
If the coin collector someday wants to look at his collection from a year ago, he
just opens the book where he keeps his pictures. He can go to the date that he
wants and take a look. He can even compare it with his current collection. The
only difference between the coin collection and the VisualAge Pacbase
repository is that if you want to take a look at a historical session in VisualAge
Pacbase you can actually hold the coins and even sell them again and again. In
fact you can reuse almost all things in the repository.
Chapter 3. VisualAge Pacbase products: overview 31

The repository also allows you to see where different entities are being used. For
example, data elements are used to create a dictionary of basic units of data. You
can say that data elements are the building blocks of almost every other
VisualAge Pacbase entity. This requires that VisualAge Pacbase maintain
extensive cross-referencing. Using the cross-referencing you can see, for
example, in which data segments a data element is used. Cross-referencing is
not limited to data elements. Almost all VisualAge Pacbase entities have some
form of cross-referencing. For example, programs are cross-referenced to show
how they use a particular macro, which is a unit of re-usable code. The extent
and ease of use for the cross-referencing makes maintenance much easier.
A new feature of VisualAge Pacbase allows you to create a local repository on

your workstation. This enables you to work with VisualAge Pacbase without
having to be connected to the VisualAge Pacbase server.
The subject of managing the repository is discussed in greater detail in the

chapters that explain the use of the administrator’s Workbench and the
reusability of VisualAge Pacbase.
3.2 Other tools

Providing robust e-business software, requires us to use VisualAge Pacbase in
conjunction with other specific tools. This topic provides an overview and
description of other tools.
The tools presented are:

򐂰 Rational Rose modeling environment
򐂰 VisualAge for Java development environment
򐂰 WebSphere Studio development environment
򐂰 WebSphere Application Server execution environment
򐂰 DB2 Universal Database (UDB)
򐂰 MQSeries messaging environment
These products are not described in detail. For more information on how to install
and develop with VisualAge for Java, WebSphere Studio and WebSphere
Application Server, please refer to Servlet and JSP Programming with IBM
WebSphere Studio and VisualAge for Java, SG24-5755.
3.2.1 About Rational Rose

The Unified Modeling Language (UML) is becoming the industry-standard for
specifying, visualizing, constructing, and documenting the artifacts of software
systems. It simplifies the complex process of software design.

Rational Rose is a product from Rational Software that is UML-based. It allows
you to visualize, understand, and refine your requirements and architecture
before committing them to code.
For more information on Rational Rose and UML, see the product documentation
and visit the Web site:
http://www.rational.com
3.2.2 About VisualAge for Java

VisualAge for Java is a product from IBM. In this book we used the VisualAge for
Java 3.02 Enterprise Edition.
VisualAge for Java provides extensive functionality across the entire

development life-cycle and includes tools for Java code editing and debugging,
JavaServer Page debugging, and the WebSphere Test Environment.
Complementary to VisualAge Pacbase, VisualAge for Java also includes a

repository that stores project source and compiled code.
For more information on VisualAge for Java, see the product documentation and
visit the Web site:
http://www.ibm.com/software/ad/vaJava/
3.2.3 About WebSphere Studio

WebSphere Studio is an IBM product. In this book we used the WebSphere
Studio 3.0 version.
WebSphere Studio is used to develop, manage and deploy the resources for a
Web site.
WebSphere Studio maintains project files in the file system and provides support
for team development and version control tools.
WebSphere Studio also contains a number of wizards that guide you through
tasks such as SQL statement generation and creation of Web pages to interact
with databases and JavaBeans. You can also use the WebSphere Studio Page
Designer to edit these generated pages or create your own HTML and JSP
pages.
For more information on WebSphere Studio, see the product documentation and
visit the Web site:
http://www.ibm.com/software/webservers/studio/

3.2.4 About WebSphere Application Server
WebSphere Application Server (WAS) is a product from IBM. In this book we
used the WebSphere Application Server 3.02 Enterprise Edition.
WebSphere Application Server enables Web transactions and interactions with a

robust deployment environment for e-business applications. It provides a
portable, Java-based Web application deployment platform focused on
supporting and executing servlets, JavaBeans, and JavaServer Pages (JSP)
files.
For more information on WebSphere Application Server, see the product

documentation and visit the Web site:
http://www.ibm.com/software/webservers/appserv/
3.2.5 About DB2 Universal Database

DB2 Universal Database (UDB) is an IBM product. In this book we used the DB2
6.1 version.
DB2 UDB is a relational database management system. It is fully scalable, has

full multimedia capabilities and is also very Web-enabled, including built-in Java
support.
For more information on DB2 UDB, see the product documentation and visit the
Web site:
http://www.ibm.com/software/data/db2/udb/
3.2.6 About MQSeries

MQSeries is a product from IBM. It is possible and practical to use MQSeries in
conjunction with VisualAge Pacbase in certain situations involving legacy
systems and diverse platforms. MQSeries messaging middleware provides a
highly reliable asynchronous communications function for
application-to-application connections.
For more information on MQSeries, see the product documentation and visit the
Web site:
http://www.ibm.com/software/ts/mqseries/

3.3 Tools integration
Earlier, we said that providing robust e-business software requires us to use
VisualAge Pacbase in conjunction with other specific tools. This topic explicitly
describes the various interactions between the different products we use.
3.3.1 Integration of Rational Rose with VisualAge Pacbase

Rational Rose can be used as a modeling tool in conjunction with VisualAge
Pacbase. Initial modeling steps can be accomplished with Rational Rose, using
the Unified Modeling Language (UML) methodology. Next, a bridge permits you
to import models from Rational Rose to populate the VisualAge Pacbase
repository. This process is described in Part 2 of this redbook.
3.3.2 Integration of Rational Rose with VisualAge for Java

Rational Rose can be used in many ways with VisualAge for Java.
One way is to use Rational Rose for modeling during the analysis and design
steps. As you proceed, you can use the XML/Toolkit to generate Java classes
from the model and import these classes into VisualAge for Java.
The reverse of this is also available. You can obtain a model from developed
classes through a reverse-engineering process.
3.3.3 Integration of VisualAge for Java with WebSphere Studio

WebSphere Studio provides two-way communication with VisualAge for Java,
allowing you to keep your Java source files synchronized between WebSphere
Studio and the VisualAge for Java Repository.
You should use this feature to ensure that VisualAge for Java is your primary
Java development and test tool. This allows you to:
򐂰 Receive updates from VisualAge for Java
򐂰 Send updates to VisualAge for Java
򐂰 Use VisualAge for Java as an editor
For more detailed information on this integration please refer to Servlet and JSP
Programming with WebSphere Studio and VisualAge for Java, SG24-5755.

3.3.4 Integration of VisualAge for Java with WAS
VisualAge for Java integrates much of the WebSphere Application Server
Advanced runtime so that debugging servlets and JSPs (and EJBs) is possible in
a highly integrated development environment. The WebSphere Test Environment
(WTE) in VisualAge for Java actually encompasses the servlet and JSP runtime
and test environments.
There are two different ways to configure and run the WTE:
򐂰 SERunner
򐂰 ServletEngine
Both are detailed in Servlet and JSP Programming with WebSphere Studio and
VisualAge for Java, SG24-5755.
After testing code using the WTE, it is deployed from VisualAge for Java to
WebSphere Application Server, by exporting Java files.
3.3.5 Integration of WebSphere Studio with WAS

Two levels of integration are available:
򐂰 Web applications built in WebSphere Studio can be deployed to WebSphere
Application Server.
򐂰 The WebSphere Studio proposes a remote debugger for easy remote
debugging of server-side scripts and logic, including JSPs, servlets and
JavaBeans. This remote debugger requires the WebSphere Application
Server.
For more detailed information on this integration please refer to Servlet and JSP
Programming with WebSphere Studio and VisualAge for Java, SG24-5755.
3.3.6 Integration of WebSphere Application Server with DB2

Two levels of integration are available:
򐂰 The WebSphere administrative console program maintains the configuration
of the Application Server in a DB2 (or Oracle) database. The configuration
contains information about servers, Web applications, servlets, EJBs, the JSP
compiler, DataSources, and other resources.
򐂰 The code in Web applications can access enterprise resources such as
relational databases (DB2 and others).

For more detailed information on this second point, refer to IBM WebSphere and
VisualAge for Java Database Integration with DB2, Oracle, and SQL Server,
SG24-5471.
3.3.7 Complete product environment

Figure 3-2 summarizes the development environment.
ANALYSIS
AND Rational
Analysis Model
DESIGN Rose
-----> Design Model
IMPLEMENTATION VisualAge Pacbase
HTML, WebSphere
JSP Studio
Proxy
Servlet
JavaBean
Business Components
Servlet, Folder
VisualAge
JavaBean Database
for Java
TESTING
Servlet JSP Proxy
WebSphere
JSP VAP Test
Text
Monitor Tool
Environment
Figure 3-2 Summary of development environment

Figure 3-3 summarizes the runtime environment.
DEVELOPMENT
WebSphere VisualAge VisualAge
Studio for Java Pacbase
DEPLOYMENT
Servlets
HTML Folders
JavaBeans
JSPs Elementary Components Database
Proxies
VAP Middleware
(Socket)
DB2
WebSphere
HTTP
Application Server
HTML Browser VisualAge Pacbase

Business Application
MQ Series
DB2
Figure 3-3 Summary of runtime environment

4
Chapter 4. Environment setup,

installation, and
administration
In this chapter we describe the installation and setup of VisualAge Pacbase 3.0
for Windows NT. In addition, we discuss the configuration of VisualAge Pacbase
to work with our other tools, VisualAge Java and WebSphere Studio and how to
set up these tools to work with VisualAge Pacbase. We also provide information
on VisualAge Pacbase administration using the administrator Workbench.

4.1 Installation/setup: VisualAge Pacbase 3.0 repository
In this section we describe the steps necessary to install the VisualAge Pacbase
repository on a server in the Windows NT environment.
We installed the software on the C: drive (the default) for this redbook. If you wish
to install on another drive, substitute the appropriate drive letter.
4.1.1 Special considerations

VisualAge Pacbase installs from the CD supplied by IBM, so the machine you are
using will need access to a CD drive.
You should sign-on to the machine as the Windows NT administrator or a user-id

that has administrator access.
To install the VisualAge Pacbase server you will need Windows NT or Windows
2000 (there is no Windows 3.x or Windows 95/98 version available). You will also
need Windows Installer 1.1 or higher and Windows Script Host 5.1 minimum.
To support VisualAge Pacbase you will need approximately 500 MB of hard drive
space. This can be on any available drive or combination of drives. The initial
installation will consume nearly 100 MB and the rest of the space will be used for
the data files which will become larger as you begin to populate the VisualAge
Pacbase repository.
The installation takes approximately twenty to forty minutes to complete and can
be accomplished in stages.
4.1.2 Running the installation

The installation software is distributed on CD-ROM. From the CD-ROM, you will
execute the SETUP.EXE installation program.
Please refer to the VisualAge Pacbase Environment & Installation Guide (chapter
Installation) for a complete description of the installation procedures.

As the installation begins, you will see the following information, as shown in
Figure 4-1.
Figure 4-1 Starting the installation
Chapter 4. Environment setup, installation, and administration 41

To begin the installation, click Next>.
As the installation begins, you will be asked to provide a user name and the
name of your organization, as seen in Figure 4-2.
Figure 4-2 Providing a user and organization
The user and organization are shown only for documentation purposes.
The installation proceeds in three stages:

1. Installing the system, that is, the software
2. Installing the administration database
3. Installing the development database

Installing the software
Figure 4-3 begins the installation sequence to install the software, referred to as
the VisualAge Pacbase System.
Figure 4-3 Installing the VisualAge Pacbase system
Note that the default location for the system is:

C:\Program Files\IBM\VisualAge Pacbase\
You can change the location by clicking the button labeled Change ...

The procedure gives you the option of revising your choice of location before
proceeding with the install, as seen in Figure 4-4.
Figure 4-4 Confirming the system installation

If you are ready to proceed with the installation, click the button labeled Install.
This results in the progress panel in Figure 4-5.
Figure 4-5 Progress of the system installation
Even though the procedure says it may take several minutes, it finishes quickly.
When the installation of the VisualAge Pacbase system is complete, you will see
another panel that tells you that the system has been installed.

This same panel gives you the option of proceeding with the installation of the
administration database, seen in the Figure 4-6.
Figure 4-6 Completing the system installation
You can defer the installation of the administration database by clicking the
button labeled Later.
Installing the administration database

In the preceding figure, clicking the button labeled Now ... will begin the
installation process for the administration database. This establishes the files
that will be used by the VisualAge Pacbase administrator to manage the system,
control access to the system, and execute various utilities called batch
procedures. Unlike earlier versions of VisualAge Pacbase, in VisualAge Pacbase
3.0 the administration database is now a single-session single-library database

Clicking the button labeled Now ... results in the panel seen in Figure 4-7.
Figure 4-7 Beginning the administration database installation
Clicking Next will begin the install process for the administration database. Note
that the administration database will only be installed once. This single
administration database is used to manage the VisualAge Pacbase repository,
regardless of how many development databases it contains.
The process requires you to provide:

򐂰 VisualAge Pacbase key
򐂰 Listener Port number
򐂰 Default language
The VisualAge Pacbase key is a sequence of seventy characters that activates

various options associated with the product and controls the product license and
its expiration date. The VisualAge Pacbase key is supplied by IBM with the
software when it is purchased.

The port number designates the port which will be used for the listener for
VisualAge Pacbase. You can take the default or specify another port number.
Note that the value of the listener port number must be between 6000 and 9000.
In addition, it must be distinct from any other VisualAge Pacbase development
database.
You must also choose the default language for the administration database,
either English (the default) or French, as shown in Figure 4-8.
Figure 4-8 Options for the administration database

After you have entered the key, the listener port number, and chosen a language,
click Next> to proceed. Figure 4-9 is the panel that results.
Figure 4-9 Choosing the administration database location
Note that the default location for the administration database is the same as that
for the VisualAge Pacbase system,
It is not required that the system and the administration database be in the same
location. To change the location, click the button labeled Change ...

To proceed with the install, click Next>. Figure 4-10 is the panel that results.
Figure 4-10 Specifying additional locations
The preceding figure shows the panel used to indicate the location of the
following components of the administration database:
򐂰 Journal directory
򐂰 Backups directory
򐂰 Temporary directory
򐂰 Users directory
Note that the default locations for these are the same as the administration
database,

The journal directory specifies the location of the files that are used to record the
transactions against the administration database in a chronological sequence.
The journal provides the capability to recover the administration database in the
event of a problem and ensures that the recovered database is accurate. It is
recommended that the journal directory be placed in a location that is distinct
from both the administration database and the backups directory to provide
better coverage in the event of a problem.
The backups directory specifies the location of the files that are used for the
backup of the administration database. These backups are sequential images of
the corresponding database and are used to recover the content of the database
in the event of a problem. It is recommended that the backups directory be in a
location distinct from the administration database and the journal directory.
The temporary directory specifies the location of the files that are used for work
areas, sorting, and to contain the reports that result from the use of various batch
procedures (utilities). It should be located on a drive that has sufficient space to
handle the sorting of large files used by the batch procedures.
The users directory specifies the location of the files that are used for the results
of generation from the repository. This directory should be located so that it is
accessible by the users it supports.

Any of the locations previously discussed can be changed by clicking the
Change ... button next to the directory that you would like to change. If you
decide to change a location by clicking the button, you will be presented with the
panel shown in Figure 4-11.
Figure 4-11 Changing a directory location

To change the location, enter the new location in the field labeled Folder name
and click OK. This will return you to the panel for all of the directory locations. On
that panel, click the Next> button to continue. You will see the panel shown in
Figure 4-12.
Figure 4-12 Proceeding to install the administration database

Click the Install button to continue the installation for the administration
database. When the installation process is complete, Figure 4-13 will be
displayed and you will have the option of installing a development database or
ending the install process.
Figure 4-13 Successful installation of the administration database
If you wish to end the install procedure, click the Finish button. If you wish to
install a development database, click the button labeled Yes. Note that you can
create development databases anytime by using the indicated shortcut in the
Start menu by selecting Programs -> VisualAge Pacbase 3.0 -> Create New
Database.

Installing a development database
Installing a development database refers to the process of establishing a set of
files that will be used by developers to build and maintain entities within the
VisualAge Pacbase repository. These entities become the building blocks of the
applications which are generated from the VisualAge Pacbase repository.
Development databases are distinct from the administration database installed
earlier. The VisualAge Pacbase repository can contain multiple development
databases, but will only contain one administration database.
Many projects and developers will share the same development database.
Indeed, a major advantage of the VisualAge Pacbase repository is that it is a
multi-user environment. As users work in the repository they are working with the
authoritative source of the development components and will see the results of
the work of other developers with each new download to their workspace.
The installation begins with the panel shown in Figure 4-14.
Figure 4-14 Installing a development database

To begin installing a new development database, click Next>. The following
panel, in Figure 4-15, will be displayed.
Figure 4-15 Specifying a development database
The preceding panel is used to specify the characteristics of the development

database. You will need to provide:
򐂰 Name of the database
򐂰 Listener port number
򐂰 Database language
򐂰 Generation language
The name of the database refers to the folder that will contain the files used for
the development database. You can use a maximum of eight characters and you
should use a name that has significance. In the example from the preceding
figure, we named our development database REDBOOK.
The listener port number must be a value between 6000 and 9000 and must be
unique from the listener port number assigned to the administration database.
You can use the default value supplied or specify a different value for the listener
port. In our example, we assigned 7030 as the listener port number.

The database language can be either English (the default) or French. This
controls the language used for the labels and messages displayed on panels as
developers work with this database. We used English for our example.
The generation language is also either English (the default) or French. This
controls the language that will be used during the generation of entities from the
VisualAge Pacbase repository. Again, we used English for our example.
After you have completed the specifications for this panel, click Next> to proceed
with the install process. This produces the panel in Figure 4-16.
Figure 4-16 Default location for the development database
The default location for the development database is:

You can change the location by clicking the Change ... button.

To proceed with the installation, click Next> to see the panel in Figure 4-17.
Figure 4-17 Additonal directory locations
The development database contains several directories for its files. These all
default to the location:
The location for any of these directories can be changed by using the Change...
button and entering a new location.
The directories for the development database include:

򐂰 Journal directory
򐂰 Backups directory
򐂰 Temporary directory
򐂰 Users directory
Note that the default locations for these are the same as the administration
database:

The journal directory specifies the location of the files that are used to record the
transactions from each user that update the development database. These are
recorded in chronological sequence. The journal provides the capability to
recover the development database in the event of a problem and ensures that
the recovered database is accurate. It is recommended that the journal directory
be placed in a location that is distinct from both the development database and
the backups directory to provide better coverage in the event of a problem
The backups directory specifies the location of the files that are used for the
backup of the development database. These backups are sequential images of
the corresponding database and are used to recovery the content of the
database in the event of a problem. It is recommended that the backups directory
be in a location distinct from the development database and the journal directory.
The temporary directory specifies the location of the files that are used for work
areas, sorting, and to contain the reports that result during the generation of
entities from the development database. It should be located on a drive that has
sufficient space to handle the sorting of any large files that may be used during
generation.
The users directory specifies the location of the files that are used for the results
of generation from the repository. This directory should be located so that it is
accessible by the users it supports.
Click Next> to continue.
This will present the panel shown in Figure 4-18, where you will confirm the
installation of the development database.

Figure 4-18 Confirming the development database installation
Click Install to proceed with the installation.
Panels will display the progress of the installation and when the process
completes you will see Figure 4-19.

Figure 4-19 Successful installation of development database
Click Finish to exit the installation procedure. This ends the installation of the
software and the creation of the necessary databases for administration and
development activities. Before using the product, you will need to complete the
installation of the Workbenches for VisualAge Pacbase.
Verifying the installation

Before discussing the installation of the Workbenches for VisualAge Pacbase, it
is appropriate to check the results of the installation.
In this section we describe how to check that the product installed correctly.
It includes a description of the files created, where they are located, and a brief
description of their use. The examples in this chapter relate to the default
locations for the directories and file locations. If you specified alternate locations,
then you should verify your install based on your specifications. Also, depending
on the VisualAge Pacbase product options you have acquired, your hardware
platform, communications, and operating system environment, your installation
results may vary from the ones in our examples.

Verifying the system installation
After the install process for the system finishes you should verify that certain
directories have been established. Figure 4-20 shows the directory structure that
results from the system install. You must not modify these directories or the files
they contain.
Figure 4-20 System directories
The preceding figure shows the system installed in the default directory:
A folder is established named Sys, which contains the following folders:

򐂰 Nls
򐂰 Pgm
򐂰 Proc
򐂰 Setbases
򐂰 Skel
Nls refers to national language support, and this folder contains message files in
both English and French as well as a file to handle character conversion. The
files in the Nls folder are shown Figure 4-21.
Figure 4-21 Content of the Nls folder

Pgm refers to programs, and this folder contains all of the executables for
VisualAge Pacbase.
A partial view of the Pgm folder is shown in Figure 4-22.
Figure 4-22 Content of the Pgm folder
Proc refers to batch procedures. These are utilities that accomplish routine
activities such as backing up the database and extracting its content. Figure 4-23
shows a portion of the content of the Proc folder.
Figure 4-23 Content of the Proc folder
Setbases contains the installer and the .cab file used for the install, as seen in
Figure 4-24.
Figure 4-24 Content of the Setbases folder

Skel refers to skeletons. When VisualAge Pacbase generates application
components the process involves merging content from two sources, the entity
specifications from the VisualAge Pacbase database and a skeleton file which
contains information specific to the options chosen as part of the generation
request. These options relate to the hardware platform, communications, and
operating system combination.
Figure 4-25 shows a sample of the content of the Skel folder.
Figure 4-25 Contents of Skel folder
The actual content of the Skel folder varies considerably based on the VisualAge
Pacbase product options installed at a site.
Verifying the administration database install

Figure 4-26 shows the directory structure that results from installing the
administration database.

Figure 4-26 Administration database directory structure
Note in the preceding figure that the Admin folder that contains the directories for
the administration database is itself contained in a folder called Data. All of the
VisualAge Pacbase databases will be placed in the Data folder. The Data folder
basically contains all of the things that you will use directly. These are the files
that will change and grow as information is stored in the VisualAge Pacbase
repository.
Specifically, the Admin folder contains the following folders:

򐂰 Base
򐂰 Input
򐂰 Journal
򐂰 Save
򐂰 Tmp
򐂰 Users
Base refers to the files that contain the content of the administration database.
Figure 4-27 shows the content of the Base folder.
Figure 4-27 Contents of Base folder

Input refers to the files that contain input transactions and parameters for specific
batch procedures. Each of these files is explained in detail in the VisualAge
Pacbase documentation. The content of the Input file after the administration
database is shown in Figure 4-28.
Figure 4-28 Content of the Input folder
Journal refers to the chronological record of activity for the administration

database. The Journal is used to recover the administration database in the
event of a problem.
The content of the Journal folder is shown in Figure 4-29.
Figure 4-29 Content of the Journal folder
Save refers to the files that represent the backup of the administration database.
These files are used to recover the administration database in the event of a
problem. The content of the Save folder is shown in Figure 4-30.
Figure 4-30 Content of the Save folder

Tmp refers to the location of the temporary files used as work areas, for sorting,
and to store reports that result from executing batch procedures.
The content of the Tmp folder is shown in Figure 4-31.
Figure 4-31 Content of the Tmp folder
In the preceding figure, many of the files will not be present immediately after the
installation of the administration database. As you complete the installation and
begin to run batch procedures you will see files begin to appear in this folder.
Users refers to the folder that will contain the results of generating entities from
VisualAge Pacbase. Since no generation has been requested at this point in the
installation, this folder will be empty.
Verifying the development database install

Figure 4-32 shows the directory structure that results from installing the
development database.

Figure 4-32 Development database directory structure
Note that the development database resides in a folder that corresponds to the
name specified during the installation process, in this example Redbook. Like all
VisualAge Pacbase databases, the Redbook development database is
positioned within the Data folder. Since the administration (Admin) database was
installed prior to the Redbook development database in our example, we see the
Admin database in the figure.
As you can see in the preceding figure, the folders that result from the installation
of the Redbook development database are similar in name and function to the
ones associated with the administration database and so they will not be
discussed again in this section.
Additional results
The install process adds an entry for VisualAge Pacbase to your Start menu in
Windows NT.
Selecting the Admin option allows you to:

򐂰 Execute Admin database utilities
򐂰 Start the Admin database so that it becomes accessible from the
administrator Workbench
Selecting the Redbook option allows you to:

򐂰 Execute Redbook database utilities
򐂰 Start the Redbook database so that it becomes accessible from the
administrator, developer, and e-business Workbenches
If you select the Create New Database option, the Install SmartGuide begins the
process to install another development database.

4.2 Installing the VisualAge Pacbase Workbench
In this section we describe the steps necessary to install the VisualAge Pacbase
Workbench components in the Windows NT environment. The install process is
used to install Workbenches for:
򐂰 Administration
򐂰 Batch
򐂰 e-business
The machines we used had the following characteristics:

򐂰 IBM Personal Computer 300PL
򐂰 x86 Family 6 Model 7 Stepping 3
򐂰 AT/AT Compatible
򐂰 640 MB RAM
򐂰 Windows NT 4.00.1381
򐂰 Internet Explorer 5.0
4.2.1 Installation
In this section we describe how to run the installation procedure for the
VisualAge Pacbase Workbenches.
The installation procedure begins by running the Workbench SETUP.EXE found

on the VisualAge Pacbase installation CD.

Running the SETUP.EXE begins the SmartGuide used for the installation
procedure. This is shown in Figure 4-33.
Figure 4-33 SmartGuide for Workbench installation

Clicking Next displays a panel where you will need to confirm your acceptance of
the Java license agreement, as shown in Figure 4-34.
Figure 4-34 Java license acceptance

You must indicate that you accept the license and click Next to proceed. This
displays the panel shown in Figure 4-35.
Figure 4-35 User options for the Workbench
The Workbench installation gives you the options of installing the Workbenches
for either all users on the machine or for a specific user. Depending on your
organization’s policies, for example, you may install the administration
Workbench only for users that will function as VisualAge Pacbase administrators.
For the batch and e-business workstations, you may decide to install these for all
users of the machine without specifying a user.
For our redbook example, we installed the Workbench so that anyone using the
machine would be able to access the administration, batch, and e-business
Workbenches.

Once you have indicated your choice of user installation option, clicking Next
displays the panel shown in Figure 4-36.
Figure 4-36 Indicating the destination folder
The panel in the preceding figure is used to indicate the location of the files that
will be installed for the Workbench. The default location is:
C:\Program Files\IBM\VisualAge Pacbase\Workbench\
You can change the location by clicking the Change ... button and specifying a
new path. For our redbook example, we used the default location.

To continue with the installation procedure, click Next. This displays the panel
shown in Figure 4-37.
Figure 4-37 Selecting the Workbench modules
Using this panel, you can specify which Workbench modules you want to install.
Note that you also have the option of installing the Rational Rose Bridge as part
of the e-business module. This feature is discussed more fully in chapter 15 of
this redbook. For our redbook example, we chose to install all of the Workbench
modules and the Rational Rose Bridge.

To continue, click Next. This displays the next panel for the installation process,
seen in Figure 4-38.
Figure 4-38 Specifying the communications type
The next part of the installation procedure requires you to indicate the type of
communication that you will be using, either a gateway or middleware (the
default).

Selecting Gateway and clicking Next displays the panel shown in Figure 4-39.
Figure 4-39 Additional communications information
Here, you need to provide the database name and a four-character code for the
database. You can also indicate whether or not the middleware has any security
associated with it.

Click Next to continue and the panel shown in Figure 4-40 is displayed.
Figure 4-40 Specifying the gateway IP address and port

After specifying the IP address and port, click Next to continue. This displays the
panel shown in Figure 4-41.
Figure 4-41 Connecting additional databases
When you install the Workbench modules in VisualAge Pacbase, you are setting
up connections to the administration and development databases used by your
organization. The installation process allows you to iterate through the
installation process in order to install the Workbench modules for the appropriate
administration and development databases. Click No to proceed with the
installation or click Yes to indicate that you wish to connect another database.

The earlier example showed the selection of a gateway for the type of
communications. If you select Middleware as the type of communications, the
panel shown in Figure 4-42 is displayed.
Figure 4-42 Middleware communications type
In fact, this screen is very similar to the one displayed if gateway is selected as
the type of communications. One major difference is that the Location name
must be specified and the Edit host ... button is active when middleware is
selected.

Clicking the Edit host... button displays a panel that gives you an example of the
type of entries for the Location name, as seen in Figure 4-43.
Figure 4-43 Edit host options
The Location name field corresponds to the example names between the < and
>. The series of SmartGuide panels that specify the communications type and
the options associated with either the gateway or middleware are used to create
the basis.ini and vaplocat.ini files which control the connection activity during the
startup of the Workbench modules.

Earlier, it was mentioned that the Workbench install process allows you to iterate
through the databases for connection. When you complete this iterative selection
of databases, you will see the panel in Figure 4-44.
Figure 4-44 Proceeding with the Workbench installation
To proceed with the installation, click Next. The installation will proceed by
displaying a panel with a progress bar as it copies the necessary files.
When the process finishes, the panel in Figure 4-45 is displayed.

Figure 4-45 Completion of the installation of Workbench
Click Finish to end the Workbench install procedure.
At this point the Workbenches are not actually installed and operational on the
workstation. In order to complete the process you need to click Start ->
Programs -> Workbench and then select each of the Workbenches you want to
make operational for this workstation. The first time you select an Workbench in
this manner, the autoinstaller is activated, which will copy the specific files for
each Workbench module. This is true only for the first time you select the
Workbench module. After that, selecting Start -> Programs -> Workbench and
then selecting an Workbench module will start that Workbench.
Verifying the Workbench installation

In this section we describe the results of installing the VisualAge Pacbase
Workbenches. The examples in this section reflect the default location of
C:\Program Files\IBM\VisualAge Pacbase\Workbench\
If you changed the destination folder, then you will need to verify your installation
accordingly.

The Workbench installation procedure establishes the directory structure shown
in Figure 4-46.
Figure 4-46 Directory structure from Workbench installation
The Workbench modules are installed in:

C:\Program Files\IBM\VisualAge Pacbase\Workbench\workstation
The directory structure for this appears in Figure 4-47.
Figure 4-47 Directory structure for the workstation

In addition to the directory structure in the preceding figure, the workstation
subdirectory contains various files, as seen in Figure 4-48, which is a partial
listing of the files for the workstation.
Figure 4-48 Partial listing of files for workstation
Of particular interest in this collection of files are the bases.ini and vaplocat.ini
files, which manage the connection activity during the workstation startup. The
base.ini is basically the logical description of the connection and the vaplocat.ini
corresponds to the physical description of the connection.
Customizing the Workbenches

This section contains a brief discussion of how to customize the appearance of
the Workbench and pertains to the administrator’s Workbench, the developer
Workbench, and the e-business Workbench.
Each Workbench operates through a set of tabs that allow you to work with the
entities managed within the VisualAge Pacbase repository. The initial set of tabs
are the result of the Workbench installations.
VisualAge Pacbase includes a facility to add tabs, remove tabs, and change the
order of tabs for any of the Workbenches.
The configuration manager

In order to change the tabs for the Workbench you must execute:
..\Workbench\cfm.bat
This starts the configuration file manager, seen in Figure 4-49.

Figure 4-49 Configuration file manager
By default, the configuration file manager opens to the options associated with
the developer Workbench. To change to either the administrator Workbench or
e-business Workbench, select File -> Open and navigate to:
..\Workbench\workstation\modules
In this directory, you will see three directories:

򐂰 Admin, which corresponds to the administrator Workbench
򐂰 Batch, which corresponds to the developer Workbench (opened by default)
򐂰 e-business, which corresponds to the e-business Workbench

Each of these directories contains the file named default.cfg, as seen in Figure
4-50.
Figure 4-50 Opening default.cfg for the Workbench
In order to change the tabs for the Workbench, you will need to open this file.

Opening the default.cfg file results in the panel in Figure 4-51. In the list of
workbooks, selecting the entry for Workbench will display the current list of tabs
for the Workbench associated with the default.cfg file. Right-clicking the entry for
Workbench will display a small context menu that will allow you to add pages
(tabs).
Figure 4-51 Tabs for the Workbench

Selecting Add Pages will present another panel with a list of the tabs that can be
added to the Workbench. For example, to add the Programs tab to the
e-business Workbench, select it by clicking it and then click OK, as seen in
Figure 4-52.
Figure 4-52 Adding the Programs tab
This will cause an entry for Programs to be added to the list of tabs, as seen in
Figure 4-53.

Figure 4-53 Programs tab added to the Workbench

The Programs tab is currently located as the rightmost tab. You can move it to the
left in the tab order by using the toolbar Up button. We used multiple clicks to
position the Programs tab as shown in Figure 4-54.
Figure 4-54 Repositioning a tab

To remove any of the tabs, right-click the tab and select Remove page from the
context menu as seen in Figure 4-55.
Figure 4-55 Removing a tab

4.3 Impacts on other tools
In this section, we do not describe the entire installation process for all of the
related tools. We placed the emphasis on installation phases that are specific
and necessary for building e-business applications with VisualAge Pacbase.
4.3.1 Installing the WebSphere test environment feature

This section reviews how to install the WebSphere Test Environment Feature in
VisualAge for Java.
First, use the File menu from the menu bar, then click the Quick Start ->
Features -> Add Feature. The display changes as shown in Figure 4-55.
Figure 4-56 Adding a feature to the VisualAge for Java Workbench
As a result of this action, a dialog box appears that allows you to choose the
feature to add to the Workbench. Select the IBM WebSphere Test Environment
feature, as displayed in Figure 4-57.

Figure 4-57 Selecting the WebSphere Test Environment feature
Clicking the OK button adds the feature to your VisualAge for Java Workbench.
4.3.2 Installing the VisualAge Pacbase Java environment

The VisualAge Pacbase installation CD contains the files(.jar) to install the
appropriate Java code in the VisualAge for Java environment.
These .jar files are the following:

򐂰 Vapruntime.jar, which contains all the generic Java classes for VisualAge
Pacbase Java runtime environment (Folder, for example)
򐂰 Vapgen.jar, which contains all Java classes constituting the Proxy Generator
Tool
򐂰 Vapswing.jar, which contains all graphic Java classes for jdk1.1.x
򐂰 Vapswgx.jar, which contains all graphic Java classes for jdk1.2

You can use any of three ways to install these files in VisualAge for Java:
򐂰 Importing .jar files in the VisualAge for Java class path
򐂰 Importing .jar files in VisualAge for Java projects, which is the most common
way
򐂰 Making VisualAge Pacbase .jar files a feature for VisualAge for Java
Importing jar files into the class path

To import VisualAge Pacbase .jar files in your VisualAge for Java workspace
class path, you need to select the Window menu from your Workbench menu
bar, and then click the Options menu choice.
In the Options window, select the Resources choice and edit the workspace
class path as shown in Figure 4-58.
Figure 4-58 Editing the workspace resources (options window)

Then, you need to add your .jar files using the Add Jar/Zip button, as seen in
Figure 4-59.
Figure 4-59 Editing the workspace class path
Click OK, Apply, OK, and your workspace is ready for you to use the VisualAge
Pacbase Java classes.
Importing jar files into VisualAge for Java projects

The second way to prepare the VisualAge for Java workspace for the VisualAge
Pacbase Java classes is to import them into VisualAge for Java Projects.
Here, we describe the import process for the generic runtime .jar file. The
process is the same for the other ones.
First, create a project called VisualAge Pacbase Runtime.Click the Selected

menu from the Workbench menu bar, then click Add-->Project.
After that, select this new project, click the Selected menu, and then the Import
menu choice. This opens the Import SmartGuide. Select the .jar file choice, and
click Next.

Then select the options as displayed in Figure 4-60.
Figure 4-60 Importing jar file options
Clicking the Finish button imports the Java packages into your project, seen in
Figure 4-61.

Figure 4-61 VisualAge Pacbase runtime project
Follow the same import process for the other .jar files and your workspace is
ready to use. Notice that when importing the swing .jar file, VisualAge for Java
will ask you to modify the graphic palette, useful for visual programming.
Note: When working in the Team mode with a shared repository, this process
only needs to be done once. Team developers would only need to import the
VisualAge Pacbase projects from the repository into their workspaces.
Making VisualAge Pacbase Java environment a feature

The last way to prepare the VisualAge for Java workspace for using VisualAge
Pacbase Java classes is to make the VisualAge Pacbase Java environment a
feature of VisualAge for Java.
This can be done once after importing the .jar files into VisualAge for Java
projects. Then team members will have to add the created feature just as they
did for the WebSphere Test Environment feature.

To build the feature, follow this process:
1. Export the VisualAge Pacbase projects into one repository called
projects.dat.
2. Create a default.ini file.
3. Build a deployment directory.
4. Deploy the feature on each workstation.
5. Install the feature.
For further detail on this process, refer to the VisualAge for Java product
documentation: Toolint.pdf.
Installing the VisualAge Pacbase middleware

The VisualAge Pacbase middleware is delivered on the VisualAge Pacbase
installation CD. The middleware consists of DLL files. VisualAge Pacbase
provides different DLL files for different communication protocols. We only
discuss the installation of the DLLs needed for the SOCKET protocol in the
Windows NT environment. The process is similar for other environments.
Installing the communication DLLs

During the Workbench installation, DLLs for the communications middleware are
installed by default in:
C:\Program Files\Ibm\VisualAge Pacbase\Workbench\dll
For the Java developers, you should create a new directory on their workstations
(for example, D:\RedbookVapb\), which will contain all the middleware files.
For example, using the SOCKET protocol, you would copy the following files in
this new directory:
򐂰 JavaAdapter.dll
򐂰 ixomsgen.dll
򐂰 ixomware.dll
򐂰 ixosock.dll
򐂰 MwAdapter.dll
򐂰 VapUtil.dll
Gateway considerations
For the gateway, you would add the following files in the previously created
directory (D:\RedbookVapb):
򐂰 Charconv.txt, the code pages conversion file
򐂰 VapGateway.exe, the gateway program
These files can be found on the installation CD for VisualAge Pacbase.

Figure 4-62 summarizes the gateway program usage.
Figure 4-62 VapGateway.exe parameters
In the same D:\RedbookVap directory, it is useful to create a gateway command

file (VapGateway.bat, for example) to launch the gateway.

A good example of a simple command file would be:
@echo off
d:
cd A\RedBookVapb
VapGateway -s 5647 -l "vaplocat.ini" -t 9 -c "charconv.txt"
@echo on
This is what the preceding code accomplishes:

򐂰 The -s parameter indicates that this is starting the gateway outside NT
services.
򐂰 5647 is the default TCPIP port number: it is recommended to explicitly identify
the port number.
򐂰 The -l parameter identifies the location file.
򐂰 The parameter “vaplocat.ini” follows the -l and means that the location file is
called “vaplocat.ini” and is in the same directory as our command file.
򐂰 The -t identifies that we use a trace level and the 9 following it means that we
use a high trace level. Notice that no trace file is identified, which means that
the default directory and trace file will be used.
򐂰 The -c parameter indicates that we use a code page conversion file and the
“charconv.txt” following means that the code page conversion file is called
“charconv.txt” and is in the same directory as our command file.
4.4 VisualAge Pacbase 3.0: Site administration

In this section we discuss the use of the VisualAge Pacbase Workbench for the
VisualAge Pacbase administrator. There are two aspects of VisualAge Pacbase
administration. The first aspect covers the administration of the repository as a
whole, referred to as site administration. The second aspect is referred to as
base administration and concerns the administration of a specific VisualAge
Pacbase database.
Part 2 of this redbook describes the sample application that we developed as

part of this redbook effort. The sample application concerns a fictitious company
known as VisualAge Cruise Lines. We used the administrator Workbench to
describe and administer the repository that we used to define the VisualAge
Cruise Lines sample application, which contains the components used to
generate the sample application.

4.4.1 Starting the administrator Workbench
After VisualAge Pacbase has been successfully installed, you will start the
VisualAge Pacbase server for the administration database before using the
administrator’s Workbench. To start the server select Start -> Programs ->
VisualAge Pacbase 3.0 -> Admin -> Start ADMIN Database.
In order to use the administrator’s Workbench for VisualAge Pacbase, the

VisualAge Pacbase you will need to start it. There are two ways to start the
Workbench for VisualAge Pacbase. We started the administrator Workbench
using a desktop icon.
From a desktop icon

You can place a shortcut icon on the Windows NT desktop and use it to start the
Workbench for VisualAge Pacbase. To add the shortcut do the following:
1. Open Windows NT Explorer and locate the file ws_admin.bat.
2. Right-click the file and select Create Shortcut from the context menu that
appears.
3. Select the newly created shortcut to ws_admin.bat.
4. Drag the shortcut to the desktop.
5. Optionally, you can cut and paste the shortcut onto to the desktop.
Double-click the desktop icon for the shortcut to start the VisualAge Pacbase
Workbench.
From the start menu

You can start the Workbench for VisualAge Pacbase from the start menu from
the Windows NT task bar by clicking Start -> Programs -> Workbench.
Selecting that will bring up another list which has each installed Workbench
listed.Selecting either Administration, Batch, or e-business will start the
corresponding Workbench. Figure 4-62 shows the result of selecting
Administration.

Figure 4-63 Signing on to the VisualAge Pacbase administrator Workbench
To sign on to the VisualAge Pacbase administrator Workbench you will need to

supply a user-id and password. We used the ADMIN user-id which is
automatically established during the installation of VisualAge Pacbase. By
default the password is blank and needs to be changed. The password is
changed by clicking the Change ... button. You will need to enter a new password
and enter it a second time to confirm it.
The list of databases is a drop-down list that displays the different databases
(administration and development) for your organization. Your organization may
have only one administration database and one development database or your
organization may have one administration database and several development
databases om different platforms. If your organization has multiple VisualAge
Pacbase development databases, then the drop-down list should contain one
entry that allows for site administration and several entries that correspond to the
different VisualAge Pacbase development databases.

The information in the list comes from the bases.ini file located in the Workbench
directory. This file is established as part of the installation of VisualAge Pacbase
and contains connection information for each of your organization’s VisualAge
Pacbase databases. The content of bases.ini is more detailed than in previous
releases of VisualAge Pacbase. In addition to the name of the database,
bases.ini contains the following parameters:
򐂰 Base: The string of text that appears in the list of databases as you sign on to
the Workbench
򐂰 Code: Four-character code for the development database, or “****” to indicate
the entry for site administration
򐂰 Location: Name of the reference in the file vaplocat.ini for this database
򐂰 GatewayHost (optional): The IP address of the host machine for this database
򐂰 GatewayPort (optional): The port on the host machine for this database
The following is a sample of an entry in the bases.ini file:

}
base "Base NT (gateway locale)" {
code = "V300"
location = "EnvNT"
}
The file, vaplocat.ini, is established during the VisualAge Pacbase Workbench

installation process and contains additional parameters, including:
򐂰 Location: A reference that corresponds to the Location parameter in bases.ini
enclosed between < and >.
򐂰 Length: Length of the communication buffer
򐂰 Monitor: Reference to the module that functions as the monitor
򐂰 Mware: Specifies the middleware employed (for example, Socket)
򐂰 Mwareaddress: Specifies the IP address and port number, which does the
mapping between the physical set of files and the logical database name in
the admin workspace
The following is a sample of an entry in the vaplocat.ini file:

<EnvNT>
LENGTH=08192
MONITOR=DECOMD
MWARE=SOCKET
MWAREADDRESS=127.0.0.1 7030
MWTIMEOUT=10000

Consult the VisualAge Pacbase technical documentation for more information
regarding the content of the vaplocat.ini file, which is built during the client install.
To complete the sign on to VisualAge Pacbase, select the administration

database from the list and click the Finish button.
After signing on to VisualAge Pacbase, you will see the VisualAge Pacbase
administrator Workbench. The information is presented in the form of a tool bar,
menu bar, and several tabs, each of which is discussed in the following sections.
In this chapter, VisualAge Pacbase administration is described first for site
administration and then for base administration.
4.4.2 Menu bar

The VisualAge Pacbase administrator Workbench menu bar is shown in Figure
4-63.
Figure 4-64 The administrator Workbench menu bar
File options
When you use the VisualAge Pacbase administrator Workbench, you are using a
local copy (workspace) of the VisualAge Pacbase administration database from
the server. The menu bar file option allows you to do the following regarding this
local copy:
򐂰 Save workspace locally.
򐂰 Save workspace as ...
The File option lets you manage your connection to the server as well. Normally,
as the VisualAge Pacbase administrator, you will be connected to the VisualAge
Pacbase repository server. Your changes will be made using a local copy of the
repository which will be synchronized with the server repository. It is possible to
disconnect from the server and work only with your local copy of the repository.
To do this, you would select Disconnect from the File menu. If you need to use
the server copy again (for example, to resynchronize your changes) you would
use the File menu to Reconnect.
VisualAge Pacbase allows you to customize the look and feel of your
administrator Workbench using Preferences from the file menu. The changes
made using Preferences affect this Workbench only, they are not global to
VisualAge Pacbase. A dialog box will appear that identifies the types of
preferences that you can set. These include:

򐂰 General preferences for pane behavior, which allow you to:
– Show or hide title bars
– Highlight a selected pane
– Specify the size of the pane history cache
– Appearance, which allows you to change the colors and borders
associated with displayed information and also change the fonts for the
Workbench display
– Toolbars, which provides options to reposition toolbars and control their
behavior
– Help, which specifies the browser to be used to display help information
and the location of the browser program
򐂰 Workspace preferences allow you to manage the local workspace for the
VisualAge Pacbase administrator Workbench. Using these options, you can:
– Specify the workspace root directory
– Indicate that the workspace is saved whenever VisualAge Pacbase is
closed
– Indicate that the saved workspace is loaded when the VisualAge Pacbase
administrator Workbench is restarted.
– Completely discard the content of the local workspace using the clear
workspace button
Tab options
The administrator Workbench manages seven things relative to site
administration:
򐂰 Databases
򐂰 Command lines
򐂰 Profiles
򐂰 Pac/Transfer
򐂰 Users
򐂰 Security
򐂰 Parameters

These are managed through the use of tabs except for Security and Parameters,
which are managed from the menu bar. Figure 4-65 shows the tabs for the
VisualAge Pacbase Workbench.
Figure 4-65 Tabs for the VisualAge Pacbase administrator Workbench
The second position from the left in the menu bar changes to correspond to the
tab selected. For the tab selected, the menu bar will provide options to:
򐂰 Create a new occurrence of the entity managed by the selected tab (for
example, in the preceding figure the tab selected manages databases)
򐂰 Sort the list displayed by the tab in either ascending or descending sequence
based on a property of the displayed information
Menu bar choices are also available in the form of a pop-up context menu by
right-clicking.

Window options
The Window options on the menu bar control the appearance of the Workbench
display. Using the Window options, you can:
򐂰 Maximize, minimize and restore the pane.
򐂰 Lock the window so it cannot be closed.
򐂰 Open the Workbench and Workspace manager and switch between them.
The tab display is divided into two parts, selection and definition. The selection
pane displays a list of the user entities being managed and the definition pane
displays the properties for that type of user entity. The Window options allow you
to determine whether either or both panes are displayed.
Security and Parameters are managed through the Window options. You can
open either the Security browser or the Parameters browser.
Security browser
The Security browser consists of three tabs, as shown in Figure 4-66.
Figure 4-66 The VisualAge Pacbase Security Browser

The definition tab of the Security browser lets you indicate to VisualAge Pacbase
if your organization already uses a security tool such as RACF (Resource
Access Control Facility). Other options are activated depending on the security
tool indicated.
You can specify these Password options using the definition tab as well:
򐂰 The number of old passwords managed
򐂰 The number of days that a password will be considered valid
򐂰 The minimum number of characters that the password must contain
򐂰 Whether the user can specify a blank password
򐂰 Whether the password must contain numeric characters
򐂰 Whether the password can be the same as the user id
The tab identified as VA Pac Access Key allows the VisualAge Pacbase
administrator to maintain the key for the product. The key controls which options
are licensed for VisualAge Pacbase and also controls access to the repository.
The key is established when VisualAge Pacbase is installed and is maintained
whenever the organization renews its product license or purchases additional
product options.
If the organization has purchased the DSMS (Development Support

Management System) option, then the DSMS Control tab is used to maintain
information for use of that product option.
Parameters browser
The Parameters Browser consists of three tabs as shown in Figure 4-67.

Figure 4-67 The VisualAge Pacbase Parameters browser
VisualAge Pacbase allows the administrator to set parameters related to the use
of special characters, error messages, and the categorization of the text
documentation entity. Normally, the special characters feature is not used.
When applications are generated from the VisualAge Pacbase, error handling is
supplied as part of the generated application. Specific error messages are
generated into a file which is then used to retrieve and display the appropriate
error message. The text for these error messages is standard but can be
overridden through the Parameters browser using the Error labels tab.

The original text is displayed, and the administrator can type in new text for the
error message, as shown in Figure 4-68.
Figure 4-68 Changing the error message text using the parameters browser
The Text labels tab refers to the entity used in previous versions of VisualAge
Pacbase to produce documentation and assign that documentation to other
entities within the Pacbase repository. This entity is the Text entity and it consists
of a definition and sections (also called paragraphs).
VisualAge Pacbase allows the text entity to be assigned to a category through

the use of a two character code. In the same manner, the sections of the text can
be categorized by two-character codes.

The meaning of these two-character codes is documented using the Text labels
tab of the Parameters browser as shown in Figure 4-69. This facility is for upward
compatibility purposes only. The text entity has been replaced by the publishing
facility, discussed later in this redbook.
Figure 4-69 Documenting text pages
Selected
The Selected option from the menu bar becomes active when an entity is
selected using one of the tabs on the VisualAge Pacbase administrator
Workbench. All of the options pertain to the selected entity and include:
򐂰 Open, which allows you to see the information for the selected entity
򐂰 Copy, which allows you to copy a portion of the entity
򐂰 Duplicate, which allows you to copy the complete entity
򐂰 Refresh, which updates the displayed information
򐂰 Discard Changes, which allows you to restore the entity
򐂰 Delete, which allows you to remove the entity
򐂰 Save, which commits your changes for the entity
򐂰 Create, which allows you to create a new occurrence of the entity
򐂰 Sort, which displays a list of properties for the entity for the purpose of placing
the list of entities for the tab in ascending or descending sequence

These options are context sensitive and vary from one instance to another, some
options being grayed out. These options are also accessible by right-clicking an
entry in the displayed list.
Workspace
The Workspace option from the menu bar is used to resynchronize your local
version of the repository with the server repository. This action applies changes
that you have made to the entities in your local repository to the corresponding
entities in the server repository.
Help
The Help option of the VisualAge Pacbase administrator Workbench menu bar
contains the following:
򐂰 Help Home Page
򐂰 Workbench Home
򐂰 Support
򐂰 About Workbench
The first three options invoke the browser to display related help information for
the VisualAge Pacbase user.
The last option, About Workbench, displays version information.

4.4.3 Using the administrator Workbench
Figure 4-70 shows the basic tabs of the administrator Workbench.
Figure 4-70 VisualAge Pacbase administrator Workbench tabs

Databases
The databases tab displays the logical names of databases that can be
administered from this administrator Workbench.
Clicking a database displays the following information in the pane to the right of
the display:
򐂰 Code: A four-character logical identifier for the database
򐂰 REST batch procedure: You must use the REST batch procedure to record
this four-character code as reference to a development database
򐂰 Label: A longer description of the database
򐂰 Transaction code: The code that allows the TP monitor to manage the
communications for this database
We added the VisualAge Cruise Lines database using the following steps:
1. From the menu bar we selected Create new Base VisualAge Pacbase.
2. In the SmartGuide, we entered “VCL|” for the code and VisualAge Cruise
Lines for the Label. In our Windows NT environment we did not need a
Transaction code.VCL
3. We clicked the Finish button.
You can change the database information using this tab. To change the
information for a database:
1. Select the database from the list in the selection pane.
2. Change the information in the definition pane.
To remove the database from the display, right-click the database and select
Delete from the context menu.

4.4.4 Command lines
When components are generated from the VisualAge Pacbase repository, they
are in the form of source files for such things as programs and database
definition language (DDL). After generation, it is necessary to process this
source with a compiler or other utility in order to complete the transition to a test
or production environment. VisualAge Pacbase assists you in the transition by
allowing the administrator to define additional control data to be positioned
relative to the source.
Figure 4-71 shows where command lines can be positioned for entities
generated from VisualAge Pacbase.
Command lines at
beginning of jobstream
Command lines
before entity 1
Source for
entity 1
Command lines after

entity 1
Command lines
before entity 2
Source for
entity 2
Command lines after

entity 2
Command lines at
end of jobstream
Figure 4-71 Command line processing
In the figure, command lines can be inserted before and after each generated
entity (there are two in this example) and before and after the job stream
associated with the generated entities.
We did not require the use of any command lines for the components we
generated for the VisualAge Cruise Lines sample application.

4.4.5 Profiles
VisualAge Pacbase allows the administrator to establish profiles to control the
access to the VisualAge Pacbase repository content and authorizations to
execute other administrative procedures. Selecting the Profiles tab presents the
information shown in Figure 4-72.
Figure 4-72 Using the Profiles tab
We used the following profiles:

򐂰 Admin (added by default during the installation)
򐂰 Developer
The Admin profile contains users that have the authority to administer our
sample application repository. The steps to add a profile are:
1. Select Create new Profile VisualAge Pacbase from the menu bar.
2. Complete the information presented by the SmartGuide as shown Figure
4-73. Most of this information only applies to users that will be VisualAge
Pacbase administrators.

Figure 4-73 SmartGuide for adding a profile
3. Click the Finish button.
Profiles (just like users) and their authorizations are common to all databases.
Using the base administration feature of VisualAge Pacbase, they can be refined
for each user on each database and library.

Libraries authorization refers to the level of access that users with this profile will
have to the libraries within VisualAge Pacbase. A library in VisualAge Pacbase
refers to a logical collection of managed entities in the repository. For more
discussion regarding libraries, refer to chapter 6 of this redbook. There are four
options associated with Libraries authorization:
򐂰 None: The user would have no direct access to the components in this library.
򐂰 Read only: The user can view the components but cannot change them.
򐂰 Update: The user can modify components in the library.
򐂰 Administrator: The user can change options associated with the library.
Procedures authorization refers to whether users with this profile can execute
batch procedures. Batch procedures are various utilities that can be used to
manage the VisualAge Pacbase repository and its content. In general, only the
VisualAge Pacbase administrator should have this ability. There are two options:
򐂰 Not authorized
򐂰 Authorized
Parameters authorization refers to the ability to administer users. Only the

VisualAge Pacbase administrator should have this ability. There are two options:
򐂰 Not authorized
򐂰 Authorized
PEI authorization refers to the use of the optional VisualAge Pacbase component
for managing application components generated from the repository and placed
in the production environment. PEI is not within the scope of this redbook.
When you set the Parameters authorization to Authorized, VisualAge Pacbase

sets related options automatically. After the Profile is added, you can see these
related options by clicking the Show Parameters Details button in the pane.

These related options were set automatically for the Admin profile because we
set the Parameters authorization to Authorized. Normally, you would not need to
change the Parameters details. Figure 4-73 shows the defaults that were added.
Figure 4-74 Parameters added by default
Refer to the VisualAge Pacbase product documentation for additional detail

regarding these related options.
We also set up a Developer profile.

4.4.6 Pac/Transfer
The content of a VisualAge Pacbase database is managed as a set of sessions.
A session is identified by a number and represents the content of the repository
as of a specific point in time. A low session number indicates that the content is in
the distant past. A high number indicates that the content is of more recent origin.
A session number of 9999 is used to designate the current session.
In addition, all of the update activity in VisualAge Pacbase is recorded in a file

referred to as the Journal. The journal is a chronological record of every update
that occurs. The Journal file is periodically archived by a utility (ARCH) so that its
content can be managed more efficiently.
Sessions are independent of one another, and a common situation involves

taking the activity associated with one session and applying it to another session
in order to synchronize certain entities. The archived Journal is the source for the
transaction information used to accomplish this. The Pac/Transfers tab provides
the ability for the VisualAge Pacbase administrator to manage the activity
between sessions. The basic process involves:
1. Defining a transfer set using the VisualAge Pacbase administrator Workbench
2. Using the Pac/Transfer tab in the VisualAge Pacbase administrator
Workbench to define the journal extraction criteria, which is the input to the
transfer parameter update procedure (TRUP)
3. Extracting the activity from the archived journal using a utility (utilities in
VisualAge Pacbase are called batch procedures), which is the transfer file
creation batch procedure (TRPF) and the generation of transfer transactions
batch procedure (TRRP)
4. Updating another session or sessions with the results of the extraction using
the batch procedure update (UPDT)
This discussion focuses on the use of the VisualAge Pacbase administrator

Workbench to define the transfer set and the transfer criteria.
Important: If your organization is using DSMS, consult the VisualAge

Pacbase documentation for information regarding batch procedures that must
be run when using Pac/Transfer.

Defining a transfer set
Defining a transfer set begins with selecting Pac/Transfer -> Create new
Transfer Set (Pac/transfer). This starts the SmartGuide shown in Figure 4-74.
Figure 4-75 Pac/Transfer SmartGuide

A transfer set is associated with a VisualAge Pacbase database. Clicking the
button labeled ... next to the database code displays a list of databases, shown in
Figure 4-76, that can be used to select a database to begin defining the transfer
set.
Figure 4-76 Pac/Transfer database selection
To complete the definition of the transfer set, enter a four-character transaction

set code and a label, which can be up to thirty-six characters.

Defining transfer criteria
To define the transfer criteria, double-click the transfer set you created. This
displays the Pac/Transfer selection criteria tabs as shown in Figure 4-77.
Figure 4-77 Pac/Transfer selection criteria tabs
The VisualAge Pacbase administrator uses these tabs to establish the following
types of Pac/Transfer criteria:
򐂰 Definition: Corresponds to the earlier definition of the transfer set and can be
used to change the label for this transfer set
򐂰 Sessions: Used to specify the source session and one or more target
sessions
򐂰 Libraries: Used to restrict the extraction from the archived journal based on a
specific library and to designate target libraries
򐂰 Change Numbers: Used if you have DSMS, to restrict the archived journal
transaction based on the DSMS controls
򐂰 User Codes: Used to restrict the extraction from the archived journal based
on a specific user code and to designate a user code for the target.

Specifying session criteria
To specify the source and target sessions for Pac/Transfer, select the Sessions
tab, and then from the menu bar select Sessions -> Create new Sessions. This
starts the SmartGuide shown in Figure 4-78.
Figure 4-78 Specifying sessions for Pac/Transfer
You can use the buttons labeled ... to display a list of available sessions to use
as the source and target. The sequence number is used to control the sequence
of the update activity to the target session. For example, when multiple sessions
are specified, you must indicate which session is to be applied first.

Specifying library criteria
To specify the source and target libraries for Pac/Transfer, select the Libraries
tab, and then from the menu bar, select Libraries -> Create new Libraries. This
starts the SmartGuide shown in the Figure 4-79.
Figure 4-79 Specifying source and target libraries
You can use the buttons labeled ... to display a list of available libraries to use as
the source and target.

Specifying user criteria
To specify a user code for source and target for Pac/Transfer, select the User
Codes tab, and then from the menu bar, select User Codes -> Create new User
Codes. This starts the SmartGuide shown in Figure 4-80.
Figure 4-80 Specifying user codes for Pac/Transfer
You can use the buttons labeled ... to display a list of available user codes to use
as the source and target.

Specifying change numbers criteria
This tab only applies if your organization is using DSMS (development support
management system, an optional part of VisualAge Pacbase). To specify the
change numbers for the source and target for Pac/Transfer, select the Change
Numbers tab, and then from the menu bar, select Change Numbers -> Create
new Change Numbers. This starts the SmartGuide shown in Figure 4-81.
Figure 4-81 Specifying Pac/Transfer change numbers (DSMS only)
When using change numbers, it is possible to associate the transactions to a

specific user code. You can use the button labeled ... to display a list of available
user codes.

4.4.7 Users
The Users tab is used to set up users that will have access to the VisualAge
Pacbase repository. We added a User for each redbook author.
To add a User, select Create New User from the menu-bar. A SmartGuide
appears that allows you to add the information for a new User.
The SmartGuide fields are:

򐂰 Name: A short code to identify the user. This is the code that the User is
required to enter to logon to VisualAge Pacbase.
򐂰 Label: A more descriptive reference, usually the person’s name.
򐂰 Profile: Used to assign an existing Profile to this User. To do this, click the
button with the ..., then select the Profile to assign by clicking it.
򐂰 Change pass...: Depending on the security options, the administrator can
assign an initial password for the User. To do this, click the button with the ....
You will be asked to enter the new password and to confirm the password by
entering it a second time.
򐂰 Check boxes allow you to assign this User a role as Administrator, Designer,
or Workbench user.
򐂰 Other fields for the User are documentary and optional. These include:
– E-Mail
– Manager, which you can select from a list of managers by clicking the
button labeled Managers list
– Phone Number
– Cellular Phone
– Service
– Personal fields:
• Second Name
• Pers Phone
• Address
– Comments
After the User is added, it will appear in the list of Users.
Clicking a User displays that User’s information and makes it available for
change.
To delete a User, right-click the User and select Delete from the context menu.

Figure 4-82 shows the User information we set up for one of the redbook authors.
Figure 4-82 User REDBOOK
4.4.8 Tool bar

The VisualAge Pacbase administrator Workbench includes a tool bar that
pertains to the entity selected when using the tabs. Figure 4-83 shows the
toolbar icons.
Figure 4-83 VisualAge Pacbase administrator icons

Referring to the preceding figure, the toolbar icons from left to right are:
򐂰 Create: To create a new entity occurrence which corresponds to the active tab
򐂰 Show Details: To display more information with the list of entities in the
selection pane
򐂰 Refresh: To rebuild the display from the repository
򐂰 Discard Changes: To eliminate any changes associated with the selected
entity from your workspace
򐂰 Save: To commit changes to your local workspace for later resynchronization
with the server repository
These options are also accessible by right-clicking an entry in the displayed list.
4.5 External controls

VisualAge Pacbase allows the administrator to specify validations and
initialization for entities created in the repository. JavaScript is used to write these
rules. These scripts are read and interpreted dynamically through FESI, a free
external tool that allows access to Java objects and methods. The Workbench
interface to these scripts is specified as a path file or URL set using File ->
Preferences and navigating to External controls in the display. Here too, you can
indicate whether the Workbench activity will be subject to validity controls,
initialization functions, or both. Figure 4-84 shows the specification of the
external controls.
Figure 4-84 Specifying the external controls

4.5.1 Validity controls
Validity controls are evaluated each time the entity is modified. The results of the
validation can be set to indicate that the modified entity is valid, or to give a
warning, or to indicate an error. Warnings and errors are accompanied by an
error message to the Workbench user.
For example, VisualAge Pacbase allows entities to be associated with keywords

so that entities can be grouped and located conveniently within the VisualAge
Pacbase repository. Your organization may recommend that all entities should
have an explicit keyword assigned. As the VisualAge Pacbase administrator, you
can check for conformance to this recommendation through the external controls.
To do this you would create a file named AllEntities.js, which is the mandatory file
name for the JavaScript external controls that pertain to all entities. In this file,
you would place the following JavaScript code:
//Controls if keywords are present
if (this.getKeywords().isEmpty()) {
this.setWarningMessage("In our company, keywords are strongly recommended.");
return false;
} else {
return true;
}
4.5.2 Initialization controls

Initialization scripts are called each time the user clicks on the Finish button of
an entity creation SmartGuide. These scripts allow default characteristics of an
entity to be established as the entity is created. For example, initialization scripts
can be used to add a macro to a batch program as it is created.
For additional information on External controls, consult the VisualAge Pacbase

documentation.
4.6 VisualAge Pacbase 3.0: Base administration

Base administration refers to functions accomplished by the VisualAge Pacbase
administrator for a specific database as opposed to site administration, which
refers to functions for all of your organization’s VisualAge Pacbase databases.
Base administration involves using the VisualAge Pacbase administrator

Workbench and there are only slight differences between site administration and
base administration.

Starting the VisualAge Pacbase administrator Workbench is the same for base
administration as it was for site administration. The difference is in your selection
from the drop-down list, as shown in Figure 4-85.
Figure 4-85 Administrator sign on
4.6.1 Menu bar

The Menu Bar contains the same options and looks similar to that used for site
administration.
4.6.2 Base administration tab options

Base administration differs from site administration primarily in the things
managed at the database level. Recall from the previous discussion that the site
administration manages seven things:
򐂰 Databases
򐂰 Command Lines
򐂰 Profiles
򐂰 Pac/Transfer

򐂰 Users
򐂰 Security
򐂰 Parameters
Base administration manages the following:

򐂰 Command Lines
򐂰 Profiles
򐂰 Pac/Transfer
򐂰 Users
򐂰 Meta Entities
򐂰 User Relationships
򐂰 Libraries
򐂰 Input Aids
򐂰 Security
򐂰 Parameters
Command lines, Profiles, Pac/Transfer, and Users function the same way as for
site administration except that the information is specific to this database
(indicated by the sign on). Security and Parameters open the corresponding
browser and function the same as for site administration.
Unique to base administration are:

򐂰 Meta Entities
򐂰 User Relationships
򐂰 Libraries
򐂰 Input Aids
Meta entities and user relationships

Meta entities and user relationships are an optional part of the VisualAge
Pacbase product. Meta entities (referred to as User Entities in previous releases
of VisualAge Pacbase) allow the repository to be extended to include custom
entities for your organization. This extension of entities can result in the need to
define relationships between the new meta entities or between the meta entities
and the entities which are a standard part of the VisualAge Pacbase repository.
Refer to the VisualAge Pacbase documentation for specific information
concerning Extensibility and the use of meta entities and user relationships.
Libraries
The content of a VisualAge Pacbase database is logically a set of libraries
organized hierarchically. These libraries need to be established and managed by
the VisualAge Pacbase administrator. This is done using a combination of utilities
(called batch procedures) and the VisualAge Pacbase administrator Workbench.

The basic steps are as follows:
1. The VisualAge Pacbase administrator sets up the input transactions for the
batch procedure PACS, MLIB. Libraries can be added, deleted or
repositioned hierarchically.
2. The PACS procedure with the MLIB option is run to produce an image version
of the database with the new library information.
3. The REST procedure is run to restore the database from the image created
by the PACS procedure.
4. After the REST procedure finishes, the VisualAge Pacbase administrator
must initialize the library and at the same time has the opportunity to change
any of the options for that library. This is done through the administrator’s
Workbench using the library tab as seen in Figure 4-86.
Figure 4-86 Managing libraries

Input aids
Input aids (Parameterized Input Aids or P.I.A.s) are one of the standard entity
types in VisualAge Pacbase. The input aid entity is used for documentation, to
specify options to be taken into account during generation, and to describe error
messages. This tab conveniently allows the VisualAge Pacbase administrator to
create and maintain a P.I.A. entity.
4.7 VisualAge Pacbase utilities

This section briefly discusses changes to the utilities associated with VisualAge
Pacbase from previous releases of the product and also new utilities for
VisualAge Pacbase Release 3.0.
4.7.1 Changes from previous releases

VisualAge Pacbase includes a set of utilities (batch procedures) used by the
VisualAge Pacbase administrator to manage the content of the repository
databases and to ensure their recovery in the event of a problem.
For information regarding the utilities that are available and how to execute them,
refer to the VisualAge Pacbase documentation.
Of interest to administrators of previous VisualAge Pacbase releases is the

elimination of certain batch procedures. Among these are:
򐂰 Batch procedures related to PEI (production environment interface) have
been incorporated into the VisualAge Pacbase administrators Workbench.
PEI is an optional part of VisualAge Pacbase. No longer available are GRPE,
HIPE, INPE, PRPE, RSPE, SIPE, and SVPE.
򐂰 Batch procedures related to the maintenance of user parameters. These are
part of the Security and Parameters browsers accessed through the
VisualAge Pacbase administrator Workbench. PARM, REAG, SVAG, LOAE
are no longer available.
򐂰 Batch procedures that provide the ability to extract content from the
VisualAge Pacbase databases began to change in the previous releases of
VisualAge Pacbase from separate extraction procedures into the more global
PACX procedure. In VisualAge Pacbase 3.0, the individual procedures have
been eliminated and PACX must be used for all extractions. This includes
extractions for entities, libraries, journal information and extractions in support
of library sub-network comparisons.

򐂰 Certain batch procedures related to backing up and managing the VisualAge
Pacbase database have been consolidated into a new batch procedure
PACS. The functionality of SAVE, SASN, MLIB, UXSR, and LVBL have been
incorporated into PACS.
4.7.2 New to this release

Changes in release 3.0 of VisualAge Pacbase have resulted in new batch
procedures and they are:
򐂰 Previously, it was mentioned that PACS is a new batch procedure that
eliminates the SAVE, SASN, MLIB, UXSR, and LVBL procedures.
򐂰 The addition of the VisualAge Pacbase administrator Workbench added new
files to the VisualAge Pacbase database and new batch procedures have
been added to manage the files that make up the administration database.
New batch procedures include:
– INGU, initialize
– ARAD, archive
– PACG, backup
– ROAD, reorganize
– RSAD, restore
򐂰 Because some of the previous files have been removed from the VisualAge
Pacbase a new set of batch procedures to migrate to VisualAge Pacbase
Release 3.0 from previous releases is supplied (PC25, PE25, PG25)
򐂰 In the Windows NT environment, it is no longer necessary to run the batch
procedures from a DOS window. Now you can run batch procedures from the
Start menu. In addition, the results of the batch procedure execution is stored
in a log file in the tmp directory in a file ([PROC]msg.log).
Refer to the VisualAge Pacbase 3.0 documentation for your specific hardware,
communications, and operating system before migrating from a previous release.

5
Chapter 5. VisualAge Pacbase 3.0

development
In this chapter we explain how to use the Workbench for e-business
development. We cover things such as:
򐂰 How to create a data element
򐂰 How to create a data segment
򐂰 How to create e-business components

5.1 The Workbench in general
To be able to log on to the Workbench, you first have to make sure that the server
is running; then you can start whichever Workbench you want. Since we will only
be developing in the e-business Workbench, we recommend you start that one.
The first thing you will see after you start the server is a command window, which
will say:
Checking for new version......
This line means that your Workbench is checking with the VisualAge Pacbase
3.0 server to see if there has been an update to the VisualAge Pacbase software.
If there has been an update, your Workbench will automatically get that update
for you. This does not happen on a stand-alone machine.
5.1.1 Logging on
The process of logging on to either one of the three Workbenches is almost the
same. There are only two things you are not able to do with the Administrators
Workbench log on that you can do with the others. Logging on to a versioned
session, also known as a historical session, and logging on to work under
Development Support Management System (DSMS).
In order to sign on to the system for the first time:

1. Type in the user-id created in the Administrators Workbench.
2. Type in your password that was assigned to your user when it was created.
(It is possible to allow blank passwords in VisualAge Pacbase, if the blank
password field is activated, then you will not need to enter a password.)
3. Click Change ... . A pop-up window appears in which you must create a new
password.
4. Type a password in the text box after New password.
5. Type the same password in the text box after Confirmation.
6. Click OK and you will now return to the log-in window.
7. Select your database.
8. Now you have two choices:
– Click Finish to go directly to the Workbench.
– Click Next>>, to see where you can change your session or select to work
under DSMS.
• Since we won’t be using these options in this redbook, click Finish.

5.1.2 Quick tour of the Workbench
After you have signed on the Workbench will load. The first thing you will see is
the Quick Start window, as shown in Figure 5-1.
Figure 5-1 Quick start window
Since this is a tour, we do not want to import or to create anything just now. We
first want to show you around.
1. Click the Go to the Workbench icon.
2. Click OK.
3. Click the tab Data Elements.
What you see now is an empty Workbench. So where are your programs? They
are in the repository together with the data-elements and segments and all the
other things we mentioned before. To be able to take a look at them you would
need to download them first to your local repository. We will come to that later.
Chapter 5. VisualAge Pacbase 3.0 development 139

Now we guide you to the Workbench, which will look as shown in Figure 5-2.
Figure 5-2 The empty Workbench
The title bar

On the title bar, Workbench [Redbook in current session, workspace ‘cruisedev’],
you will find the name of the user (Redbook) and the session you are working on
(in current session). After you save your workspace, the name of your workspace
will also be shown after the session. We already saved ours, workspace
‘cruisedev’.
The menu bar

Out of the s,ix menus on the title bar, we will explain four of them here. We do this
because two of them are related to the tabs and will change depending on the
tab you select. If you have selected the tab Data Elements your menu bar will
look like the one in Figure 5-3.
Figure 5-3 The menu bar
The third menu from the right is called Data Elements. This is because you have
selected the tab Data Elements. If you select another tab, for example
Segments, the menu Data Elements will be replaced by a menu called
Segments. The other menu that changes based on the selected tab is the
Selected menu. In addition to the menus on the menu bar there is also a
short-cut to IBM’s VisualAge Pacbase Homepage. Just click the VisualAge logo
on the right of the menu bar to access it.

The file menu
Figure 5-4 is the menu from which you control your Workbench. For example,
here you can issue Print and Close commands.
Figure 5-4 File menu
Now we take you through the File menu:

򐂰 Quick start.: This will display the same pop-up window as when you entered
the Workbench for the first time. We will use this later and there we will
explain the complete window.
򐂰 Open a new session.: This will display a pop-up window, which you can use
to change sessions. The session you chose will open in a new Workbench.
򐂰 Save workspace locally: Used to save data in your local repository.
򐂰 Save workspace as...: To be able to save a workspace locally you first must
give it a name. This name will then show up in the title bar after the session.
򐂰 Reconnect: In this figure, this option is grayed out because you are already
connected to the VisualAge Pacbase server.
򐂰 Disconnect: This enables you to break your connection with the VisualAge
Pacbase server.
򐂰 Preferences...: Here you can adjust your settings and give the Workbench the
Look and Feel you prefer.
򐂰 Print.: With this option, you can print the content of the pane you selected.
򐂰 Close: This closes the window you are using. This option closes the
Workbench when selected from the main window.
򐂰 Exit Workbench: Terminates your Workbench.

The workspace menu
By using the menu shown in Figure 5-5, you will be able to manage your
workspace.
Figure 5-5 Workspace menu
The choices you have here are:

򐂰 Change view library...: To select another library or to change the view from a
library.
򐂰 Resynchronize with repository: Using the timestamps, this will check to see
where the most current version of data is located. If the data in your local
repository has the newest timestamp the repository will be updated. If data on
the repository is more current then yours, the Workbench will ask you if want
your local repository to be updated.
򐂰 Search...: This will enable you to search the local and server repositories.
The Window menu

This menu has features that make working with VisualAge Pacbase more
comfortable. An example is shown in Figure 5-6.
Figure 5-6 Window menu

These are the options for you to use:
򐂰 Show workbook tabs Ctrl+T: Here the option is checked. When you uncheck
it, you will be restricted to the tab you had selected.
򐂰 Restore pane: Grayed out in this example. This option will become available
when you select the options Maximize pane or Minimize pane. Selecting the
Restore pane option will return the window to its original state.
򐂰 Maximize pane: Will maximize your selected pane. The other pane will totally
disappear.
򐂰 Minimize pane: Will minimize the selected pane, the pane remains visible.
򐂰 Data Elements: If the Data Elements option is checked the Data Elements will
be visible. This menu option will change dynamically depending on your
selection.
򐂰 Definition: If the Definition option is checked the Definition screen will be
visible.
򐂰 Lock Window: To lock a window. The locked window cannot be closed.
The three options below allow you to switch between three different screens:
򐂰 Workbench: Default, this is the screen we are currently exploring.
򐂰 Workspace Manager: This opens the Workspace Manager. We explain the
working of the Workspace Manager later on in this chapter.
򐂰 Generation Manager: This opens the Generation Manager. We explain the
working of the Generation Manager later on in this chapter.
򐂰 Switch to: The different windows you have opened via the Workbench.
The help menu

To be able to use the help menu, shown in Figure 5-7, you must have an Internet
browser installed on your machine.
Figure 5-7 Help menu
The help menu gives you the following options:

򐂰 Help Home Page: This will take you to the Help Home Page you have
installed somewhere on your system.

򐂰 Workbench Home: This will take you to IBM’s VisualAge Pacbase
Homepage.
򐂰 Support: This opens your Internet browser on the IBM VisualAge Pacbase
support site. Here you can ask everything about features in VAP3.0 and read
about other features available.
򐂰 About Workbench: Gives you the version of your workbench.
Standard tool bar icons

A couple of very general commands are also located on the tool bar. The tool bar
we show you here in Figure 5-8, has a large gray space in the middle. Normally
this space is occupied by icons related to the tab you have selected. Since those
are dynamic we will not explain them in this section.
Figure 5-8 Tool bar
The search button

The search button in shown in Figure 5-9.
Figure 5-9 Search button
By pressing the search button, you will automatically get the Search SmartGuide
for Xref’s, which are cross-references.
The refresh button

The refresh button is shown in Figure 5-10.
Figure 5-10 Refresh button
By pressing the refresh button you will able to refresh an entity you have selected
from the list on your workbench. Why would you want to refresh? You would
want to refresh because everything you see on your Workbench is stored locally
and it is not locked to you. So when someone else decides to change something
on his machine and saves it in the repository you suddenly have an old version in
your local workspace. To get the latest version you have to refresh.

The discard button
The discard button is shown in Figure 5-11.
Figure 5-11 Discard button
The discard button will undo your changes on a selected unsaved entity. You
would want to use this if you are not sure of your changes or because someone
else already changed it in the repository.
The save button

The save button is shown in Figure 5-12.
Figure 5-12 Save button
When you have finished your work on an entity you would like to save it. By using
the save button you will save it in your local repository and on the server
repository. When you create an entity it is automatically saved in the local and on
the server repository.
Dynamic tool bar icons

The middle part of the tool bar is occupied by icons that have a direct link to the
tab that is currently selected. Some of these icons will change when you go from
one tab to another. Others will stay the same only their function changes a little.
We will discuss three of the buttons. These are:
򐂰 Import from repository button.
򐂰 Import / Create by code button
򐂰 Show details button
The buttons placed in between the Import / Create by code button and Show
details button, as shown in Figure 5-13, change per tab and therefore will be
discussed when we discus that tab. These buttons are often the Create buttons.
Figure 5-13 Dynamic part of the tool bar

Import from repository... button
The import from repository button in shown in Figure 5-14.
Figure 5-14 Import from repository button
A blue downward pointing arrow always means import in VisualAge Pacbase 3.0.
It can be found on almost every toolbar there is in VAP 3.0 and it is a part of the
Quick Start window we described earlier. Import in this case means downloading
data from the server repository into the local repository.
The SmartGuide for imports can be divided into to parts, which we did in Figure
5-15. The first part is for importing multiple entities at once. The second part is for
importing specific entities which name is known to you.
Figure 5-15 Top half of the import SmartGuide
The top half of the SmartGuide is only accessible when the radio button in front
of Multiple Import is checked. The result is as follows:
򐂰 Select: When the preceding radio button is checked you can fill in the amount
of entities you want to download.
– Data Elements from code: This gives the possibility to download entities
from a certain starting point.

򐂰 Next....... Data Elements: Import the next X entities starting from the latest
entity already downloaded. X standing for the amount given in the text box.
Default is the same amount as the previous download.
򐂰 Other (by labels, keywords, etc.): This allows to download entities by their
name of certain keywords. This must be followed by clicking the Next button at
the bottom of the SmartGuide. This will guide you to an almost similar
SmartGuide as the current one. The only difference being that there is the
possibility to download by label or keyword.
򐂰 View in separate window: A normal download will add the entities to the
entities already in your local repository. This option opens a window which will
display only the entities just downloaded.
Figure 5-16 shows that the lower part of the SmartGuide is only accessible when
the Single import radio button is checked.
Figure 5-16 Lower half of the import SmartGuide
This second part of the SmartGuide is to download a single entity whose code is
known to you. The results are as follows:
򐂰 Code: The code of the entity wanted for import.
򐂰 Open browser: If this box is checked, the browser belonging to the entity will
open after the import.

At the bottom of the SmartGuide are four buttons. The only button from those
four which need explaining is the Next>> button. Pressing this button gives the
opportunity to change the direction of the download. The default value for an
import is from your current library using an upward view with doubles. This
means that the import takes all libraries in consideration which are located higher
in the hierarchy than the current library and selects the amount of entities defined
in the SmartGuide, beginning from the letter or entity defined in the SmartGuide.
Import / create by code button

The create by code button is shown in Figure 5-17.
Figure 5-17 Import/Create by code button
This will almost do the same as the lower half of the Import from repository
SmartGuide but with two additional options:
򐂰 The ability to download more then one entity by its code.
򐂰 If the entity does not exists, the option to create it.
Show details button

The show details button is shown in Figure 5-18.
Figure 5-18 Show details button
The default screen of a selected tab displays only the VisualAge Pacbase 3.0
code and the associated label. The show details button will show more specific
details of the entities in your local repository. This details will include in which
session an entity has been created or modified, its library, keywords and some
other details. In Figure 5-19, there is the code, the label, the storage library,
session number and the computed format.

Figure 5-19 Details of data elements
5.2 The workspace manager

In VisualAge Pacbase we work with entities that we have downloaded from the
server and entities that we have created locally. VisualAge Pacbase provides us
with the workspace manage and, as the name suggests, the workspace
manager is there for you to manage your workspace. This is shown in Figure
5-20.

Figure 5-20 The workspace manager
Next we will go through all four tabs in the workspace manager.
5.2.1 The local update tab

This tab gives you four possibilities to update your local repository or the one on
the server. Most of these possibilities are available on the workbench but there
they work only for one selected entity at a time. These four work on all the
entities on your local repository.
Refresh updated entities list

This button, as shown in Figure 5-21, will look at the entities you have updated in
your local repository and compare them with the entities stored in the server
repository. This comparison will be made by matching the timestamp from the
entity stored locally with the one stored on the server. This timestamp on your
local entity is the time when this entity was downloaded from the server. If the
entity on the server has a timestamp more current then the local one, the local
one will be updated by the server. The Workbench will issue a warning window
asking you if you really want to proceed.

Figure 5-21 The refresh updated entities list button
Refresh all
To make sure you have the latest version of a downloaded entity there is the
refresh all button as shown in Figure 5-22. This button will retrieve all the latest
versions of downloaded entities from the server.
Figure 5-22 Refresh all button
Discard all changes

Do you know this feeling? You have been working on a problem in an application
and suddenly you realize your on the wrong path. All your changes are useless
and its better to start all over again with the original program. For occasions like
that there is the discard all changes button as shown in Figure 5-23. All your
unsaved work will be restored, all your changes will be ignored.
Figure 5-23 Discard all changes button
Save all
Instead of having to save changed entities one at a time you can save them all at
once by pressing the save all button, seen in Figure 5-24.
Figure 5-24 Save all button

5.2.2 All problems tab
Whenever you leave an error in an entity, VisualAge Pacbase will warn you by
displaying a red error cross on the bottom left of your window (next figure). This
cross will also appear in front of the incorrect entity when displayed in a list. To
get a complete overview of your errors there is the all problems tab. This will list
all your errors along with the messages indicating what is wrong. You can select
an occurrence of this list by double-clicking it. This will open the window
associated with this occurrence in which you can correct the entity. If you want
your error containing entity to be replaced by the version in the server repository,
press the refresh invalid entities button as shown in Figure 5-25.
Figure 5-25 Refresh invalid entities button
5.2.3 Libraries
This tab will show you all the libraries in the server repository. If you select a
library you can see the definition the VisualAge Pacbase administrator has given
to the library.
5.2.4 Log tab

The log keeps track of all communications between your Workbench and the
VisualAge Pacbase server. It will display what you have uploaded, whether it was
successful, and how long it took. It will also tell you why something went wrong
with an up- or download.
5.3 Generation manager

VisualAge Pacbase programs need to be generated. The place to do this is the
Generation Manager. This will list all the options you have for generation,
everything from folders to servers and from batch programs to e-business
applications. The generation manager consists of two tabs. The generation
command lines tab and the JCL tab.

5.3.1 Generation command lines
Figure 5-26 shows results from selecting the tab from which you will run your
generation. Here you select what you will be generating.
Figure 5-26 Generation manager
New command line button

Clicking the button shown in Figure 5-27 will make the SmartGuide pop up as
shown in Figure 5-28. You need to create a command line for every entity you
want to generate.
Figure 5-27 Create new command line button

Figure 5-28 Create generation command line SmartGuide
Using the list box, you select the type of generation you want. If you select one of
the options to generated an application, for instance, Generate Folder, an extra
button will appear between the list box and libraries. By clicking this button you
can select the entity you want to generate.
Save button
This will save the command lines you have entered.
Submit and Save button

This button, as shown in Figure 5-29, will start the generation of the entity you
have selected. It will also save your command line.

Figure 5-29 Submit and save button
5.3.2 JCL
This tab has no use in our redbook Windows NT-environment. If you work on a
different platform, for example MVS, check the VisualAge Pacbase guide and
your platform guide.
5.4 Programming concepts

Every VisualAge Pacbase program is organized as a set of successive
processing steps that are performed in a loop. These processing steps include:
򐂰 Getting the data
򐂰 Checks
򐂰 Updates
򐂰 Printings
򐂰 Returning the output
Each one of these processing steps consists of a group of homogeneous

sequences of instructions called functions. A program is structured based on two
supplementary principles:
򐂰 Linear linking of functions in the logical order of their execution, with each
executing a functional or technological task in the program. Each function is
identified by a code from 0A to 99.
򐂰 Hierarchical structuring of the processing steps in each function. A function
can be broken down into sub-functions, which, in turn, can be further broken
down into sub-functions, and so on.
Functions and sub-functions follow one another in the order of their codes, as
determined by the EBCDIC standard collating sequence, with letters preceding
numbers, regardless of the sorting sequence in effect for the hardware being
used. In e-business development you are able to alter the sequence by using
relative positioning.
Hierarchical structuring is done by leveling. Functions always start with a level

05. Sub-functions start with a level 10 by default. However, they can be any level
from 06 to 98.

Within a given function, a level 15 sub-function is part of the level 06 to 14
sub-functions which precede it. In other words, a sub-function of a logically lower
level will have a level number that is greater. For example, a level 15
sub-function is logically dependent on, or inferior to, a level 14 sub-function.
In this way, a sub-function dependent on another sub-function, is only executed

under the conditions of execution of the logically higher level sub-function. The
following example, as shown in Figure 5-30, should make this more
understandable.
Figure 5-30 Levelling
Here you see the two VisualAge Pacbase functions from Figure 5-30:
򐂰 Function 60: Where am I living?
򐂰 Function 65: Dinner
Function 60 deals with where the person is living. Function 65 deals with what
the person is going to eat for dinner. No matter where the person lives on the
globe, that person is going to Pizzeria Grill La Romagnola for pizza tonight.
Functions 60 and 65 are linearly linked to each other, but only in the sense that
function 60 will execute before function 65.
For the sub-functions it is different. They are dependent on the hierarchy

established by the level numbers. Figure 5-31 shows you the how the code will
look for function 60.

Figure 5-31 Function 60
Level numbers are responsible for the level hierarchy. The lowest level number,
05, stands at the top of the level hierarchy. Level 98 has the highest level number
and stands at the absolute bottom of the hierarchy. So when we take a look at
the sub-functions used in the preceding figure, more things should become clear
as follows:.
򐂰 Sub-function 60BA, at level 10, will be executed if the Country is France.
򐂰 Sub-function 60BG, at level 15, will only be executed if sub-function 60BA has
been executed and the City is Paris.
򐂰 Sub-function 60BK, at level 20, will only be executed if sub-functions 60BA
and 60BG have been executed and the CityArea is Louvre.
򐂰 Sub-function 60BR, at level 15, will only be executed if sub-function 60BA has
been executed and the City is Marseille.
򐂰 Sub-function 60DA, at level 10, will only be executed if the Country is not
France.
򐂰 Sub-function 60DG, at level 15, will only be executed if sub-function 60DA
has been executed and the Continent is Europe.

򐂰 Sub-function 60DK, at level 15, will only be executed if sub-function 60DA has
been executed and the Continent is North America.
For the sub-function 60DK it does not matter if sub-function 60DG is executed or
not. It stands at the same level as 60DG and its condition will be checked
regardless of whether the condition in 60DG is true or false.
5.5 Development with the e-business Workbench

We will now explain the tabs in the e-business Workbench. These tabs represent
different VisualAge Pacbase 3.0 entities.
5.5.1 Data elements

A data element is a unit of data, considered “elementary” during at least one
stage in the development of a project. The purpose of a data element is to
identify and describe all pieces of information used by the applications.
We will now show you how to create elements using VisualAge Pacbase. We will
create three data elements:
򐂰 An Alphanumeric Data Element called Ship
򐂰 A Numeric Data Element called Cabins
򐂰 A Date Element called Inserv
To create a data element, click the Create a Data Element button in the tool bar.
The create a data element button is shown in Figure 5-32.
Figure 5-32 Create data element button
This action will activate the SmartGuide for creating Data Elements. We start by
creating the data element Ship, proceeding through these steps:
1. In the Code field, type the code of the element, we will use Ship. The length of
the code of a Data Element can vary between one to six characters. For
further restrictions on the code, refer to the on-line help for Data Elements.
2. In the Label field, type a clear name for the Data Element, in our example we
use Name of Ship.
3. Change the Length to 10.
4. Click Finish.

You have now created a Data Element called Ship with the picture class X(10) in
your local repository.
Now we will create the other two Data Elements:

1. Click the Create button.
2. Type Cabins in the Code field.
3. Type Amount of Cabins on Ship in the Label field.
4. Select Numeric from the Class List box.
5. Set the Total Length to 5.
6. Set the Usage to Display.
7. Click Finish.
8. Click the Create button.
9. Type Inserv the Code field.
10.Type Service entry date of Ship in the Label field.
11.Select Date from the Class List box.
12.Select 1998-12-25 from the Format List box.
You can see your Data Elements in the Workbench Data Elements window.
Your Workbench will look something like Figure 5-33.
Figure 5-33 Data elements workbench
In front of your Data Elements you find a pictogram. Within that pictogram you
see a character. These characters refer to the picture class of the corresponding
element.

Another button you will find on the tool bar is the Create Property button as
shown in Figure 5-34. Properties are elements without any values and picture
classes. Properties are used in the early stages of data modeling.
Figure 5-34 Create property button
Data element window

When you double-click CABINS a window pops up. In this window you define
your element by providing more detail. We explain only the tabs we use in our
explanation. For more information you should see the VisualAge Pacbase guide.
Representation tab
This tab is used to specify the element’s appearance in an application. Here you
define different input or output formats. You also can create column and short
labels. There are also fields in which you can specify a default value for the field
and a simulation value.
Value Controls
Value controls are used to assign values to an element. If we were to use Cabins
as an input field we could limit the input to be between two pre-defined values.
We also could say that only specific values are allowed. You create a value by
clicking the Create Value button shown in Figure 5-35.
Figure 5-35 Create Value button
This will make a SmartGuide pop up. You have to fill in the value field and give it
a label. We used a value of 200. If we now were to create an input application
with VisualAge Pacbase we could ask VisualAge Pacbase to validate the Cabins
input. If it does not contain a value of 200, it will generate an error message.
To create an interval, click the create an interval button (next figure). In the
SmartGuide that appears you can define the interval. There are several intervals
you can use:
򐂰 (‘A’,‘Z’): This will give you a value range from A until Z including A and Z.
򐂰 )‘A’,‘Z’(: This will give you a value range between A and Z. But A and Z are
not a part of the range.

򐂰 (0,9):This will give you a value range from zero to nine including zero and
nine.
򐂰 )0,9(:This will give you a value range between zero and nine, excluding zero
and nine.
Alphanumeric values have to placed between ‘quotes’ if you want to use them as
an interval or a value.
5.5.2 Segments
A Segment entity is made of a structured collection of data elements (elementary
or group). A segment must be coupled to a Data Structure. Each segment,
described only once, can be called into any entity that uses segments (programs,
other segments, or database blocks).
In order to create a Segment we first have to create a Data Structure. The data
structure create button is shown in Figure 5-36.
Figure 5-36 Data structure create button
Complete the following:

1. Click the Create Data Structure button. The SmartGuide for the creation of
Data Structure appears.
2. In the Code field, type TE.
3. In the Label field, type Test Datastructure.
4. Click Finish.
Now you have created a Data Structure, which can contain several segments.
The create a segment button is shown in Figure 5-37.
Figure 5-37 Create a segment button

Complete the following:
1. Click the Create a Segment button. The SmartGuide Create Segment
appears.
2. In the Code field, type 01.
3. In the Label field, type Test Segment.
4. Click Finish.
Segment window
You have now created a segment definition called TE01. At this point, the
segment does not contain any elements. These are the steps to take to populate
the segment so that it becomes a collection of data elements:
1. Double-click your segment. The Segment window pops up.
2. Select the Composition tab.
– Click the Call one or more Data Elements button as shown in Figure
5-38. A window with the Label “Choose Data Elements to call” pops up as
shown in Figure 5-39. In this window you see the three Data Elements you
have created.
3. Select all three Data Elements. You can do this in any of the following ways:
– Select an element and click OK. Repeat this until you have all three Data
Elements.
– Hold down the Ctrl-key while selecting the Data Elements you want with
the mouse pointer. When you have all the elements you want release the
Ctrl-key and click OK.
– Select either the data element on top or the one at the bottom and then
press the Shift-key and select the opposite one and click OK.
Figure 5-38 Call one or more data elements button

Figure 5-39 Choose data elements to call screen
Composition tab
You have now populated your Segment with Data Elements. These Data
Elements, however, may not be in the right order. Perhaps you want the Data
Element Inserv to be on top of the list. To rearrange the composition of your
Segment you can use the Up and Down buttons on the tool bar. This is what our
Segment looks like after we re-arrange it:
򐂰 Ship
򐂰 Inserv
򐂰 Cabins
On the tool bar you have numerous buttons to alter your composition. These
buttons are outlined in Table 5-1.
Table 5-1 Composition tool bar

Button Function
Call one or more table elements Populates your table with one or more
elements
New data element call Calls one specific element in your

segment
New segment call Calls an existing segment in your segment
New group Creates a group field in your segment

Button Function
Create filler Creates a filler in your segment
New error vector Only for batch use
Up Moves the selected element higher in the

hierarchy of your segment
Down Moves the selected element lower in the

hierarchy of your segment
Refresh positions You need to refresh if you were changing

elements while the segment window was
open
Show statistics Shows you the amount of elements in your

segment and their total length
5.5.3 Programs
The reason we have added the Programs tab to the e-business Workbench is
that we need it to build a parameterized macro structure (PMS or macro). The
purpose of a macro is to standardize sequences of procedural, with possible
variations, in order to use them:
򐂰 One or more times in one program
򐂰 In several different programs
Note: A parameterized macro structure is not a sub-program. A sub-program

can only contain consecutive statements. A macro can contain
non-consecutive statements.
Structured code
The macro we are going to build has only one goal. The macro is going to display
which elementary component has been started on our Listener.
The structured code screen is separated into nine columns, each with its own
specific function, seen in Figure 5-40.
Figure 5-40 Programming bar

On the programming bar, you will find:
򐂰 Fn: Function
򐂰 Sub: Sub-function
򐂰 Ln: Line-number (can be switched on or off)
򐂰 Lv: Level-number
򐂰 O...: Operator
򐂰 Operand: Fields manipulated by the operators
򐂰 C...: Condition Type
򐂰 Condition: The condition used
Operators
VisualAge Pacbase uses a number of operators to manipulate data. Operators
are entered in the Operators column abbreviated as O.... on the programming
bar. Table 5-2 will explain twelve of the most commonly used operators in
VisualAge Pacbase.
Table 5-2 Operators

Operator Function Usage
N Note line Always at the beginning of

functions and
sub-functions. Required
field.
* Comment To place comment lines

inside functions and
sub-functions.
M Move The first operand is the

source of the move;
subsequent operands are
the targets.
P Perform Perform the function

indicated in the operand.
R Read Read file.
W Write Write a record.
ADC Get date Get system date with

century.

Operator Function Usage
C Compute The result field must be

entered as the first
operand, followed by an
equal sign(‘=’). The fields
to be computed must be
separated by the
necessary arithmetic
operators and necessary
parentheses.
A Add Addition of the first

operand to the following
operand(s).
S Subtract The first operand is

subtracted from the
second.
MP Multiply Multiplication of the first

operand by the second.
DV Divide Division of the second

operand by the first.
Condition types
Condition types are entered in the C... column. This column is used for two
reasons. The first one is for relative positioning and the second one for
programming conditions.
When entering procedural code in an elementary component you have to use

relative positioning most of the time. Relative positioning allows you to place
code in front or after generated code or even to replace it. There are certain
limitations of placing your own code in an elementary component:
򐂰 Each insertion or replacement of procedures on a logical view inside an
elementary component is limited to 36 sub-functions.
򐂰 The replacement of a check on a data element or the insertion of such a
check is limited to only one sub-function per data element and 90 lines of
generated code for each of these sub-functions.
򐂰 In an elementary component used by a graphic application, no provoked
abends are authorized.
򐂰 Functions OA, 80 and 81 are not suited for relative positioning.
Table 5-3 contains the relative positioning condition types.

Table 5-3 Relative positioning condition types
Condition type Usage
Ante Insertion before the automatically

generated code.
Post Insertion after the automatically generated

code.
Replace Replacement of the automatically

generated code.
Complete Insertion or replacement of the processing

on the server or the Logical View.
Complete should only be used at an 05
level.
The condition type for relative positioning must always be followed by a condition
line. On this condition line you have to define where you want your code to be
placed. In your code these condition types are abbreviated. They start with an
asterisk (*) and are followed by the first character of the name. Table 5-4 shows
examples of condition types and lines with explanations.
Table 5-4 Examples of condition types

Condition type Condition line Explanation
*A SHIP Allows you to place coding

before the generated code
for evaluation of the data
element SHIP
*P SHIP Allows you to place coding

behind the generated code
for the evaluation of the
data element SHIP
*R SHIP Allows you to replace the

generated code with code
of your own for the
evaluation of the data
element SHIP.
*B SHIP Allows you to place code

between the generated
label and the generated
code for the evaluation of
the data element SHIP

Condition type Condition line Explanation
*C BS A Places code before Begin

BS R Server (BS)
BS P Replaces code of Begin
Server (BS)
Places code behind Begin
Server (BS)
As in every other programming language VisualAge Pacbase 3.0 has

programming conditions as shown in Table 5-5.
Table 5-5 Programming conditions

Block Default value for all non-conditioned

structures.
If Then Default value for all conditioned

structures. Executed if the condition is
satisfied.
Else Prohibited at the function level.

Executed if the preceding structure at the
same level (which must be an ‘If Then’)
was not executed. An ‘Else’ structure
cannot have its own condition.
Case Of Prohibited at the ‘05’ function level and at

the ‘99’ level.
A ‘CO’ structure is used for procedures
that are exclusive of each other, and that
are executed depending on the possible
values of a variable.
In a ‘Case Of’ structure only the name of
the variable is defined (in the condition
field and on a single line). The possible
values of this variable are specified in the
structures at the next lower,
non-elementary, hierarchical level.
Do While Prohibited at the ‘05’ function level and at

the ‘99’ level.
This structure is executed repeatedly, as
long as its condition is satisfied.

Do Until Prohibited at the ‘05’ function level and at

the ‘99’ level;.
This structure is executed repeatedly until
its condition is satisfied. Thus, it is
executed at least one time.
For the ‘DW’ and the ‘DU’ type structures,
the user must set up the condition status
(incrementing of an index, for example).
DO 2d ‘sf’ standing for the SUB-FUNCTION

CODE.
OR Continuation of the condition associated

with the preceding lines by a logical ‘OR’.
AND Continuation of the condition associated

with the preceding lines by a logical ‘AND’.
Creating a macro
When you select the Programs tab, you will find two yellow buttons. The one we
need is the one with the dollar sign in it, seen in Figure 5-41.
Figure 5-41 Create a macro structure button
After clicking this button, you have to fill in two fields on the SmartGuide that
appears:
򐂰 Code: We used MarkII
򐂰 Label: We used Begin Server Message
Parameters
A parameterized macro structure (PMS) uses parameters of course. These
parameters are identified by a dollar sign ($) followed by a character. A macro
structure in VisualAge Pacbase can contain twenty parameters. These twenty
parameters range from $1 to $0 and from $A to $J.
In our macro we are going to use only one parameter. This parameter is going to
contain the name of the elementary component. Here is what needs to be done:

򐂰 Select the parameter code you want to use. We used $1.
򐂰 Label: We used Name of Elem Comp.
򐂰 Type: We used alphanumeric.
򐂰 Minimum size: We used 1.
򐂰 Maximum size: We used 36.
Source tab
The source tab is the place to put the structured code for a PMS. By clicking the
Create a function/sub-function button in Figure 5-42, we can create one.
Figure 5-42 Create a function/sub-function button
For creating the function, we filled in the following fields in the SmartGuide:
򐂰 Function: We used 01.
򐂰 Title: We used Display Messages.
For creating the sub-function, we filled in the following fields in the SmartGuide:
򐂰 Function: We used 01.
򐂰 Subfunction: We used BB.
򐂰 Level: We used 10.
򐂰 Title: We used Message Display.
򐂰 Condition: We used Complete.
򐂰 Condition line: We used BS A.
Our Source now looks like Figure 5-43.
Figure 5-43 Code in the macro

This macro can now be used in any elementary component we want. In each
elementary component we use we give the name of that elementary component
to replace the $1.
5.5.4 Logical views

A logical view contains the data elements you want to use in your e-business
application. A logical view is the way to describe a set of elementary information.
It is made of a collection of data elements that describe the structure of a
business concept. The logical view is to be considered as a business-oriented
set of data on which services are required in order to accomplish a user task.
We show you the logical view tab and the rest of the e-business Workbench by
using one of the proxies for our sample application.
Creating a logical view definition

Like all VisualAge Pacbase entities, a logical view has a definition. In order to
create a logical view, you have to click the Create new Logical View (LV) button
on the tool bar, as shown in Figure 5-44.
Figure 5-44 Create new logical view button
The creation SmartGuide appears. Here we fill in three mandatory fields:

򐂰 Code: We used Destination.
򐂰 Label: Again we used Destination.
򐂰 Short Code: We used BT02.
If we now select our Destination we open the logical view browser.
Definition tab
Here you will find the definition you produced with the SmartGuide.
Composition tab
The Composition tab is labeled with a question mark. Here we populate our
logical view in almost the same manner as we populated the segment TE01. We
add elements to the logical view by creating a composition line. We populated
our logical view with the following elements:
򐂰 Portid: Port identifier.
򐂰 Portnm: Port name.
򐂰 Ctrynm: Country in which the port is located.

The logical view composition tab contains a tool bar with which you can adjust
your composition. Table 5-6 shows the buttons and functions associated with
them.
Table 5-6 Logical view composition tool bar

Button Function
Add a composition line Adds an element to your logical view.
Shift up Moves a selected element one place

higher in the hierarchy.
Shift down Moves a selected element one place

lower in the hierarchy.
Increment indentation Removes a selected element from a data

element group.
Decrement indentation Puts a selected element in a data element

group. The element will be placed in a
group that was or will be created
automatically above it.
Extract Methods tab

An extract method is described when there is a need for a conditional selection
on the logical view instances. For example, you may want to narrow the scope of
the returned selection or to sort the retrieved instances. These conditions apply
to the logical view content, and therefore are independent of the physical
resources from where the logical view instances are built. This ensures the
portability of the extract methods.
Note: Extract methods should be used only for simple requests on the
database, otherwise methods should be written in the elementary components
that support more complex code. Extract methods are interesting only if they
do not concern the table keys, since such accesses are dealt with by the
elementary components. Sort methods would only be used to sort the results
of the extract method defined.
5.5.5 Elementary components

An elementary component is a component that runs on the server side of the
application and supports a set of services on a logical view. These services may
be generic and dedicated to selections and updates on the logical view, or they
may be specific and support functional requirements.

Creating an elementary component
The first step in VisualAge Pacbase 3.0 to create any entity is to create the
definition of that entity. So, in order to create an elementary component, we click
the Create new Elementary Component (EC) button found on the tool bar,
Figure 5-45 Create new elementary component (EC) button
In the SmartGuide that appears we fill in the following fields:

򐂰 Code: We filled in Destination.
򐂰 Label: Here We used Destination.
򐂰 Short code: We used EC1000.
򐂰 COBOL program ID: We used this name, PGMDES.
򐂰 Type of code to generate: We used VisualAge for COBOL.
We have now created the definition for one elementary component called
Destination. When we double-click our creation the elementary components
browser pops up.
Definition tab
In the definition tab, you can change the fields which make up your definition
except for two fields. These are:
򐂰 The Code field
򐂰 The Short code field
Composition tab
In an elementary component we will call persistency objects. A persistent object
is described by a collection of data elements that defines its internal structure. A
persistency object is a component that manages persistency on the following
physical data storage systems.
򐂰 Another elementary component, which manages access to data contained in
a logical view.
򐂰 A table or a relational database.
򐂰 A DL1 database record.
򐂰 A mono or multi-structure file.
򐂰 A working area.
򐂰 A Pactable table, optional VisualAge Pacbase 3.0 module.

We are using a DB2 relational database as our persistency object. So to create
our composition we select the relational database icon from the tool bar as
Figure 5-46 Add relational database button
In the SmartGuide you have to name your relational database. We used the
name Cruise.
Now that we have indicated what kind of persistency object we will be using we
need to tell VisualAge Pacbase which persistency object we will be using. We do
this by clicking the Add persistency object button, shown in Figure 5-47,on the
tool bar.
Figure 5-47 Add persistence object button
We have to fill in two fields in the SmartGuide. Those fields are:

򐂰 Generation code, we used TB01, which is the code of the persistency object
we will select.
򐂰 Segment referential code. We select TB01, which is our destinations
segment.
Our definition window now looks like the one in Figure 5-48.
Figure 5-48 Definition window

Now we need to assign our logical view, Destination, to our persistency object
TB01. We will start this by creating a new composition line using the create new
composition button in Figure 5-49 in the top right window of our screen called List
of managed LV.
Figure 5-49 Create new composition button
In the SmartGuide that appears, we have to fill in the following fields:

򐂰 Generation code. In our case BT05.
򐂰 Logical view short code. We selected Destination.
򐂰 Iterative capacity. We chose ten. This is the number of occurrences of data
that you want your logical view to select.
򐂰 Logical view use. We used Destination Class.
The relationship between a logical view and persistency object is based on the
processing, triggered by a server call, of a collection of N instances of the logical
view, N being the number of instances that navigate between client and server at
once and being limited by the iterative capacity of the logical view. We create this
relationship in the central right window.
In order to activate this window, we select the logical view call from the List of
managed LV window. We can drag and drop the persistency object, which we
have defined in the Definition window on the right, into this window. We select
the type of access we need to our persistency object from the list box located
directly under the title bar. We selected Standard Update. Our window now looks
like Figure 5-50.
Figure 5-50 PO cinemtics window

We still have not identified the source data elements for the data elements in the
logical view. We will do this in the window appropriately named dataElement
Transfer. There are two types of transfers between the logical view and the
persistency objects:
򐂰 Key transfer
򐂰 Field transfer
To fill the key fields in the dataElements Transfer window we need to select the
TB01 from the PO cinemtics window. Now we can Add the key field. The
dataElements transfer identifier and transfer field are listed in Table 5-7 and Table
5-8.
Table 5-7 Data element transfer identifier

Source identifier Target identifier
Portid Portid
Table 5-8 Data element transfer fields

Source field Target field
Portnm Portnm
Ctrynm Ctrynm
Structured code tab

The structured code tab is the place to enter your own specific programming
logic. This tab is subdivided into four smaller tabs:
򐂰 Procedural code
򐂰 Working storage
򐂰 Macro calls
򐂰 Beginning Insertions
Procedural code
The first thing you will see when you enter this window is all the logic VisualAge
Pacbase has generated so far. This is more than sufficient to run your program.
But there could always be some sort of reason that you would want to place
specific code into the program. If you do want to add your own logic be very
careful were you place it. Also think very carefully were you want to place it. Not
every piece of code will be executed all the time. Figure 5-51 gives you a global
idea what each elementary component does in the logic.

Figure 5-51 Elementary component

Macro calls tab
After clicking the Add a new macro call button a SmartGuide appears which will
guide you through the macro call process:
򐂰 Parameterized macro call: select MARKII
򐂰 In the value field behind $1: Destination.
When you now go back to the procedural code tab you will see that your macro
code has been placed there. Notice also that the code of your macro is indicated
by the color green.
5.5.6 e-business application

The e-business application component in VisualAge Pacbase aims at grouping a
set of parameters which are common to elementary components, folders,
communication monitors and only one error server. It is mandatory to define an
application previous to creating the folders. Before we can create the e-business
application we first must create a working file and an error file.
Creating the working file

The working file is a technical file that is used by the communication monitor to
temporarily store the information which is necessary to build the request or its
response when several messages are required.
The working file may be stored as a DB2 table, but for performance reasons we
recommend using an indexed file. This working file must also be defined in
VisualAge Pacbase as follows:
1. We created a data structure CR with the label Working File Structure.
2. The second step was to create a segment CR00 called Common Part.
3. We filled this segment with two data elements.
– KEYWF, alphanumeric 37 positions, labeled Key of the Working File.
– DETAIL, alphanumeric 250 positions, labeled Content of the Working File
The error file

We stored our errors, keys and labels, in our DB2 database. Our segment is
defined as follows:
򐂰 Code: TB00
򐂰 Label: T_Lier
򐂰 Composition
– ERKEY, alphanumeric 29 positions, labeled Error Key.
– LIBELE, alphanumeric 71 positions, labeled Error Label.

Creating the e-business application
We can only create e-business applications in the e-business tab. Here we find
the Create new e-business Application (EA) button, shown in Figure 5-52.
Figure 5-52 Create new e-business application button
Clicking this button activates the creation SmartGuide. Here we fill in the
following fields:
򐂰 Code: CruiseApplication.
򐂰 Label: Cruise Application.
򐂰 Short Code: Cruise.
򐂰 Associated Package: com.cruise.cruiseline.proxies. This is the name of the
Java package that will be created when generating the proxy.
򐂰 Working file: CR00.
򐂰 File Type: File.
򐂰 Working file logical name: WF00.
򐂰 Click Finish.
We now double-click our creation to open it.
e-definition tab
By using the SmartGuide we have filled in all the things we needed on our
definition screen.
e-error Server
Here we give our error server its generation details. We call the error segment
we created before.
Generation
Our server will be a COBOL program compiled with the VisualAge for COBOL
compiler. Here we define the COBOL program ID and the Type of code to
generate:
򐂰 COBOL program ID: SERVERR
򐂰 Type of code to generate: VisualAge COBOL.

Error Labels File
Here we need to define what kind of file we are using, how it must be accessed,
and how it is defined in the repository:
򐂰 File type: Relational object
򐂰 The check box File Description is checked.
򐂰 Error server segment referential code: TB00 T_Lier
򐂰 Segment key code: ERKEY
򐂰 Relational object type: Table
򐂰 Data base block code: Cruise
򐂰 Data base block location: Local
The other four tabs of the Error Labels File are not needed in our redbook
sample application.
e-business common area

This is not used in our redbook sample application.
e-database
Here we define the database our application is using. For performance reasons it
is better if it is also local to the servers:
򐂰 Connection database block code: CRUISE
򐂰 Connection database location: Local
5.5.7 Folders
A folder groups a set of services nodes: thus it is a complex information concept
built from a set of elementary information concepts linked through hierarchical or
reference relationships. It supports a set of consistent services required to
accomplish user tasks and also manages data consistency.
A complete services node corresponds to a pair of two types of components: a

logical view and an elementary component.
Creating a folder
We create a folder by first establishing its definition, using the button in Figure
5-53.
Figure 5-53 Create new folder (FO) button

We have to fill in the following fields in the SmartGuide that appears:
򐂰 Code: Destination
򐂰 Label: Destination Folder
򐂰 Short Code: Destin
򐂰 e-business application shortcode: CruiseApplication
򐂰 Cobol program ID: Destin
򐂰 Type of code to generate: VisualAge COBOL
򐂰 Package code: com.cruise.destination.proxies
򐂰 Click NEXT
In the window that appears we will give our root node a name for our folder
nodes hierarchy. We select the logical view and the elementary component we
want to use. To be able to generate our folder later we must give generation
codes and classes. A proxy node is generated into three Java classes:
򐂰 HierarchicalNode
򐂰 DataDescription
򐂰 SelectionCriteria
Figure 5-54 shows what we filled in.
Figure 5-54 Properties window
We not only created the definition, but also the root node of our folder, which is
shown in the composition tab. There is however one very important thing missing
here. That is the Node identifying. The node identifier is the key field to the

logical view. By clicking the button on this line we can select our node identifier
from the list of data elements in the logical view. We select data element Portid
as out identifier as shown in Figure 5-55.
Figure 5-55 Select identifier window
5.5.8 Communication monitors

The communication monitor plays several roles:
򐂰 It manages communication functions, sending and receiving of messages
according to the platform.
򐂰 It controls each received message.
򐂰 It controls the reception and the sending of messages.
򐂰 It calls the appropriate folder managers depending of the request it receives.
򐂰 It manages the transaction, that is commits and rollbacks when errors occur.
Creating a communication monitor.

To create a definition for a communication monitor, we click the Create new
Communication Monitor (CM) button, seen in Figure 5-56.
Figure 5-56 Create new communication monitor button

We filled in the following fields in the creation SmartGuide:
򐂰 Code: CruiseCommunication
򐂰 Label: Communication monitor for cruise
򐂰 Short code: COMSER
򐂰 e-business application code: CruiseApplication
򐂰 Message size: 008.
򐂰 Protocol code: Sockets
򐂰 COBOL program ID: COMMONIT

6
Chapter 6. Reuse and portability in

VisualAge Pacbase
In this chapter we describe how to position, structure, and populate the
VisualAge Pacbase repository in order to promote reusability of application
components. We examine how the information about the application components
in the VisualAge Pacbase repository is cross-referenced and consider how those
cross-references play a part in maintenance and enhancement activities. This
includes a discussion on the portability of application components and the
generated applications.

6.1 Reusability
Using existing application components to assemble new applications is the major
strength of the VisualAge Pacbase product. Re-using application components
provides these advantages:
򐂰 Reliable code
򐂰 Accelerated development
򐂰 Ease of maintenance
Re-using existing application components provides more reliable code, since the
component has already been proven to work properly in the production
environment. A calculation, for example, may need to be performed as a precise
set of operations. Writing the code for this calculation once and then re-using that
code assures that the operations will be performed correctly.
When components are re-used for development, a time-saving is realized

because that component does not need to be specified, coded, and tested.
Components that can be re-used are generally identified during the analysis and
design phase of the development life-cycle and then included in the application.
A common maintenance scenario is to respond to change requests in an efficient

and thorough manner. A change request, for example, may require a modification
to our example of a re-used calculation in order to add additional operations.
VisualAge Pacbase allows you to accurately locate the code that needs to be
modified within the repository, modify the code, and then systematically
propagate the change to the application components. More will be said about this
later in this chapter in the discussion about using the VisualAge Pacbase
cross-references.
6.1.1 Reusable components

Re-using application components is highly dependent on establishing the proper
structure for managing the content of the VisualAge Pacbase repository. The
content of a VisualAge Pacbase repository consists of entities. An entity is
anything for which information needs to be stored in order to generate an
application component.
VisualAge Pacbase includes standard entities for many of the data and
processing needs of most applications while other entities exist to support the
production of documentation from the VisualAge repository. In addition, you can
define entities in the VisualAge Pacbase repository to meet the specific needs of
your organization. These are referred to as meta-entities (formerly called
user-entities in previous releases of VisualAge Pacbase) and are not in the
scope of this redbook.

Standard entities in VisualAge Pacbase can be grouped as either data,
processing, or documentation entities. Data entities allow you to describe
variables and group variables into collections. Data entities become the input,
output and intermediate work areas for the processing entities. Processing
entities in VisualAge Pacbase correspond to such things as programs and
reports. These combine and re-use the data entities, other processing entities,
and unique logic to produce an application component. Documentation entities
complete the information about an application within the repository and allow you
to use that information for end-user help and to publish technical and end-user
manuals.
6.1.2 Organizing the repository for reusability

The VisualAge Pacbase repository needs to be organized to achieve reusability
and to control the access to entities stored within the VisualAge Pacbase
repository. Logically, the content of the repository is organized hierarchically as a
set of libraries, so that content in higher-level libraries is available for use in lower
libraries. At the higher levels, the content of each library is predominately one
type of entity or contains entities that share a common theme.
Data considerations
Data entities are re-used frequently across the application components within the
VisualAge Pacbase repository. In this sense, the VisualAge Pacbase repository
functions as a data dictionary and serves as the authoritative source of
information about the organization’s data model. For this reason, the data entities
are positioned at a high level within the VisualAge Pacbase library hierarchy.
Documentation considerations
Documentation that describes your organization’s standards for the use of the
VisualAge Pacbase repository is normally positioned at a higher level library so
that it can be read by all users of the repository. Often, templates are placed in a
higher level library to demonstrate the use of your organization’s standards for
each type of entity.
Processing considerations
VisualAge Pacbase processing entities are re-used to a lesser extent than data
entities. Of particular note, however, is the concept of parameterized macro
structures, referred to simply as “macros”. Macros are re-usable code fragments
that are called into other processing entities to produce code or to supplement
the code of the programmer.
Chapter 6. Reuse and portability in VisualAge Pacbase 187

Macros can have a variety of uses. A macro, for example, may:
򐂰 Create intermediate work areas in a processing entity
򐂰 Add processing logic to a processing entity
򐂰 Combine with other macros to provide a complete unit of code to add
functionality to the processing entity
Macros are positioned at a higher level within the VisualAge Pacbase repository
to maximize their reusability. Since macros manipulate data entities, they are
positioned subordinate to the data entities in the repository.
Application component considerations

Entities that represent the application components are positioned in lower levels
of the library hierarchy and access is restricted to the developers that are
producing the application. Organizations generally arrange the lower level
libraries that contain entities for application components according to major
systems.
6.1.3 Libraries
Libraries in the repository are used to position entities for reuse across the
applications developed with VisualAge Pacbase and also serve to limit access to
the entities which they contain. For example, it is ill-advised to allow everyone in
your organization to modify the data entities that represent the data model for
your organization. Normally, only staff members responsible for data
administration would have this responsibility.
The VisualAge Pacbase administrator establishes the library access for each
VisualAge Pacbase user (read-only or update, for example). Libraries are entities
in the VisualAge Pacbase repository managed by the VisualAge Pacbase
administrator. Each library is identified by a three character code chosen by your
organization and each library has a label that is used to describe its content or
theme. Libraries within the VisualAge Pacbase repository can be thought of as
consisting of two layers, an administrative layer and a development layer. Figure
6-1 shows the typical structure of the administrative layer of the VisualAge
Pacbase library hierarchy.

DTA
STD
Administrative
MAC
Development
SY1 SY2
AP1 AP2
VR1 VR2
Figure 6-1 Administrative library layer
The highest level library (DTA) is controlled by the data administration staff and
contains the data entities such as data elements, data structures, segments, and
database blocks.
Below the DTA library is the library (STD) used for entities that describe the
organizations standards.
Below the STD library is the library (MAC) used to manage the macros (reusable
code fragments) that are of interest to the entire organization.
Figure 6-2 shows the development layer positioned below the administrative
layer in the VisualAge Pacbase repository.

DTA
STD
Administrative
MAC
Development
SY1 SY2
AP1 AP2
VR1 VR2
Figure 6-2 Development libraries
The MAC library in the preceding figure is the same library in the figure for the
administrative layer. The MAC library, which contains the macros for the
organization, can be considered to be part of both the administrative layer and
the development layer.
Below the MAC library, the content of the VisualAge Pacbase repository can be
organized based on major systems within your organization (SY1 and SY2 in the
figure). An example of a major system might be Finance.
A major system can be organized into libraries for its applications which will
contain the corresponding entities in VisualAge Pacbase used to generate the
application components (shown by AP1 and AP2 in the figure). Extending our
Finance example, AP1 and AP2 might be PAYROLL and GENERAL LEDGER.
It is possible to use the VisualAge Pacbase library structure to manage different

versions of the entities used to generate the application components (shown in
the figure as VR1 and VR2). Versions, in this sense, refer to application

components that must be generated to run in different environments and which
require the addition of unique code for that hardware or operating system.
Library structures can be as simple or as complex as your organization requires.
6.1.4 Positioning the repository

The repository environment for VisualAge Pacbase 3.0 is a distributed
environment. The authoritative version of the repository is positioned on a server
and each VisualAge Pacbase user can have one or more local copies of the
repository database content on their workstation. These local copies are
synchronized to the server repository databases on an ongoing basis to ensure
that the server repository functions as the authoritative source of repository
content. The process of retrieving content from the server in order to create or
refresh a local copy is referred to as importing. The redbook chapter about the
developer workstation contains information about importing entities.
6.2 Data entities

Entities that describe the organization’s data model include:
򐂰 Data elements
򐂰 Data structures and segments
򐂰 Database blocks
Establishing the data entities in the VisualAge Pacbase repository is a start up

activity that must be done by the organization shortly after the VisualAge
Pacbase product is installed. This activity is normally done by the data
administration staff. As time goes on, the organization’s data model becomes
more fully described through the data entities in the VisualAge Pacbase
repository and this activity diminishes.
6.2.1 Data elements

Data elements represent the most basic information about the organization’s
data model.Data elements represent attributes of objects and can be likened to:
򐂰 Variables in most programming languages
򐂰 Properties in other programming languages
򐂰 Entries in a data dictionary
򐂰 Columns in tables
򐂰 Fields in a COBOL program
Data elements are used throughout your code in calculations, data manipulation,
and to store values.

Because data elements are the foundation of the organization’s data model,
proper use of the VisualAge Pacbase repository mandates that data elements be
established as the single authoritative source about the objects related to the
organization’s activity. This is best accomplished by establishing a limited set of
data elements to be used by developers in the VisualAge Pacbase repository.
6.2.2 Data structures and segments

Collections of data elements are referred to as segments in VisualAge Pacbase
and the segment entity establishes and describes a collection of data elements.
Segment entities are then used to describe such things as:
򐂰 Program input and output files
򐂰 Work areas in programs
򐂰 Tables and arrays
򐂰 Hierarchical databases
򐂰 Relational tables and views
򐂰 Logical views
A collection of segments is referred to as a data structure and the data structure

entity in VisualAge Pacbase establishes a collection of related segments. A data
structure is used primarily in batch programming to indicate program inputs and
outputs.
6.2.3 Database blocks

The database block entity in VisualAge Pacbase is used to assemble segments
into databases. A variety of hierarchical and relational database management
systems is supported by VisualAge Pacbase. For information regarding a
specific database management system contact IBM or visit the IBM VisualAge
Pacbase Web site at:
www.software.ibm.com/ad/
The database block entity provides VisualAge Pacbase with the ability to
generate DDL (data definition language) and establishes the VisualAge Pacbase
repository as the authoritative source of information about your organization’s
databases. VisualAge Pacbase becomes a tool for the data base administration
staff to manage the DDL.
The database block entities are usually positioned with the other data entities at
a high level in the VisualAge Pacbase library hierarchy.

6.3 Documentation entities
VisualAge Pacbase supports the full life-cycle of application development activity.
In general terms this activity consists of:
򐂰 Analysis
򐂰 Design
򐂰 Construction
򐂰 Testing
򐂰 Deployment
Much of the activity throughout this life-cycle results in specifications and

descriptions. These aspects of your activity are managed by the publishing
facility in VisualAge Pacbase.
6.3.1 Descriptions
Descriptive detail can be developed with your choice of word processor and then
related to entities within VisualAge Pacbase. This provides the advantage of
being able to write one description and to associate it with several related
entities.
Another approach is to use the extensibility feature of VisualAge Pacbase. The

extensibility feature allows you to create new types of entities to suit your
organizations needs and then to define occurrences of these new entities in the
VisualAge Pacbase repository. This new entity occurrence can be related to the
standard VisualAge Pacbase entities as well as other entities you create through
the extensibility feature.
For example, you may decide to create a new entity called Project. You could
create an occurrence of the Project entity called Redbook and capture attributes
about the Project such as its beginning date, expected completion, and manager.
You could then relate this Project entity to such standard entities as data
structures, segments, programs, and reports that are created as part of the
project.
Descriptive entities exist at all library levels within the VisualAge Pacbase
repository. Relative to reusability, these entities need to be positioned at a library
level within the hierarchy that will make them visible and accessible to
developers in lower libraries that desire to use these as part of their application.

6.3.2 Publishing facility
The publishing facility in VisualAge Pacbase is used to assemble and generate
descriptive detail using the content of the repository. You can use the publishing
facility to include the information that defines and describes the VisualAge
Pacbase entities that are part of your application. The publishing facility gives you
the ability to describe detail in a manner fully customizable to suit the needs of
your organization and your e-business applications.
The publishing facility allows you to:

򐂰 Publish the descriptive entities that pertain to your application
򐂰 Publish VisualAge Pacbase entities (for example, data elements and
segments) that are part of your application
6.3.3 Parameterized input aid

Every VisualAge Pacbase entity has a section referred to as general
documentation. The general documentation for an entity is used:
򐂰 To describe unique information about that entity occurrence
򐂰 To specify options that are taken into consideration during the generation of
that entity
򐂰 To specify error messages for limited entities
The parameterized input aid is an entity managed within the VisualAge Pacbase
repository used to structure the entry and presentation of the information for
general documentation of other entities. Parameterized input aids are often
related to an organization’s standards and are positioned as entities in the higher
level library that contains information related to standards and the use of the
VisualAge Pacbase repository.
6.4 Processing entities

Processing entities are those VisualAge Pacbase entities that result in the direct
or indirect generation of source code. These include:
򐂰 The e-business entities, new to VisualAge Pacbase 3.0
򐂰 The batch program entity
򐂰 The report entity, which is included in the batch program entity and indirectly
impacts the generated source
򐂰 The database block entity, previously discussed, which generates DDL

6.4.1 e-business
The e-business entities are new to VisualAge Pacbase 3.0. The e-business
Workbench manages:
򐂰 Folders
򐂰 Logical views
򐂰 Elementary components
򐂰 I/T server
򐂰 Communications monitor
A folder is used to group nodes and serves as the basis for generating the
VisualAge Pacbase proxy.
A logical view is a collection of data elements. It is referred to as a logical view

because it is independent of how the data elements may be physically stored.
The logical view represents the data needed for your e-business application.
An elementary component represents the processing rules for a logical view. In

order to generate the services necessary to properly access the data and apply
the business rules, the logical view and an elementary component must work
together. The term node is used to refer to the pairing of the logical view and the
elementary component.
An initialization/termination (I/T) server is used to implement specific procedures

before and after the execution of a request associated with a folder. An I/T server
is called by a folder before the first call of the elementary component associated
with the request to be processed and after the last executed elementary
component.
The e-business entities are located at the lower library levels within the
VisualAge Pacbase repository in an application library.
6.4.2 Batch programs and macros

The batch program entity in VisualAge Pacbase refers to applications that are
intended to process information without end-user interaction. Batch programs
typically read and update files involving large amounts of data. Batch program
entities are described in terms of their input and output files and databases
accessed. Batch program entities reference macros and contain code that is
unique to the batch program.
The batch program entity is also used to define macros (reusable code
fragments). When a batch program entity is used in this manner, it does not
contain any descriptions of input or output files or databases.

Batch program entities that are not macros are located at the lower library levels
within the VisualAge Pacbase repository in an application library (AP1 or AP2 in
the preceding figure). If additional versions of the batch program entity are
required, another batch program entity of the same name may exist in a version
library.
Batch program entities that are macros are located in the VisualAge Pacbase
repository based on whether they are or interest to the entire organization or
specific to a major system or one of its applications:
򐂰 If the macro is of interest to the entire organization it is positioned at the
higher library that contains such macros (MAC in our example).
򐂰 If the macro is of interest to all of the applications for a major system it is
positioned at a lower level library that will allow it to be used by all of the
applications for that major system (SY1 or SY2 in our example).
򐂰 If the macro is of interest only to the components of a specific application,
then it is positioned at the lower level library that contains the components for
that application within the VisualAge Pacbase repository (AP1 or AP2 in our
example).
Macros that pertain to additional versions of the application components would

be located at the lower level library that contains entities for that version (VR1 or
VR2 in our example).
Batch program entities that represent macros must be identified with a code that
precedes the name of the batch program that uses the macro. For this reason
many organizations establish a standard that requires the code for the macro to
begin with the letter “A” or a special character.
6.4.3 Reports
The report entity in VisualAge Pacbase describes the layout of the report, how
the information on the report is formatted, and also the conditions for printing the
different sections of the report such as the headings, detail lines, and totals. The
report entity is used by calling it into a batch program entity. The report entity can
be defined once and used in several batch program entities. During generation of
the batch program entity, the report entity is taken into account and the code
necessary to manage the report is placed into the source code for the batch
program entity.
Report entities are located at the lower library levels within the VisualAge
Pacbase repository in an application library that corresponds to the batch
program entities that use the report.

6.5 Cross-references
Cross-references continue to be a major strength of the VisualAge Pacbase
repository. Entities within the VisualAge Pacbase repository can be likened to
building blocks. Entities are used by other entities within the VisualAge Pacbase
repository to assemble application components that will result in the generation
of source code or documentation. There is a need to track how entities are used
by other entities and this is the basis of the cross references within the VisualAge
Pacbase repository.
6.5.1 Available cross-references

Cross-references within the repository can be considered to be either an implicit
cross-reference or an explicit cross-reference. An implicit cross-reference results
from the use of the workbench to call an entity into the description of another
entity. When this occurs, VisualAge Pacbase automatically manages the implicit
cross-reference that results. For example, as the programmer writes code in a
batch program entity and references a data element as a variable in a
calculation, VisualAge Pacbase automatically recognizes the reference to that
data element and builds the implicit cross-reference between the data element
and its use by the batch program.
Certain types of entities can be created and explicitly cross-referenced to other

entities. This is accomplished through the use of the extensibility feature which
allows you to create and define new entities within the repository to suit the
specific needs of your organization.
6.5.2 Maintenance considerations

Cross-references are extremely valuable during maintenance of an application.
The VisualAge Pacbase facility for creating and managing cross-references
allows you to see the impact of changes as it pertains to all of the entities in the
repository. For example, if you are considering changing a data element, you can
first use the repository cross-references for that data element to see where it
used in such things as segments, programs, and reports. This feature allows you
to assess the impact of changing the data element with a great deal of precision.
6.5.3 Cross-reference considerations

Both implicit and explicit cross-references are available for review from the
VisualAge Pacbase repository. Documentation entities are managed from the
publishing facility of the developer workbench.

The library hierarchy of the VisualAge Pacbase repository affects the use of the
cross-references. When you work in the VisualAge Pacbase repository as a
developer, you must indicate your library position as you sign on. By default,
VisualAge Pacbase allows you to view the entities in the library where you are
positioned and also entities that are within the library hierarchy where you are
positioned. The scope of your default library view is shown in Figure 6-3.
Scope of your default view

DTA
of the library hierarchy
STD
SY1 MAC
AP1 SY2
VR1 AP2 Sign-on library
VR2
Figure 6-3 Signon library view
You can change the library view option to see different views of the library
hierarchy relative to your position.

6.6 Portability
Portability, relative to VisualAge Pacbase, can refer to either the content of the
VisualAge Pacbase repository or the applications generated using that content.
6.6.1 Repository content

VisualAge Pacbase is designed to run in a variety of hardware and operating
system environments. The technical aspects of the VisualAge Pacbase
repository allow the entities stored to be extracted and placed in other compatible
VisualAge Pacbase repositories. Compatibility of VisualAge Pacbase
repositories refers to the release of the product since there can be differences in
the format of the VisualAge Pacbase entity formats among different releases of
the product.
The extraction of entities from one VisualAge Pacbase repository for placement
into another VisualAge Pacbase repository is accomplished by the execution of
utilities that are part of the VisualAge Pacbase product. The extraction utilities
produce flat files that can be used with the update utility to place the entities in a
different repository.
The design and structure of VisualAge Pacbase also makes it possible to easily
move a VisualAge Pacbase repository from one platform to another (for example
from MVS to UNIX).
Consult the VisualAge Pacbase documentation for a full discussion of the various
utilities available for managing the VisualAge Pacbase repository.
6.6.2 Generated applications

The portability of applications generated by VisualAge Pacbase refers to the
ability of VisualAge Pacbase to generate source code targeted for different
hardware platforms or operating systems. When you define an entity that is used
to generate source code, you indicate the target environment. The generator
then produces the appropriate source code for the target environment. To
generate source code for a different target environment from the same entity, you
must change the indicators for the target environment. Review the VisualAge
Pacbase documentation for information about the target environments available.

7
Chapter 7. VisualAge Pacbase

development process
In this chapter we describe the VisualAge Pacbase development process. We
discuss development in terms of analysis, design, construction, testing, and
deployment. We introduce both the forward and the backward development paths
before presenting the main steps of the forward development path.

7.1 Overview
For our simplified redbook discussion, development consists of:
򐂰 Analysis
򐂰 Design
򐂰 Construction
򐂰 Testing
򐂰 Deployment
We introduce both the forward and the backward development paths before
presenting the main steps of the forward development path.
Chapters 8 to 13 detail the forward development main steps, while chapters 14 to

19 apply these steps to the VisualAge Cruise Lines sample application.
7.2 Development paths

In this section we describe the forward and backward development paths.
7.2.1 Forward development path

The forward development path is a top-down approach.
7.2.2 Analysis and design

This approach starts with the following analysis and design steps:
1. Building the Analysis Model, using the Unified Modeling Language (UML) and
possibly a tool such as Rational Rose
2. Building a design model and describing VisualAge Pacbase components as a
set of related classes.
3. Optionally, using the bridge to import the design model as VisualAge Pacbase
entities.
Construction: server-side
Forward development continues with the steps for the server-side
implementation of business services and data access and includes:
4. Setting a technical frame, the e-business application
5. Building a services node, the Logical View / Elementary Component pair
6. Building a services system, the Folder

Construction: client-side, presentation, navigation
Following the server-side step, the path focuses on the client-side
implementation, which involves:
7. Developing service components, using the VisualAge Pacbase proxy
8. Developing the presentation components (for example, JSPs)
9. Developing the navigation components (for example, Servlets)
Testing and deployment

After they are developed, both the server-side and the client-side components
would be tested. Following successful testing, the components would be
deployed into the production environment.
7.2.3 Backward development path

The backward development path is an iterative prototyping approach. This
approach is much more adapted to rapid application development (RAD) or
proof-of-concept projects where presentation and user interface aspects are
leading the development path.
Analysis and design

Analysis and design are incorporated iteratively in a prototyping approach to
development.
Construction: presentation and navigation

This approach starts with the steps that produce components of the application
that are nearest the end-use:
1. Developing the presentation components (for example, JSPs)
2. Developing the navigation components (for example, Servlets)
Construction: server-side components

This first prototype guides the needs in terms of business services from the
server-side:
3. Building the Logical View
4. Setting a technical frame, the e-business application
5. Building a services system, the Folder
6. Building the Elementary Component
7. Building a services node, the Logical View / Elementary Component pair
Chapter 7. VisualAge Pacbase development process 203

Construction: client-side components
From this point, we return to the client-side:
8. Developing service components, using the VisualAge Pacbase proxy
Construction: refinement
9. Refining the presentation and navigation
Testing and deployment

After they are developed, both the server-side and the client-side components
would be tested. Following successful testing, the components would be
deployed into the production environment.
7.3 Designing a VisualAge Pacbase application

This section discusses the required components, the relation to the UML
modeling, and the use of the Rational Rose Toolkit.
7.3.1 Required components

Implementing an e-business application with VisualAge Pacbase requires
designing and producing the following components:
򐂰 Database
򐂰 VisualAge Pacbase Logical View
򐂰 VisualAge Pacbase Elementary Components
򐂰 VisualAge Pacbase Folders
򐂰 VisualAge Pacbase e-business applications
򐂰 Java Beans
򐂰 Java Servlets
򐂰 JavaServer Pages (JSPs)
򐂰 HTML Pages
We recommend that these components be designed with a tool based on the

Unified Modeling Language (UML).
7.3.2 Relation to Unified Modeling Language (UML)

UML is becoming the industry-standard language for specifying, visualizing,
constructing, and documenting software systems. UML is use-case driven: all the
development activities are guided by the use cases, and the use cases
synchronize the content of other UML models such as class diagrams and object
interaction diagrams.

A use case describes the application’s response to a business event in terms of
the data used and the processing applied. Specifically, the use case is a
sequence of actions involving objects and actors that participate in the business
event.
Using the UML modeling approach works extremely well with the analysis and
design of a VisualAge Pacbase application. This can be seen in the following
approach, which is highly recommended:
Some of the main workflows constituting the UML process are strongly
recommended when designing a VisualAge Pacbase application:
1. Describing requirements
򐂰 Understanding the system context
򐂰 Identifying the use cases and the mechanisms involved in user activities
2. Expanding the analysis
– Definition of modular sub-parts of the system, based on functional criteria
using the various behavior diagrams such as the activity diagram and
interaction diagrams
– Internal description of the uses cases with the use case diagram
– Introduction of Business Objects using the class diagram
3. Designing the system
– Deploying the packages into design subsystems with the component
diagram
– Distributing the analysis Use Case Realizations into design subsystems
and refining the associated diagrams
VisualAge Pacbase accelerates the completion of the above activities by

providing standard answers to many of the technical challenges encountered
during the design, including:
򐂰 Standards design artifacts (servers and proxies, for example)
򐂰 Ready-made generic mechanisms (error management, recovery and
transaction management, for example)
򐂰 Automatic handling of client-server issues (lock mechanism and local cache
management, for example)
One of the core structuring concepts of VisualAge Pacbase is the Folder. The
Folder is a good example of how UML and VisualAge Pacbase concepts
complement each other:

򐂰 Folder design activity uses the following VisualAge Pacbase design classes
stereotypes:
– Root node
– Dependent node
– Referenced node
򐂰 UML Class diagrams describe details for the VisualAge Pacbase nodes by
modeling relations and specifying cardinalities as well as attributes and
operations.
򐂰 UML Interaction diagrams together with the class diagrams validate the
VisualAge Pacbase root node and its related classes.
7.3.3 Relation to the Rational Rose Toolkit

Rational Rose from Rational Software is a UML-based product.Using the
Rational Rose toolkit provides the following advantages:
򐂰 Support for requirements, analysis, and design activity
򐂰 Population of VisualAge Pacbase entities from the UML Analysis Model using
the bridge from Rational Rose to VisualAge Pacbase.
7.4 Server-side implementation

This topic focuses on server-side implementation of data access and business
services. Refer to the discussion in Chapter 8 for a description of the underlying
concepts for data access and business services.
7.4.1 Building a services node

A services node is the smallest level of business granularity on the server-side. It
is made of two parts:
򐂰 Logical View
򐂰 Elementary Component
The Logical View represents data for which services (for example, read and
update) are required. It contains a structured list of data elements that forms the
message to be exchanged between the client and the server.
A Logical View must be independent: it must contain all data that it needs to
establish the message between the client and the server without the need to
access any other source.

A Logical View provides a set of generic services for the data it contains.
Primarily, these services are extraction methods on data that do not need any
specific code.
The Elementary Component is associated with a Logical View. Some major

characteristics of the elementary component are:
򐂰 Groups various services for its associated logical view
򐂰 Maps the logical view to accomplish persistency (for example, to a relational
database)
򐂰 Allows automatic generation of accesses and controls (selections, updates,
checks)
򐂰 Supports functional code for specific user services and business logic
򐂰 Provides the ability to reuse existing modules through the use of the standard
call mechanism
In general, we can say that the Logical View organizes the data and the
Elementary Component organizes the services for this data. This Logical View /
Elementary Component pair is known as a Node.
Building the services nodes level consists of describing Logical View /

Elementary Component pairs. These services nodes need to be logically
organized at a higher level, which corresponds to the Folder.
7.4.2 Building a services system

The Folder represents a group of hierarchically organized services nodes and/or
reference links.
The Folder is the central level of business granularity. It supports a set of

consistent services required for end-user tasks which correspond to the use
cases, and also manages data integrity for the logical views it references. A
Folder request ensures consistency through the relationships between its nodes.
7.4.3 Setting a technical context

There are certain technical aspects that will be part of every e-business
application. The term e-business application refers more to a technical context
that is not part of the business logic of the system under development. It is
possible for several folders to share a common technical context.

Building an e-business application provides the following technical facilities:
򐂰 May contain several folders and communication monitors
򐂰 Groups common characteristics of the folders linked to it
򐂰 Avoids repeating the technical context on different folders
򐂰 Specifies access to the error server for its folders
򐂰 Allows global generation of all its folders
Even though the technical context can be shared, our design recommendation is
to have one VisualAge e-business application per deployed business application.
7.4.4 Results
After completing the construction of the server-side components, the servers and
proxies must be generated from VisualAge Pacbase.
COBOL servers are generated on the server-side development workstations.

Java proxies are generated on the client-side development workstations. Both
can be tested immediately using the Visualage Pacbase Test Tool, before
delivery to the client-side development team.
Note: The term proxy will be explained in detail in chapter 9 which describes
the VisualAge Pacbase Proxy. Testing will be described in greater detail in
chapter 13, Testing and Deployment.
7.5 Client-side implementation

This topic focuses on the client-side steps to implement navigation, presentation,
and access to services.
7.5.1 Developing services components

Services components are related to the VisualAge Pacbase proxy concept.
Basically, the VisualAge Pacbase proxy is a generated JavaBean that runs on the
client-side and manages access to a component such as a folder or node on the
server-side. This JavaBean has got a public API (application programming
interface) that hides complex mechanisms like locking mechanisms, message
optimization, network traffic and error management, while providing access to
the business services implemented on the server-side.
As a result, this VisualAge Pacbase proxy is the main component of our client
model layer (refer to Chapter 2, Targeted Application Architecture). Using the
Proxy concept, services are structured as follows:
򐂰 We create some Business Objects through inheritance from the proxies.
򐂰 We use the Command pattern to encapsulate the access to services.

Services development are constructed using VisualAge for Java. As an output of
this construction, we obtain JavaBeans independent of the server-side. These
JavaBeans are delivered to the Presentation Development Team.
In Part 2 of this redbook, we use this approach for the VisualAge Cruise Lines
sample application.
7.5.2 Developing presentation

Presentation refers to developing static and dynamic pages to support an
application. Static pages are coded as HTML, whereas dynamic pages are
coded as JavaServer Pages (JSPs) or simply JavaScript code.
For this redbook, we used WebSphere Studio to design and develop our HTML
pages and JSPs. The JavaBeans we needed to provide dynamic content for the
JSPs were developed and imported from VisualAge for Java.
These JavaBeans function as DataDeliveryBeans. When the Servlet requests

services, a generic request is sent to a CommandBean. The CommandBean
then sends a more specific request for services to the Proxy, which manages the
interaction with the database management system (DBMS). The response from
the Proxy includes more data than we need and so the JSP invokes the
DataDeliveryBean to deliver only the data necessary and also to provide any
data manipulation. The DataDeliveryBean functions under the control of the
Servlet, which instructs the DataDeliveryBean as to which data is needed and
how it is to be delivered.
In Part 2 of this redbook, we demonstrate how these components work together

as we develop and deploy the VisualAge Cruise Lines sample application.
7.5.3 Developing navigation

WebSphere Studio eases the development work by generating the servlet and
providing ready-to-use methods.
Specifically, WebSphere Studio generates a servlet for each JSP along with the
following services:
򐂰 doPost(), doGet() methods to retrieve the URL content
򐂰 getRequestParameters() method to retrieve each field value and user action
These servlets are imported into VisualAge for Java where the navigation is then
fully developed. The navigation development team must decide between:
򐂰 Generating a servlet for each JSP, or
򐂰 Using one servlet to manage several JSPs

We recommend using one servlet to manage several JSPs to better conform to
the associated use case.
Implementing the navigation consists of:

򐂰 Constructing DataDeliveryBeans consistent with the presentation
򐂰 Managing the JSP, which handles the output to the browser
This too will be shown in the VisualAge Cruise Lines sample application in Part 2
of this redbook.
7.5.4 Testing
VisualAge for Java provides three integrated tools to test the client-side
application:
򐂰 The VisualAge for Java Debugger provides facilities to debug Java code.
򐂰 The WebSphere Test Environment simulates a Web Server within VisualAge
for Java.It provides access to the Java Debugger for JavaBeans and Servlets
running in the simulated servlet engine.
򐂰 The JSP execution monitor provides facilities to review JSP compilation and
execution.
Additional information regarding testing can be found in the chapter 13, Testing
and Deployment including the use of the VisualAge Pacbase Test Tool.
7.6 Development process summary

Figure 7-1 summarizes the development process using VisualAge Pacbase.
Data Delivery Bean Proxy
Business components, folder,

...
HTML pages,
Data Bean
JSP
Database
Command Beans
Servlet
Page Producer Application Assembler Bean Provider Server Developer Database

Administrator
Figure 7-1 Development process summary

7.7 Team considerations
Figure 7-2 summarizes the distribution of work among e-business development
teams.
Functional
Subsystem
UI Workflow Business Persistancy

Subsystem Subsystem Subsystem Subsystem
Navigation Commands
HTML,
JSP,... Elementary Database
components,
Servlets Beans folder, ...
Page Producer Application Bean Provider Server Database

Assembler Developer Administrator
Proxy
Figure 7-2 Distributing the work among development teams
The distribution of effort discussed here is intended to optimize the growth of

e-business development skills within an organization and also to increase
productivity.
Server-side development team:

򐂰 Composed of Database Administrator and Server Developers
򐂰 Responsible for implementing the database and the VisualAge Pacbase
server components
򐂰 Delivers proxies to the client-side business development team
򐂰 Client-side business development team:
򐂰 Composed of JavaBeans developers, and application assemblers
򐂰 Responsible for implementing the JavaBeans, and the servlets
򐂰 Delivers JavaBeans to the client-side presentation development team

Client-side presentation development team:
򐂰 Composed of Web page and JSPs developers
򐂰 Responsible for implementing HTML Pages, JSPs, and servlet shells
򐂰 Delivers servlet shells to the client-side business development team
Regardless of how your organization chooses to manage the development effort,

we recommend that the following decisions be finalized as early as possible in
the e-business project:
򐂰 Organization and composition of the different development teams
򐂰 Components to be delivered by each team
򐂰 Schedule of delivery for each component
7.7.1 Deployment
Figure 7-3 describes how the e-business application components are deployed.
Web browser
(no deployment)
WebSphere VisualAge Pacbase
Application Server business application
Database
Servlet
Elementary
HTML, Proxy components,
JSP folder, ...
JavaBeans
Database
Figure 7-3 Deployment

8
Chapter 8. Building services and data

access
In this chapter we describe the components which together form the server side
of our client server application. We also explain how the different components
work together and how they interact. In the first section we explain the different
parts of the server. In the second section we discuss how to combine them in one
application.

8.1 Logical view
The logical view is a specific entity of VisualAge Pacbase 3.0. It is used to define
an information concept in your data system. It is reusable across several
applications.
A logical view is made up of a collection of data elements. Its description is

independent of the storage medium chosen to store its instances. To be used in a
VisualAge Pacbase 3.0 e-business application, a logical view must be called in
an elementary component. The elementary component makes the link between
the structure of the storage entities (segments) and the structure of the logical
view.
A logical view has an iterative capacity. This capacity is the maximum number of
instances that can be processed by an elementary component in one execution.
A logical view must have a key made of identifying data element(s).
Note: The logical view is considered to be a business-oriented set of data on

which services are required in order to accomplish a user task.
8.2 Elementary component

An elementary component runs on the server side of the e-business application
and supports a set of services on a logical view. These services may be generic
and dedicated to selections and updates on the logical view, or they may be
specific and support functional requirements.
These services on the logical view include:

򐂰 Check and update
򐂰 Selection
򐂰 User service
򐂰 Logical lock
Check and update

A check processes all the intrinsic and correspondence checks indicated in the
VisualAge Pacbase Repository. In case of error, it sends an error message to the
Client.
An update allows to create, modify or delete a Logical View instance in the

database. The action code associated with the update can be implicit or explicit.
In case of error, an error message is sent to the Client.

Selection
This service allows a collection of Logical View instances to be retrieved on the
Client workstation. This retrieval is based on:
򐂰 Standard selection criteria: The selection service returns the number of
instances requested. If the number of instances returned is lower than the
number of instances of the selected collection, it returns the identifier of the
first instance to be displayed in the next selection page. This service also
allows selecting only one Logical View instance.
򐂰 Customized selection criteria: You can add / replace specific clauses in a
standard generated SQL access or create a new physical access. Also, using
the customized selection criteria, implemented by extraction methods, you
can retrieve a collection of instances of a Logical View.
User service
A User Service is a consistent processing unit executed based on the Client’s
request. For each Logical View called in a Business Component, the developer
can define custom processing using an insert point reserved for that purpose.
Coding follows the standard rules of the VisualAge Pacbase structured code.
Logical lock
A logical lock allows - upon the Client’s request - to limit the update of a coherent
set of data to one user.
8.3 The e-business application

The e-business application component in VisualAge Pacbase encapsulates the
rest of the server components. It is therefore the most obvious place for
parameters that are common among different components.
Note: The e-business application is considered to be purely a technical

component which groups a set of programs that can call each other.
The e-business application may contain several communication monitors,

folders, elementary components, but only one error server. All of these can be
generated from the VisualAge Pacbase repository in a single step using the
Chapter 8. Building services and data access 215

8.3.1 Error server
The error message server manages the messages associated with the errors
detected by the elementary components. The text of these messages is stored in
a dedicated file. The source for this messages file is generated from VisualAge
Pacbase.
8.4 Communication monitor

The Communication Monitor handles the following functions:
򐂰 The definition of communication functions (message sending and receiving)
according to the target environment.
– Multi-environments management: A VisualAge Pacbase 3.0 e-business
application can be executed on different environments. In this case, a
monitor being specific to an execution environment (generation variant
and communication type), there will be as many Communications Monitors
as environments.
򐂰 Checking each message received.
򐂰 Controlling the sending/receiving of the query.
– According to the size allowed for the physical message, several physical
messages may need to be issued in order to obtain the complete logical
message. A work file must therefore be available for a temporary storage
of the current query.
Once the query is completely received, sequential processing of services which

compose it by successive calls to the corresponding Services Manager.
򐂰 Transactional management (COMMIT/ROLLBACK): The Communications
Monitor uses the COMMIT and ROLLBACK services of a Database or a
transactional monitor depending on its generation variant. A query is
processed as a whole. The server part executes - before return to the client -
a COMMIT or a ROLLBACK according to the error context (protocol error or
application error) established at the end of the query processing. In case of
error, query processing is ended and an error message is sent back. Thus, all
the resources monopolized by query processing are made available once the
response has been sent.
8.5 Folder
A folder, or services system, groups a set of services nodes. A complete services
node corresponds to a pair of two types of components, a logical view and an

elementary component. A folder is thus a complex information concept built from
a set of elementary information concepts linked through hierarchical or referential
relationships. It supports a set of consistent services required to accomplish user
tasks and also manages data consistency.
8.5.1 The Services Manager

For each query sent via the Communications Monitor, the Services Manager
processes the service requests and sends back the response to the
Communications Monitor.
A query targets one and only one Services Manager and includes 1 to n service
requests. The Service Manager processes a query:
򐂰 By interpreting the contents of the service into 1 or n elementary requests
addressed to the corresponding elementary components.
򐂰 A service is processed by an elementary component which can, in turn, call
another elementary component.
򐂰 By transmitting whenever relevant the corresponding user buffer to the called
elementary component and by updating its contents after the call from the
elementary component if the user buffer has been sent by the client.
There are as many Services Managers as there are Folders specified for the
application. The Services Manager is a purely technical component, in which it is
not recommended to insert specific code.
8.5.2 Folder view

Considering the fact that an application’s functionality does not necessarily cover
the wide scope of a Folder definition, each business act must be able to work on
a partial view of a Folder which guarantees the integrity of the transformation of
its instances. This view is represented by the Folder view entity:
򐂰 A Folder view represents all or part of the Folder and must contain the Folder
root.
򐂰 A Folder can contain several Folder views. Each view corresponds to a
consistent representation of some of the Folder nodes, according to the data
required to implement a business act.
– An application can use several Folder views proceeding from different
Folders.
The generation of a Folder view creates (in the Client component) an object
called Folder view proxy which allows a VisualAge Pacbase GUI application to
read, modify and transform the Folder’s instances.

Specifying Folder views is not a requisite. Indeed, the description domain of a
Folder may be limited enough to be used in full in a given application. In this
case, an additional generation at the Folder level obtains the whole set of classes
used to manage the Folder in a graphic application.
8.6 Technical considerations

Here we discuss which step to take and in which order, to be able to create a
VisualAge Pacbase e-business application.
8.6.1 Technical environment

A VisualAge Pacbase e-business application needs two technical files. A working
file and an error file. These files are reusable, therefore it is not necessary to
create these files for every new application.
Working file
The working file is a technical file that is used by the communication monitor to
temporarily store the information which is necessary to build the request or its
response when several messages are required.
The working file could be stored using any type of file access method (for
example, a DB2 table) but for performance reasons we recommend using an
indexed file.
The path to this working file needs to be indicated in the Windows/NT

Environment parameters. This needs to be done so that the folder manager can
find it at runtime. We defined it with the name “WF00IX”.
This working file also needs to be defined in VisualAge Pacbase in order for the
components to know its logical name and structure.
This file needs to be defined as follows:

1. A basic data structure must be created
2. Also a mono structure segment.
3. The segment must be filled with the following two fields.
a. A key field, 37-characters long, alphanumeric, defined as the segment key.
This data element is called in the segment as an identifier.
b. A detail field, 250-characters long, alphanumeric.

Error file
The error message server generates the messages associated with the errors
detected by the Elementary Components. These messages are stored in a
dedicated and generated file.
The error server allows to manage application specific errors, to be sent back to
the client whenever an error is detected. The activation of the error management
is to be specified on the e-business application component.
We use a database to store our messages. The file must be defined as follows:
򐂰 Erkey, a 29-character long alphanumeric key field.
򐂰 Label, a 71-character long alphanumeric field.
8.6.2 Building a proxy

We will now discuss the steps and the sequence to follow in order to generate a
VisualAge Pacbase proxy.
The e-business application

The e-business application is the backbone of the server. Logical views and
elementary components can be created without an e-business application.
Folders and communication monitors however, need an e-business application to
which they can be assigned:
1. Define the e-business application with its code and labels.
2. Give the name of the Java package that will be created when generating the
components at once linked to the application.
3. In the working field, call the segment which is defined as the working file and
the Type of File which goes with it. Also give its logical name, for example
“WF00IX”. For performance reasons keep the file local to the generated
servers.
4. Define the database the application uses. For performance reasons, it is
better if it is also local to the servers.
5. After finishing the Definition, the Error Server tab must be filled in. It must
have its generation details and the call to the error segment.
Communication monitor
After building the e-business application it is possible to build components like
the communication monitor:
1. Like most VisualAge Pacbase definitions, the Code, Label, Short Code, Cobol
program ID and Type of Cobol to generate must be filled in.

2. The message size must be described. The default value is 2K, but it can be
up to 48K.
3. A communication protocol must be selected from the list box.
4. The e-business application must be called into this definition.
Logical view
The logical view creation is the next logical step to take in the process of creating
a complete VisualAge Pacbase 3.0 e-business application:
1. A logical view is first defined by a long identifier, a label and a short code.
These fields are all mandatory.
2. The logical view composition, in terms of data elements, should be given.
Adding a data element in the logical view is called adding a composition line,
since we give more information than just the data element name.
A data element may also be defined as a set of data elements, thus establishing
hierarchies of data elements, which are called data element groups.
Extract method
Extract methods are used when the selection is a conditional one relative to the
logical view:
1. The extract method is first created by giving it a code and a class code. The
class code will appear in the proxy to be used on a selection action.
2. Add extract parameters to the extract method:
– Extract parameters are data elements which are used to express the
conditions of the method. They are chosen from among the data elements
in the repository, but the same element cannot be called twice in the same
method.
3. Describe the conditions of the extract method. This is done by writing the
condition on the extract parameter with help of the code editor.
4. Add sort criteria if required. It is possible to have sort criteria and no
conditions. The data element on which the sort is based should belong to the
logical view. At runtime, the sort is done after the selection of instances.
Note: Extract methods should only be used for simple requests on the
database, otherwise methods should be written in the elementary components
that support more complex code. Extract methods are of interest only if they
do not involve the table keys, since these accesses are dealt with by the
elementary components. Sort methods are used to sort the results of the
extract method defined.

Describing the folder
The folder is build on the defined logical views:
1. Define the code, the label, the short code.
2. Enter the e-business application
3. Enter the COBOL program Id and the type to generate
4. Enter a package code
5. Click Next
6. Give the root node a name for the folder nodes hierarchy.
7. Select the logical view needed by accessing the logical views list.
8. Give generation codes and classes. This is necessary in order to be able to
generate the folder. A proxy node is generated into three Java classes:
– Node (HierarchicalNode, ReferenceNode)
– DataDescription
– SelectionCriteria
Nodes
Access the composition tab of the folder and add the dependant and reference
nodes of your folder. Each new node is created, departing from another node.
For each node, select the logical view that supports the required data.
Two types of nodes may be defined:

򐂰 Dependent, which means that the dependent node can not exist
independently from its parent, any node which place is higher in the
hierarchy.
򐂰 Referenced, a reference node is a pointer to another folder to use its data for
consultation only.
– When creating a reference node, the relationship between the referencing
node and its referenced node must be named. A referenced node may be
referenced by several different nodes in the same folder, and the
relationship marks the difference. The folder from which we need the data
must also be selected to link it to the node.
For each hierarchical node, root and dependents.

1. Access the selection of identifiers panel.
2. Select the ones which are identifiers of the node in this folder.

Note: It is not necessary to add the parent key to the list of keys of a
dependent node. This will be done automatically at generation.
For each reference node, open its description panel:

򐂰 In the table that displays the data elements of the referencing node and the
identifiers of the referenced node, map the field of the referencing node used
to access the referenced node with this node key.
򐂰 Map the fields of the referencing node that need to be updated by the
equivalent in the referenced node.
Note: A logical view which is called in an elementary component within a

folder cannot be reused in another elementary component that belongs to the
same or another folder if it is not a root node.
Elementary component
The application that will be used for generating the elementary component will be
the folder application to which the elementary component will be linked:
򐂰 The elementary component must be defined with a long code, a label and a
short code.
򐂰 At this stage we define only hierarchical components.
򐂰 The target generation language should also be given.
Creating nodes
In an elementary component, we will call persistency object a component that
represents one of the following physical storage systems:
򐂰 Another elementary component, which manages access to data contained in
a logical view.
򐂰 A table or a relational database.
򐂰 A DL1 database record.
򐂰 A mono or multi-structure file
򐂰 A Pactable table
A persistent object is described by a collection of data elements that define its

internal structure.

For persistency definition, we work with the left panel of the composition tab in
the elementary component:
1. Selection of the persistency object needed. Defining this type links the
persistency object with a set of characteristics used by VisualAge Pacbase
when generating description and accesses on the persistency support.
2. Add the persistency object (needed for the logical view process) that belongs
to this type instance. This generates the persistency objects descriptions.
There is also an opportunity to define views on these object by describing
subschemas.
To add a logical view to our composition we work with the top right window:
1. Create a new composition line. This needs a generation code, an identifier in
the elementary component. This must be mapped to an existing logical view
and the view should be given an iterative capacity.
To define the dynamics of the accesses to persistency objects we need to select

the logical view call in the upper right panel. For the definition itself, select the
central panel:
1. Drag and drop the persistency objects that were previously defined into this
window. This builds the relationship between the view and the persistency
objects.
2. Select the type of access needed.
3. For each of the relationships between the view and a persistency object the
accesses needed must be defined more precisely using the following rules.
There are two standard types of relationships between the logical view and a
persistency object. Both describe the dynamics of use of the persistency objects
when a set of the logical view instances is selected or updated. The first type
corresponds to a logical view instance that owns information which is only
displayed and comes from a persistency object that never will be impacted by an
update. The second type corresponds to the update process management.
Persistency objects may also be used in a specific way to modify the standard
selection or update processes. In that case, the functions for logical and physical
accesses are generated and the call of the logical functions is managed by the
developer.
The dynamics of accesses to the persistency objects, either selection or update,

allows defining in which order and under which conditions these persistency
objects will be used to process a logical view. A persistency object can only have
one type of dynamics for selection or update, If it has a selection or update type,
it cannot also have the “specific” type.

For each type of dynamics, a persistency object is applied to the type of access:
򐂰 The access type for the selection dynamics, is selection.
򐂰 The possible access types for the update dynamics are:
– Existence
– Existence and selection
– Update
– Update and selection, only when calling another elementary component
– Specific service, only when calling another elementary component
Only one type of access is allowed for a persistency object with the update
dynamics:
򐂰 Existence
򐂰 Existence and selection
򐂰 Update
򐂰 Update and selection, only when calling another elementary component
򐂰 Specific service, only when calling another elementary component
򐂰 Selection
When the dynamics are of type specific on a given persistency object, several
access types are possible but from the following four you can choose only one:
򐂰 Existence
򐂰 Existence and selection
򐂰 Update
򐂰 Update and selection
If a system access error occurs on a persistency object the processing on the

current and following logical views are stopped. Whatever the order of the
persistent objects, we can specify that a persistent object is used if the access to
the previous object has not sent an exception of the kind:
򐂰 Not found
򐂰 End of file
򐂰 Duplicate creation
When an exception is sent when accessing a persistency object, all the accesses
that are conditioned by the current access are cancelled for the current logical
view instance.
Any persistent object which is not dependent on the access of another

persistency object is called a pilot or main object. Any object which depends on
the access to another persistency object is called a secondary object, whatever
the number of persistency objects on which it depends. However this vocabulary
is not applied in case of the dynamics of the type specific.

We now turn our focus on the data transfer management. We have defined
almost every relationship possible except those on data element level. There are
two types of data transfers between the logical view and the persistency objects:
򐂰 Key transfer
򐂰 Fields transfer
The logical view data elements that appear in this step are come from the fields
entered when creating the logical view plus the fields defined as keys when
calling the logical view in the folder.
There are certain rules by which we must determine our data transfer:
򐂰 The key transfer depends on the type of dynamics chosen:
– If the dynamics are “selection”, the keys of the main persistency objects
can only be fed from the logical view keys. The keys of the secondary
persistency objects can be fed from the data elements of the logical view
which are neither extract parameters nor elements of a previously read
persistency object.
– If the dynamics is “update” or “specific” and the access type is “selection”,
“existence and selection”, or “existence only“, the keys of the main
persistency objects can only be fed by data elements of the logical view
which are not extract parameters. The secondary persistency objects can
be fed by data elements of the logical view which are not extract
parameters nor elements of a previously read persistency object.
– If the dynamics are “update” or “specific” and the access type is “update”
or “update and selection” the keys of the main or secondary objects can
only be fed by data elements which are identifiers in the logical view. If the
access type is service specific, for the call of an elementary component,
there is no possible transfer.
򐂰 The transfer of non-identifier data elements (fields) allows you to specify for
each data element (which is not an identifier in a persistency object) the data
element which it feeds (or that feeds it respectively), in the selection, update
or specific dynamics:
– If the dynamics are of type “selection”, the non-identifying data elements
of the main and secondary persistency objects can only feed
non-identifying data-elements of the logical view.
– If the dynamics are of type “update” or “specific” and the access type is
“selection”, “existence and selection”, or “existence only”, no transfer is
possible.

– If the dynamics are “update” or “specific”, and the access type is “update
and selection” or “update only”, the non-identifying data elements of the
main persistency object can be only fed by non-identifying data elements
of the logical view. The non-identifying data elements of the secondary
persistency objects can be fed by non-identifying data elements of the
logical view or by data elements of a previously accessed persistency
object. If the access type is service specific, fields can be fed by data
elements which are not extract parameters of the logical view.
The data transfer is defined in the right bottom window of the composition tab.
1. If there is more than one, select each of the previously defined relationships
between the logical view and the persistency objects.
2. Select the key transfer view.
3. For each one, list the keys of the logical view and, in the target column, their
counterpart in the persistency object. This defines the transfer between the
two types of components.
4. Change the view selection from key transfer to field transfer.
5. Here, in the same way as in step 3, define the transfer of non-identifier fields
between the logical view and the persistency object.
Finishing the folder

We finish the folder by implementing the complete services node in the folder
with all the accesses requirements selected and any specific code or macro calls
entered:
1. Return to the folder composition tab.
2. Open each node panel in order to call the elementary component that
processes the logical view which was associated with the node earlier. Now
the node is finished.
Building folder views

A folder view allows you to select a subset of a folder for technical reasons or to
match a specific user profile:
1. Open the folder composition tab.
2. Create a new composition. Give it a name, label and generation prefix that
differentiates it from the folder.
3. When selecting this new view in the view list, the icons in the composition are
grayed out. Select the nodes you want to include in the folder view by clicking
them.

8.6.3 Testing the e-business application
The VisualAge Pacbase 3.0 Test Tool allows the generated folder and its
elementary components to be tested with a corresponding graphical interface. In
a generic graphical environment, it takes as a parameter a folder view proxy and
by introspection provides a set of buttons and graphical controls which allow you
to test the methods that were implemented in the proxy. The discussion of testing
continues in chapter 13.

9
Chapter 9. The VisualAge Pacbase

proxy
In this chapter we provide information on the VisualAge Pacbase (VAP) proxy.
After introducing the concept of a VAP proxy, we describe its main features.

9.1 What is a VAP proxy?
Since the VisualAge Pacbase Business Logic generator produces folders and
elementary components with the same generic behavior, it is possible to
organize this generic behavior into classes whose objects — called proxies —
are used to execute the services for the associated elementary components.
Using the e-business development workstation, the folder and its hierarchy of
elementary components must be generated from the VisualAge Pacbase
repository. This results in an output file that is used with the VisualAge Pacbase
Java generator to produce the Java classes for the client.
The objects generated from the VisualAge Pacbase repository, shown in Figure
9-1, are the following:
򐂰 Folder proxy
򐂰 Elementary proxies (these are always associated with a folder proxy).
VisualAge Pacbase Repository VisualAge for Java Repository
Folder Folder Proxy
Nodes
Elementary Proxy
Elementary Component/Logical View
...
Generator Import
VisualAge Pacbase
Description File Java File
Input Java Generator Output
Figure 9-1 Proxy generation process
A folder proxy is the result of a folder generation. A folder is described by nodes,

which are elementary component/logical view pairs. Generation of the folder
produces a set of classes (elementary proxies) that correspond to all the nodes
which make up the folder.

There are three types of elementary proxy objects:
򐂰 The root proxy, which corresponds to the root node
򐂰 The dependent proxy, which corresponds to the depending node
򐂰 The reference proxy, which corresponds to the reference node
9.2 Proxy features

This section focuses on the Java implementation of the VisualAge Pacbase
proxy, and provides information on the main features.
9.2.1 Overview
The folder proxy is used by your client application to manage the functional
interactions (for example, between dependent nodes) of the elementary proxy
objects it contains.
The root proxy is an elementary proxy which has its own specific characteristics.
Only the root proxy can execute server update actions and ensure error handling.
The fact that the root proxy handles all of the update activities allows developers
to take advantage of services such as commit/rollback.
Elementary proxy objects are used to execute the public services of the
elementary component associated with them. The elementary component proxy
enables the client application to send requests for services to the remote server
associated with the elementary component proxy.
Proxy services include:

򐂰 Structuring of data
򐂰 Encapsulation of the implementation of the elementary component services
– Selection and update programming on tables
– Extraction methods on database
– Commit/rollback (only on root proxy)
– Paging
– User services
򐂰 Temporary storage of data to be sent to the elementary component
򐂰 Error handling
򐂰 Event-driven translation of the elementary component return codes
򐂰 Communication (encapsulating the VisualAge Pacbase middleware)
򐂰 Local data integrity check
Chapter 9. The VisualAge Pacbase proxy 231

򐂰 Automatic control of version consistency between client and server
components
򐂰 Concurrency access and locking mechanisms
The following sections and chapters describe how to use a proxy in the client
environment.
9.2.2 Hierarchy of generated proxies

This section introduces the Java hierarchy for the VAP proxy.
Hierarchy overview
Figure 9-2 shows the Java generic proxy classes hierarchy.
Figure 9-2 Java proxy classes hierarchy
ProxyLv
This class is the abstract root class of all generated proxy classes.
HierarchicalProxyLv
This class is the abstract parent class of dependent proxies and folders. It
provides the facility for managing proxy hierarchies.

DependentProxyLv
This class is the abstract parent class of generated dependent proxies.
Folder
This class is the abstract parent class of generated folders.
Important: It is really important to understand that any sub-class of this folder

abstract class is in fact the combination of what we previously called a “folder
proxy” and its “root proxy”. To simplify the vocabulary, we will now use the
term “folder proxy” to designate this folder proxy/root proxy pair.
ReferenceProxyLv
This class is the abstract parent class of generated reference proxies.
Proxy related generated classes

When generating a proxy class, regardless of its superclass, the Java classes in
the following table are always generated.
For instance, if we generate a proxy class called ShipProxy that extends the
Folder class, the following related classes will be generated as shown in Table
9-1.
Table 9-1 Proxy related generated classes

Class name Superclass Description
ShipData DataDescription Class used to represent

an instance of the SHIP
node.
ShipDataUpdate DataDescriptionUpdate Class used to represent

updated data of a SHIP
node.
ShipProxyTableModel PacbaseTableModel Class used to represent a

list of rows (instances) of a
SHIP node.
ShipProxyUpdateTableM PacbaseUpdateTableMo Class used to represent a

odel del list of updated rows of a
SHIP node.
ShipSelectionCriteria DataGroup Class used to represent

keys of the SHIP node.

When generating the same ShipProxy class, regardless of its superclass, the
bean information classes in Table 9-2 are not always generated. Actually, this is
an option when generating the VAP proxy.
Table 9-2 Proxy related generated bean information classes

Class name Superclass Description
ShipProxyBeanInfo SimpleBeanInfo Bean information about

the ShipProxy bean class.
ShipDataBeanInfo SimpleBeanInfo Bean information about

the ShipData bean class.
ShipDataUpdateBeanInfo SimpleBeanInfo Bean information on the

ShipDataUpdate bean
class.
ShipProxyUpdateTableM PacbaseUpdateTableMo Class used to represent

odel del updated rows of a SHIP
node.
ShipSelectionCriteriaBea SimpleBeanInfo Bean information about

nInfo the ShipSelectionCriteria
class.
9.2.3 Public services of generated proxies

This section briefly describes the main public services that are generated when
generating a VAP proxy.
Main local services for a folder proxy

Not all of the generated public services for a folder proxy interact with the server
associated with the elementary component. Some services remain local to the
client and these include the those in Table 9-3.

Table 9-3 Folder proxy local services
Public method Usage description
detail() Gets the detail attribute of the proxy.

This attribute contains all the data fields
of the logical view that are not defined as
extract parameters. This attribute is
used for local update actions and is a
result of reading a single instance.
getDetailFromDataDescription(aData) This action is used to copy a Data

Description to the detail attribute of the
node.
getXxx() (for example, getCabinProxy()) Returns the xxx property value, where
xxx is the name of one of the dependent
proxies.
getTableModel() Gets the TableModel attribute. Returns

an instance of PacbaseTableModel.
getUpdatedFoldersTableModel() Gets the UpdatedFoldersTableModel

attribute. Returns an instance of
PacbaseUpdateTableModel.
getUpdatedInstancesTableModel() Gets the UpdatedInstancesTableModel

attribute. Returns an instance of
PacbaseUpdateTableModel.
selectionCriteria() Gets the selection criteria attribute. This

attribute contains all of the identifier data
fields and extract parameters defined in
the logical view associated with the
node. This attribute is a parameter for
reading both single and multiple
instances.
undoLocalFolderUpdates(aDataUpdate) Cancels local folder updates based on

the indicated parameter.
undoLocalUpdate(aDataUpdate) Cancels all local proxy updates based

on the indicated parameter.
Main local services for a dependent or reference proxy

Not all of the generated public services for a dependent proxy or a reference
proxy interact with the server associated with the elementary component. Some
services remain local to the client and these include those in Table 9-4.

Table 9-4 Dependent or reference proxy local service
Public method Usage description
detail() Gets the detail attribute of the proxy.

This attribute contains all the data fields
of the logical view that are not defined as
extract parameters. In dependent
nodes, identifier data fields already
defined in their parent attribute are
excluded. This attribute is a parameter
for local update actions and a result of
reading a single instance.
getDetailFromDataDescription(aData) This action is used to copy a Data

Description to the detail attribute of the
node.
getTableModel() Gets the TableModel attribute. Returns

an instance of PacbaseTableModel.

attribute.Returns an instance of
PacbaseUpdateTableModel. This
service is not generated for a reference
proxy.
selectionCriteria() Gets the selection criteria attribute. This

attribute contains all the identifier data
fields and extract parameters defined in
the logical view associated with the node
This attribute is a parameter for reading
both single and multiple instances.

attribute.Returns an instance of
PacbaseUpdateTableModel. This
service is not generated for a reference
proxy.
Mapping between folder proxy and server

Table 9-5 shows what happens on the server for specific folder proxy services.
Table 9-5 Mapping between folder proxy and server

Folder proxy services Server
checkExistenceOfDependentInstances() Checks the existence of dependent

instances. If the local cache is empty, this
checking is done on the server.

Folder proxy services Server
executeUserService() Executes a user service defined on the

server.
readAllChildren(RacineData) Reads some or all hierarchical

readAllChildrenFromCurrentInstance() dependent instances based on the
parameter. This kind of all inclusive
retrieval must be specified on the server
side.
readFirstChildren(RacineData) Reads some or all first level hierarchical

readFirstChildrenFromCurrentInstance() dependent instances of the parameter.
This is not an all inclusive retrieval but a
standard retrieval, meaning that the
standard select is called for all first level
hierarchical dependent nodes.
readInstance() Reads one instance on the server.
readInstanceWithAllChildren() Reads one instance on the server with all

its hierarchical dependent instances (all
inclusive retrieval).
readInstanceWithFirstChildren() Reads one instance on the server with all

its first level hierarchical dependent
instances (standard retrieval).
readNextPage() Reads the next set of instances of the root

node (does not do anything if the
NoPageAfter event has been fired).
selectInstances() Reads the instances of the node.
setGlobalSelection(boolean) If GlobalSelection = True, the folder

manager calls the elementary server until
the end of list information is returned.
setMaximumNumberOfRequestedInstanc Sets the maximum number of requested

es(int) instances to use as parameter when
selecting instances.
setUserServiceCode(String) Sets the user service code to use when

calling a user service.
setExtractMethodCode(String) Sets the extract method code to use when

calling an extract method.
updateFolder() Updates all the nodes of the folder on the

server.

Mapping between dependent proxy and server
Table 9-6 shows what happens on the server for specific dependent node proxy
services.
Table 9-6 Mapping between dependent proxy and server

Dependent node proxy services Server
checkExistenceOfDependentInstances() Checks the existence of dependent

instances. If the local cache is empty, this
checking is done on the server.
executeUserService() Executes a user service defined on the

server.
readFirstChildren(DependantData) Reads some or all first level hierarchical

readFirstChildrenFromCurrentInstance() dependent instances of the parameter.
readInstance() Reads one instance.
readInstanceWithFirstChildren() Reads one instance with all its first level

hierarchical dependent instances.



selecting instances
setUserServiceCode(String) Sets the user service code to use when

calling a user service.

Mapping between reference proxy and server

Table 9-7 shows what happens on the server for specific reference node proxy
services.

Table 9-7 Mapping between reference proxy and server
Reference node proxy services Server
readInstance() Reads one instance.



selecting instances.

More about generated methods

The available extract methods and user service codes are obtained using
getExtractMethodCodes() and getUserServiceCodes().
When you use the setExtractMethodCode(String) or

setUserServiceCode(String), the string values are validated by the folder server
module before being passed to the elementary server module.
If the method setMaximumNumberOfRequestedInstances(int) is not used, the

default is the number of occurrences for the logical view.
The following methods are generated only for proxies that have at least one
dependent proxy:
򐂰 checkExistenceOfDependentInstances()
򐂰 readAllChildren(aData)
򐂰 readAllChildrenFromCurrentInstance()
򐂰 readFirstChildren(aData)
򐂰 readFirstChildrenFromCurrentInstance()
򐂰 readFirstChildrenFromCurrentInstance()
򐂰 readInstanceWithAllChildren()
򐂰 readInstanceWithFirstChildren()

The following methods are generated only if at least one user service has been
inserted in the logical view server associated with the proxy:
򐂰 executeUserService()
򐂰 setUserServiceCode(String)
򐂰 getUserServiceCodes()
The following methods are generated only if at least one extract method has
been inserted in the logical view server associated to the proxy:
򐂰 setExtractMethodCode(String)
򐂰 getExtractMethodCodes()
The updateFolder() method is generated only if some form of update activity is

indicated in the logical view servers of the folder.
When any of the following methods are used:

򐂰 readInstance()
򐂰 readInstanceWithFirstChildren()
򐂰 readInstanceWithAllChildren()
the local cache associated with the proxy is reset and will contain the instances
returned. This is true except in the case where the proxy ManualCollectionReset
attribute is set to ‘true’. When the proxy ManualCollectionReset attribute is set to
‘true’, the client is responsible for managing the cache associated with the proxy.
This is not recommended.
9.2.4 More about proxy dynamics

In this section, we describe a bit more the VAP proxy dynamics. As an example,
we consider the following proxy hierarchy as shown in Figure 9-3.
R o o tP r o x y ro o t p ro x y
F ir s tD e p P r o x y fis r t le v e l d e p e n d e n t p r o x y
S e c o n d D e p P ro x y s e c o n d le v
Figure 9-3 Sample proxy hierarchy

Retrieving root instances
We retrieve the instances of the root node by calling the selectInstances()
method for the root proxy. The retrieved instances are placed in the rows
property of the proxy.
We retrieve the detail information for one of these instances by calling the
getDetailFromDataDescription method, which places the retrieved information in
the detail property of the proxy. All of this is shown in Figure 9-4.
selectInstances() getDetailFromDataDescription(rootA)
RootProxy RootProxy RootProxy

Rows: empty Rows: list Rows: list
Detail: empty Detail: empty Detail: rootA
FirstDepProxy FirstDepProxy FirstDepProxy
Rows: empty Rows: empty Rows: empty
Detail: empty Detail: empty Detail: empty
SecondDepProxy SecondDepProxy SecondDepProxy
Rows: empty Rows: empty Rows: empty
Figure 9-4 Proxy dynamics: retrieving root instances
Retrieving dependent instances

This section provides three ways to retrieve instances of a dependent node. We
assume that the first step (retrieving root instances, and retrieving information for
one root instance) has been done, so that the rows and detail properties are filled
for the root proxy.
Node by node retrieval, option 1

We iterate through the root instances. We use the getDetailFromDataDescription
method to populate the root detail property.
Then we retrieve dependent instances for this root instance by calling the
readFirstChildrenFromCurrentInstance() method. In this way, node by node, we
retrieve all of the dependent instances as shown in Figure 9-5.

readFirstChildrenFromCurrentInstance()
RootProxy RootProxy
Rows: list Rows: list
Detail: rootA Detail: rootA
FirstDepProxy FirstDepProxy
Rows: empty Rows: childrenForRootA
Detail: empty Detail: empty
SecondDepProxy SecondDepProxy
Rows: empty Rows: empty
Figure 9-5 Proxy dynamics: node by node retrieval, option 1
Node by node retrieval, option 2

This second option is similar to the preceding one, except that we use the
readNextPage() method to retrieve dependent nodes one by one.
Actually, we iterate through the root nodes, and for each root instance, we
retrieve all of its dependent instances as shown in Figure 9-6.
readNextPage()
RootProxy RootProxy
Rows: list Rows: list
Detail: rootA Detail: rootA
FirstDepProxy FirstDepProxy
Rows: empty Rows: childrenForRootA
SecondDepProxy SecondDepProxy
Rows: empty Rows: empty
Figure 9-6 Proxy dynamics: node by node retrieval, open 2

Retrieving all dependent instances at once
This third way is recommended when you want to populate all of the hierarchy at
once. You iterate through your root proxy instances.
For each root instance, you can repeatedly call the

readAllChildrenFromCurrentInstance() method, which will retrieve all dependent
instances (first and second level) of the current root instance as shown in Figure
9-7.
readAllChildrenFromCurrentInstance() getDetailFromDataDescription(rootA)
RootProxy RootProxy RootProxy

Rows: list Rows: list Rows: list
Detail: rootA Detail: rootA Detail: rootA
FirstDepProxy FirstDepProxy FirstDepProxy
Rows: empty Rows: childrenForRootA Rows: childrenForRootA
Detail: empty Detail: empty Detail: childOne
SecondDepProxy SecondDepProxy SecondDepProxy
Rows: empty Rows: empty Rows: childrenForChildOne
Figure 9-7 Proxy dynamics: retrieving all dependent nodes at once
Notice that all dependent instances of second level are in the local cache. They
are then placed in the SecondDepProxy rows property when the FirstDepProxy
detail property changes.

10
Chapter 10. Building the model layer

In this chapter we describe useful techniques for implementing the model layer
using the VisualAge Pacbase proxy. This is based on the logical
Model-View-Controller framework introduced in Chapter 2 of this book (Targeted
Application Architecture).
For more details and issues about useful design patterns and the command
framework, refer to Servlet/JSP/EJB Design and Implementation Guide,
SG24-5754.

10.1 Useful patterns
Software patterns act like templates and help designers and architects identify
situations and determine which tools to apply in order to produce the best
implementation. In this section, we introduce useful patterns at the
programming-level for use in our model layer.
10.1.1 Singleton pattern

This section introduces the singleton pattern, and provides a Java
implementation for this pattern.
Introduction
Often it is necessary to create a single instance of a given class for technical or
business reasons. You may define a utility class of which at most one instance
can exist per Java Virtual Machine (JVM). For example, to manage a log for your
The Singleton pattern provides a programming template that consists of building

a static wrapper around a reference to an instance of the Singleton class.
10.1.2 Implementing the singleton pattern in Java

Pure implementation of the Singleton pattern ensures that the Singleton class
cannot be instantiated from the external and that this Singleton class can not be
subclassed. As a result, a good approach is to use a final class with private
constructors.
However, in some cases, it can be useful to build subclasses for a given

Singleton class. For this reason, another approach is to use a public class with
protected constructors.
The purpose of the Singleton pattern is to provide global access and to insure
that only one instance of the class is created during runtime. To do this a private
static variable is used to maintain the sole instance of the Singleton class. A
private static get method is used to access this private static variable. The first
time the variable is accessed it is instantiated.
Finally, all of the services from the Singleton class will be public static services
using the Singleton instance accessor to call private instance services.

The following example suggests a Java implementation of the Singleton pattern:
public final class Singleton {
//unique instance
private static Singleton cvInstance = null;
//constructor
private Singleton() {
// ...
}
// Return the unique instance of this class

private static Singleton getInstance() {
if(cvInstance == null) {
cvInstance = new Singleton();//lazy initialization
}
return cvInstance;
}
//Technical or business instance method

private String getNewIdentifier() {
//...
}
//Static accessor to the preceding instance method

public static String getIdentifier() {
return getInstance().getNewIdentifier();
}
10.1.3 Factory pattern

A factory is an object that produces other objects. It has two major uses:
򐂰 Ensuring the uniqueness of a singleton object (a single instance shared
among multiple clients)
򐂰 Hiding the mechanism used to procure an instance, given some specification
of the desired properties of the instance.
In this redbook, we use the factory pattern based on the Singleton pattern. This
is done because we want to ensure that the factory is the only instance provider.
The mechanism of procuring an instance is hidden in private instance services

that are accessed through public static services, as shown in the following
example:
Chapter 10. Building the model layer 247

public final class Factory {
//unique instance
private static Singleton cvInstance = null;
//constructor
private Factory() {
// ...
}
// Return the unique instance of this factory.

private static Factory getInstance() {
if(cvInstance == null) {
cvInstance = new Factory();
}
return cvInstance;
}
private MyClass createNewInstance(String myClassName) {

MyClass myInstance = null;
try {
Class c = Class.forName(myClassName);
myInstance = (MyClass) c.newInstance(); //casting
} catch (Exception e) {
//log
...
}
return myInstance;
}
public static MyClass createInstance(String myClassName) {

return getInstance().createNewInstance(myClassName);
}
10.1.4 Command pattern

The command pattern allows an object to issue requests to another object
without knowing anything about the mechanics of how the operation being
requested will be accomplished or which object will process the request.
A command is a stylized Java class with the following characteristics:

򐂰 A command object corresponds to specific business logic, such as a query or
an update.
򐂰 Commands have a simple, uniform usage pattern.
򐂰 Commands cache information retrieved during the business task.

The next section introduces a simplified command framework. The IBM Pattern
Development Kit provides a more complete one. For more details on this
command framework, refer to Servlet/JSP/EJB Design and Implementation
Guide, SG24-5754.
10.2 Command framework

The command framework captures the basic concepts of commands and
provides an extendable infrastructure.
The components of this framework are:

򐂰 Command interface
򐂰 CommandException class
򐂰 CommandFactory class
10.2.1 Command interface

The command interface provides the minimum set of methods common to all
commands used by the controller (servlet) to manage the life-cycle of a
command. This is shown in Example 10-1.
Example 10-1 Command interface implementation

public interface Command extends Serializable {
public void execute() throws CommandException;
public boolean isReadyToCallExecute();
public void reset();
}
The execute() method executes the task encapsulated by the command. This
moves the command from the initialized to the executed state.
The isReadyToCallExecute() method allows the command controller (servlet)

and the command runtime to ask the command whether all required input
properties have been set.
The reset() method resets the output properties to the values they had prior to
calling the execute method, so that the get methods no longer work and the
isReadyToCallExecute() returns true. This provides a convenient and efficient
way to reuse the same command instance with changes in some of the input
properties.

A command has the following states during its life cycle:
򐂰 New: just after the command has been created (for example via a factory
create). In this state the isReadyToCallExecute() method returns false and the
get methods should not be called.
򐂰 Initialized: just after all required input properties have been set. In this state
the isReadyToCallExecute() method returns true and the get methods should
not be called.
򐂰 Executed: just after the execute() method has been called. In this state the
isReadyToCallExecute() method returns true and the get methods can be
used as shown in Figure 10-1.
setXxx getXxx
List required Execute

Instantiation setXxx
NEW INITIALIZED EXECUTED
Reset
Figure 10-1 Command state diagram
10.2.2 CommandException
The CommandException class is a concrete class that inherits from
Java.lang.Exception.
This class represents a command exception which can be thrown by the

execute() method. The CommandException class can be subclassed.
A CommandException instance eventually encapsulates another Throwable.

This Throwable instance is a specific VisualAge Pacbase exception and
corresponds to a message that is formatted using a specific key to retrieve the
message. We recommend using a properties file to implement this error
message.
VisualAge Pacbase local exceptions are instances of

com.ibm.vap.generic.LocalException. VisualAge Pacbase server exceptions are
instances of com.ibm.vap.generic.ServerException. Refer to the Visualage
Pacbase documentation CD for more details on these exception classes.
A Java implementation for this CommandException class follows:

public class CommandException extends Exception {
protected Throwable ivThrowable = null;
public CommandException() {

super();
}
public CommandException(String s) {
super(s);
}
public CommandException(Throwable throwable) {

ivThrowable = throwable;
}
public Throwable getException() {

return ivThrowable;
}
public String getMessage() {

if (getException() == null) {
return super.getMessage();
} else {
return getException().getMessage();
}
}
public String getDetailMessage() {

String detail = "";
if (getException() instanceof ServerException) {
detail = getMessage((ServerException) getException());
}
if (getException() instanceof LocalException) {
detail = getMessage((LocalException) getException());
}
return detail;
}
An example for implementing the getMessage(LocalException) method follows:

private String getMessage(LocalException le) {
return "VisualAge Pacbase local exception : " + le.getMessage();
}
An example for implementing the getMessage(ServerException) method follows:

private String getMessage(ServerException se) {
String result = "";
Enumeration enum = se.serverMessages();
while (enum.hasMoreElements()) {
ServerMessage sm = (ServerMessage) enum.nextElement();
String key = sm.key();

if (sm.localLabel().equals("")) {
result += "Visualage Pacbase server exception with key [" + key + "]
: (no label)\n";
} else {
result += "Visualage Pacbase server exception with key [" + key + "]
: " +sm.localLabel().substring(0) + "\n";
}
}
return result;
}
10.2.3 CommandFactory
The CommandFactory class is based on the factory pattern. It hides the
mechanism of procuring a command, given the class name of the desired
instance.
Implementation of this CommandFactory is similar to the example presented in

the figure about Java implementation for the factory pattern.
10.2.4 Command programming process

The command programmer builds a concrete command class by implementing
the command interface.
A command may require some input properties. Because the command class
should be a JavaBean, we recommended that the command follow the standard
JavaBean naming guidelines. This means that the input parameters are
JavaBean input properties and should have a signature like:
public void setXxx (Xxx xxx)
The output parameter should be JavaBean output properties with a signature

like:
public Xxx getXxx ()
10.3 Business object framework

Business object is the term we use to designate the main business component in
our client-side architecture. This business object is a high-level interface that
encapsulates many other subsystem interfaces behind a single unified interface.

In the VisualAge Pacbase context, we use the business object as a services filter
for the services associated with the folder proxy. The business object interface
encapsulates the folder proxy interface, its dependent proxies interfaces, and its
reference proxies interfaces behind a single unified interface.
The Business object framework captures these basic concepts and provides an
extendable infrastructure.
The components of this framework are:

򐂰 The BusinessObject interface
򐂰 The BusinessObjectFactory class
10.3.1 BusinessObject interface

The BusinessObject interface should provide the minimum set of methods
common to all business objects. Actually, it does not specify any method in its
first version presented here. Anyway, the BusinessObject interface is still useful
to classify business objects, and to provide a generic factory as follows:
public interface BusinessObject extends Serializable {
}
10.3.2 BusinessObjectFactory
The BusinessObjectFactory class is based on the factory pattern. It hides the
mechanism of procuring a business object, given the class name of the desired
instance.
Implementation of this BusinessObjectFactory is similar to the one presented in

the previous figure about Java implementation of the factory pattern. The only
important difference is that this factory is going to initialize the proxy it
instantiates.
A folder proxy needs information about how to locate the VisualAge Pacbase
middleware. We can specify either the locations file path (when using local
middleware) or the gateway host and port (when using a local or remote
gateway). To do that, we define constants in the BusinessObjectFactory class as
follows:
/default is to use local middleware
private final static boolean cvUsingGateway = false;
//default locations file name

private final static String cvLocationsFile = "vaplocat.ini";
//default is local gateway

private final static String cvHost = "127.0.0.1";
//default gateway port is 5647

private final static int cvPort = 5647;
The constants for the file name, IP address, and port could be externalized into a
Java properties file and this is highly recommended.
It is good practice to use these constants during instantiation to centralize the set
up of such communication parameters. An example follows:
private BusinessObject createNewInstance(String
businessObjectClassName) throws Exception {
Class c = Class.forName(businessObjectClassName);
BusinessObject bo = (BusinessObject) c.newInstance(); //casting
if (bo instanceof Folder) {
if (cvUsingGateway) {
initializeForGateway((Folder) bo);
} else {
initializeForLocationsFile((Folder) bo);
}
}
return bo;
}
private void initializeForGateway(Folder bo) throws Exception {

Class classe = Class.forName(bo.getClass().getName());
Class[] typesHost = new Class[1];
typesHost[0] = String.class;
Method methodeHost = classe.getMethod("setHost", typesHost);
methodeHost.invoke(bo, new Object[] {cvHost});
Class[] typesPort = new Class[1];
typesPort[0] = int.class;
Method methodePort = classe.getMethod("setPort", typesPort);
methodePort.invoke(bo, new Object[] {new Integer(cvPort)});
}
private void initializeForLocationsFile(Folder bo) throws Exception {

Class classe = Class.forName(bo.getClass().getName());
Class[] typesLocationsFile = new Class[1];
typesLocationsFile[0] = String.class;
Method methodeLocationsFile = classe.getMethod("setLocationsFile",
typesLocationsFile);
methodeLocationsFile.invoke(bo, new Object[] {cvLocationsFile});
}

10.3.3 Business object programming process
The business object programmer builds a concrete business object class by
implementing the BusinessObject interface and subclassing a ProxyLv subclass.
Because the business object class should be a JavaBean, it is recommended

that the command follow the standard JavaBean naming guidelines. That means
that the input parameters are JavaBean input properties and should have a
signature like:
The output parameters should be JavaBean output properties with a signature

like:
10.3.4 Relation to the command

A concrete command will access one or more business objects, and eventually
will keep a reference for these business objects.
Several commands may access the same business object.
10.4 Model layer summary

Figure 10-2 summarizes the Model layer.

Command Business
Proxy
Factory Object Factory
Instantiation Instantiation
Request for
Service
XCommand XBusinessObject
O.. O..
Implements Implements
Command Business Object
Figure 10-2 Model layer summary

11
Chapter 11. Creating presentation

with JSPs
coded as JavaServer Pages (JSPs). In this chapter, we discuss how to use the
JavaServer Pages (JSP) version 1.0 specification to create dynamic Web pages
for VisualAge Pacbase e-business applications.
This chapter begins with a brief introduction to JSPs, and how they interact with
the application server. Later in the chapter, we discuss main JSP syntax
elements, and we provide details on how to create presentation logic using JSPs
in the VisualAge Pacbase context.
Throughout this redbook, we use the JSP 1.0 specification; however, WebSphere
Application Server 3.02 and VisualAge for Java 3.02 support both JSP 1.0 and
JSP 0.91 specifications.
In addition to reading this chapter, you may also want to refer to Servlet and JSP
Programming with IBM WebSphere Studio and VisualAge for Java, SG24-5755
for much more detail on JSP specification, JSP tags syntax, and JSP use.
Note: WebSphere Application Server 3.5x and VisualAge for Java 3.5x will
support both JSP 1.1 and JSP 1.0 specifications.

11.1 Introduction to JavaServer pages
JavaServer Pages (JSPs) are similar to HTML files, but provide the ability to
display dynamic content within Web pages. JSP technology separates the
development of dynamic Web page content from static HTML page design. The
result of this separation means that the page design can change without the
need to alter the underlying dynamic content of the page.
To facilitate embedding of dynamic content, JSPs use a number of tags that

enable the page designer to insert the properties of a JavaBean object and script
elements into a JSP file. Tags provide an easy way to embed and modify
JavaBean properties and to specify other directives and actions. JavaBeans
provide the inherent reusability offered by this technology.
JSPs are made operable by having their contents (HTML tags, JSP tags and
scripts) translated into a servlet by the application server. This process is
responsible for translating both the dynamic and static elements declared within
the JSP file into Java servlet code that delivers the translated contents through
the Web server output stream to the browser.
The following process outlines the tasks performed on a JSP file for the first
invocation of the file (or when the underlying JSP file changes):
1. The Web browser makes a request to the JSP page.
2. The JSP engine parses the contents of the JSP file.
3. The JSP engine creates temporary servlet source code based on the
contents of the JSP. The generated servlet is responsible for rendering the
static elements of the JSP specified at design time in addition to creating the
dynamic elements of the page.
4. The servlet source code is compiled by the Java compiler into a servlet class
file.
5. The servlet is instantiated. The init and service methods of the servlet are
called, and the servlet logic is executed.
6. The combination of static HTML combined with the dynamic elements
specified in the original JSP page definition are sent to the Web browser
through the output stream of the servlet’s response object.
11.2 Components of JavaServer pages

The available JSP elements defined in the JSP 1.0 specification are categorized
as follows:

򐂰 Directives
򐂰 Scripting
򐂰 Actions
This section briefly describes each of these categories.For more details on each
category, refer to Servlet and JSP Programming with IBM WebSphere Studio
and VisualAge for Java, SG24-5755.
11.2.1 JSP directives

A JSP directive is a global definition sent to the JSP engine that remains valid
regardless of any specific requests made to the JSP page. A directive always
appears at the top of the JSP file, before any other JSP tags.
The syntax of a directive is:

<%@ directive {attribute="value"}* %>
JSP 1.0 specification defines page, include and taglib directives.
11.2.2 Page directive

The page directive defines page dependent attributes to the JSP engine. The
available attributes for JSP page directives are listed in Table 11-1.
<%@ page page_directive_attr_list %>
Table 11-1 Available attributes for JSP page directive

Attribute Value
language "scriptingLanguage"
extends "className"
import "packageList"
session "true|false"
buffer "none|sizekb"
autoFlush "true|false"
isThreadSafe "true|false"
info "infoText"
errorPage "errorUrl"
isErrorPage "true|false"
contentType "Type | Type; charset=CHARSET
Chapter 11. Creating presentation with JSPs 259

For example:
<%@ page language="Java" session="true" errorPage="/error.jsp" %>
Include directive
The include directive allows substitution of text or code to occur at translation
time:
<%@ include file="relativeURLspec" %>
You can use the include directive to provide a standard header on each JSP
page, for example:
<%@ include file="banner.html" %>
11.2.3 JSP scripting

Scripting covers the following tags:
򐂰 Declarations
򐂰 Scriptlets
򐂰 Expressions
Declarations
A declaration block contains Java variables and methods that are called from an
expression block within the JSP file. Code within a declaration block is often used
to perform additional processing on the dynamic data generated by a JavaBean
property.
The syntax of a declaration is:

<%! declaration(s) %>
For example:
<%!
private int count = 0;
private String getCount(int aCount)
{...method body here..;}
%>
Scriptlets
Scriptlets are used to embed small Java code blocks within the JSP page, rather
than to declare entire methods as performed in a declarations block. The syntax
for a scriptlet is:
<% scriptlet %>

For example:
<% if (Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM)
{%>
Good morning
Expressions
Expressions are scriptlet fragments whose results can be converted to string
objects for display in a browser. The syntax for an expression is:
<%= expression %>
Typically, expressions are used to execute and display the string representation
of variables and methods declared within the declarations section of the JSP, or
from JavaBeans that are accessed by the JSP.
Implicit objects
Within both scriptlets and expressions, there are some implicit objects available
for use without declaring them first. Table 11-2 introduces some of these implicit
objects.
Table 11-2 Some useful JSP implicit objects

Object name Description
request The HttpServletRequest object triggering the service invocation
response The HttpServletResponse object to the request
session The current HttpSession object
out The output stream writer
application The current ServletContext object
config The ServletConfig object for this JSP
exception Instance of Throwable (available to Error Pages)
11.2.4 Comments
You can use two types of comments within a JSP. The first comment style
enables the comment to appear in the output stream on the browser. It is an
HTML formatted comment whose syntax is:

The second comment style is used to fully exclude the commented block from the
output. The syntax is:
<%-- comment text --%>

11.2.5 JSP actions
The JSP 1.0 specification offers other standard JSP tags that are known as
action tags.
The standard action tags follow:

򐂰 <jsp:useBean />
򐂰 <jsp:setProperty />
򐂰 <jsp:getProperty />
򐂰 <jsp:request />
򐂰 <jsp:plugin />
򐂰 <jsp:include />
򐂰 <jsp:forward />
We limit our discussion to the action tags related to JavaBean use.
JSP useBean tag

The jsp:useBean tag is used to declare a JavaBean object that you want to use
within the JSP. Before you can use the jsp:getProperty and jsp:setProperty tags,
you must have first declared your JavaBean using the jsp:useBean tag.
The syntax for inserting a JavaBean is:

<jsp:useBean id="beanInstanceName"
scope="page|request|session|application"
typespec>
optional scriptlets and tags
</jsp:useBean>
Here, typespec can be declared using any of the following variations:

class="package.class"
type="package.class"
type="package.class" beanName="package.class"
When the jsp:useBean tag is processed, the application server performs a

lookup of the given Java object using the values specified in the id and scope
attributes. If the object is not found, it will attempt to create it using the values
specified in the scope and class attributes.
JSP getProperty tag

Once the bean has been declared, you can access its public properties using the
jsp:getProperty tag, which insert the String value of the primitive type or object
into the output stream. The syntax for this tag is:
<jsp:getProperty name="beanName" property="propertyName"/>

JSP setProperty tag
You can set the properties of a bean by using the jsp:setProperty tag. The syntax
for this tag is:
<jsp:getProperty name="beanName" property="propertyName"/>
11.2.6 About WebSphere specific tags

WebSphere Application Server version 3 offers a number of enhancements over
the JSP 1.0 specifications. They are not discussed here.
However, we will use one WebSphere extension for implementing the VisualAge
Cruise Lines sample application: the tsx:repeat tag.
The tsx:repeat tag is used to iterate through a database query result set using
the optional start and end values as the bounding indexes of the iteration. The
syntax of this tag is:
<tsx:repeat index=name start=start_index end=end_index>
</tsx:repeat>
You can also use this tag to iterate through any indexed property within a
JavaBean class or repeatedly call any method in a JavaBean until an
ArrayIndexOutOfBounds exception is thrown.
11.3 Implementing the presentation

coded as JavaServer Pages (JSPs).
This section focuses on the way we implement this kind of presentation in a

VisualAge Pacbase context, according to the targeted logical architecture.
11.3.1 Programming process

The presentation development team designs and develops static HTML pages
and static portions of JSPs, using WebSphere Studio.
The business logic development team designs and develops the commands and
business object beans. It also designs and develops the JavaBeans needed to
provide dynamic content for the JSPs. These JavaBeans, called
DataDeliveryBeans, are delivered to the presentation development team,
importing them from VisualAge for Java to WebSphere Studio.

There is no rule about the number of DataDeliveryBeans you create per JSP: it is
a compromise between reuse of existing DataDeliveryBeans and maintenance
considerations. We recommend one to four DataDeliveryBeans per JSP.
Because any DataDeliveryBean class should be a JavaBean, it is recommended

that the command follows the standard JavaBean naming guidelines. This means
that the input parameters are JavaBean input properties and should have a
signature like:
The output parameters should be JavaBean output properties with a signature

like:
The presentation development team uses the delivered DataDeliveryBeans to

provide dynamic content for the JSPs, accessing those JavaBeans through JSP
tags.

11.3.2 JSP tags guidelines

Here are some guidelines when implementing JSPs in our context:
򐂰 Whenever possible, we recommend using jsp:useBean, jsp:getProperty, and
jsp:setProperty tags to access the DataDeliveryBean.
򐂰 Since the DataDeliveryBean may contain some array properties, the use of
the tsx:repeat tag will permit you to iterate through this indexed property.
򐂰 Do not hesitate to explicitly use the import directive tag to keep your code
readable.
򐂰 Limit your utilization of scriptlets and expressions tags: if the actions tags can
be used, use them.
11.3.3 A very simple example using the DataDeliveryBean

The following example provides a very simple JSP example using a
DataDeliveryBean.
The purpose is to display the detail of an account balance. For this, we use the
AccountDeliveryBean and standard JSP tags as follows:
<HTML>
<HEAD>
<TITLE>

Very Simple Account Detail JSP
</TITLE>
<jsp:useBean id="account" type="example.AccountDeliveryBean" scope="request">
</jsp:useBean>
</HEAD>
<BODY bgcolor="#FFFFFF">
<FONT color="#FFFFFF">Account: </FONT><jsp:getProperty name="account"
property="getNumber"/>
<FONT color="#FFFFFF">Balance: </FONT><jsp:getProperty name="account"
property="getBalance"/>
</BODY>
</HTML>
11.4 Implementing wireless presentation using JSP

A wireless device lets you access the Web from anywhere at anytime. The great
number of operating systems (PalmOS, WindowsCE, EPOC, NokiaBrowser, and
so on) and bearer networks (GSM, CDMA, TDMA, and so on) dedicated to
wireless devices increase the difficulty of building wireless applications
11.4.1 About the Wireless Application Protocol (WAP)

The Wireless Application Protocol (WAP) is an attempt to standardize the
operating environment. The WAP architecture is a layered design of the entire
protocol stack consisting of an application layer and several communication
layers.
The application layer, called Wireless Application Environment (WAE), is an

application environment based on a combination of World Wide Web (WWW)
and telephony technologies. WAE includes a light markup language similar to
HTML and called Wireless Markup Language (WML), and a WML browser.
When deploying a WAP application, a WAP gateway is needed. The WAP

gateway encodes and decodes the content transferred between the mobile
device and itself, and translates requests between the WAP protocol and the
WWW protocol.
11.4.2 Serving dynamic WML content using servlets and JSPs

Building wireless applications that serve dynamic content can be very similar to
building traditional Web applications using servlets and JSPs.
The request/response process will be the following:

1. A mobile device sends a WAP request to the WAP gateway.

2. The WAP gateway decodes the request, creates a conventional HTTP
request, and forwards it to the target Web server.
3. The Web server processes the HTTP request and returns either a static WML
page or a WML content response from a JSP.
4. After verifying the HTTP header and WML content, the WAP gateway
encodes the content and sends this WAP response to the mobile device’s
WML browser.
11.4.3 WAP relative to our e-business architecture

Figure 11-1 shows the impact of WAP technology relative to our e-business
architecture.
HTML WebSphere Application Server

Browser
Proxy
HTTP
BusinessObject
JSP Servlet
Command
DataDeliveryBean
WML-based
WAP Servlet
JSP
WAP
HTTP
WAP
Gateway
Figure 11-1 WAP in the architecture
As you can see, only the presentation aspect of our architecture is impacted. The
WAP gateway produces HTTP which is easily recognizable by our controller
(servlet), which continues to manage the JSPs and issue requests to
CommandBeans. The model layer (the CommandBean-Proxy-DBMS interaction)
remains the same as before, as does the DataDeliveryBean.
The only programming impact on our framework would be to manage some WML
content JSPs instead of HTML content JSPs. This can be accomplished by
modifying the controller servlet, as we will see later.
This discussion of adapting to WAP demonstrates the validity and strength of our
e-business architecture, which is based on the model-view-controller framework.

12
Chapter 12. Implementing navigation

with servlets
In this chapter we discuss how to use servlets to implement navigation for our
application.
We begin with a brief introduction to Java servlet concepts and the Java Servlet
API. Later in the chapter, we provide details on the way to use servlets as
navigation controllers.
In addition to reading this chapter, you may also want to refer to Servlet and JSP
Programming with IBM WebSphere Studio and VisualAge for Java, SG24-5755
for much more details on Java Servlet API, the servlet runtime life-cycle, and
advanced servlet functionalities.

12.1 Introduction to Java servlets
Servlets are characterized by the following:
򐂰 Servlets are protocol and platform independent server-side software
components and are written in Java.
򐂰 Servlets run inside a Java enabled server or application server, such as the
WebSphere Application Server.
򐂰 Servlets are loaded and executed within the Java Virtual Machine (JVM) of
the Web server or application server.
12.1.1 Servlet process flow

Servlets implement a common request/response paradigm for the handling of the
messaging between the client and server. The Java Servlet API defines a
standard interface for the handling of these request and response messages
between the client and server.
The client-to-servlet process flow occurs as follows:

1. The client sends a request to the server.
2. The server sends the request information to the servlet.
3. The servlet builds a response and passes it to the server. That response is
dynamically built, and the content of the response usually depends on the
client’s request.
4. The server sends the response back to the client.
12.1.2 The Java Servlet API

The Java Servlet API is a set of Java classes which define a standard interface
between a Web client and a Web servlet.
The Java Servlet API is a Standard Java Extension API. Throughout this book,
we use the Java Servlet Development Kit API (JSDK) V2.1 conventions.
The API is composed of two packages:

򐂰 Javax.servlet
򐂰 Javax.servlet.http
The Javax.servlet package contains classes to support generic

protocol-independent servlets. This means that the servlet can be used for many
protocols (HTTP and FTP, for example).

The Javax.servlet.http package extends the functionality of the base package to
include specific support for the HTTP protocol.
The Servlet interface class is the central abstraction of the Java Servlet API. This
class defines the methods which servlets must implement, including the service()
method for the handling of requests. The GenericServlet class implements this
interface, and defines a generic, protocol-independent servlet. To write an HTTP
servlet for use on the Web, we use a more specialized class of GenericServlet
called HttpServlet.
HttpServlet provides additional methods for processing HTTP requests such as

GET (doGet method) and POST (doPost method). Although our servlets may
implement a service method, in most cases we implement the specific request
methods of doGet and doPost.
12.1.3 Persistency management

When developing Web applications, a common issue is maintaining persistent
data during a user session.
The details of persistent data are well beyond the scope of this redbook. In this
section, we discuss some useful techniques for persistency in the WebSphere
Application Server (WAS) context. Persistency of data outside this WAS context
is not covered, assuming that it is the responsibility of the VisualAge Pacbase
components.
ServletContext
A servlet context (Javax.servlet.ServletContext) defines a group of related
servlets. A servlet context object is at least as unique as the host in which it
resides. In a servlet engine that handles multiple virtual hosts, each virtual host
must be treated as a separate context.
This allows for simple application-scoped data sharing between servlets, using
the getAttribute/setAttribute methods. Note that the servlet context attributes are
known as “application” attributes in the JavaServer Page specification.
This allows a servlet to load resources without assuming a directory structure on

the server, using the getResource method.
Cookies
Cookies are a way to place persistent information on the client machine and to
make that information accessible from the browser.
Chapter 12. Implementing navigation with servlets 269

Cookies have names and values like hashtable entries, and are a good way to
handle preferences or shortcuts. Note that cookies can be turned off at the user's
end.
The Cookie API provides methods to:

򐂰 Create cookies
Cookie(String name,String value)
򐂰 Save a cookie
HttpServletResponse.addCookie(Cookie aCookie)
򐂰 Retrieve cookies
HttpServletRequest.getCookies()
򐂰 Get a cookie’s name
aCookie.getName()
򐂰 Get a cookie’s value
aCookie.getValue()
򐂰 Change a cookie's value
aCookie.setValue(String)
Cookies have an “expiration duration”, expressed in seconds. Default expiration

is 0, which means that the cookie is not stored persistently and lasts only as long
as the browser is open. To change the expiration duration, use:
setMaxAge (int expiryInSeconds)
12.1.4 Session
The HttpSession interface is the application state management API. This
interface:
򐂰 Represents a client/server connection
򐂰 Has a lifetime that spans multiple servlets
򐂰 Is identified within requests via a session identifier
Servlets should be stateless and not store any state information within
themselves. The session is the proper repository for application state.
Note that Javax.servlet.http.HttpSession is a Java Interface. In WebSphere the

actual runtime object (implementation of HttpSession) is
com.ibm.servlet.WebSphere.servlet.session.IBMSession.
To ask for a session from the HttpRequest object you use:

request.getSession(boolean create)

This returns the current HttpSession. If create is true AND no current Session
exists, a newly created session is returned. This is the recommended way to
establish a new session. If you set create to false and a Session doesn't exist, it
returns null. Always check for a null value.
HttpSessions store application-specific information via a “key”:

void putValue(String, Object)
Object getValue(String)
Sessions act like hashtables or properties. You can store any object on a
hashtable, but it must be serializable.
12.2 Implementing the navigation

Navigation refers to developing controller servlets. Controller servlets have two
major responsibilities:
򐂰 Processing the HTTP request from a Web browser
򐂰 Sending the HTTP response to the Web browser
Processing the HTTP request from a Web browser is partially delegated to the
model layer (business logic). Sending the HTTP response to the Web browser is
partially delegated to the JSP (presentation layer). Both are assumed to be under
the control of the servlet.
This section focuses on the way we implement this navigation in a VisualAge

Pacbase context, according to the targeted logical architecture described in the
chapter, Targeted Application Architecture.
12.2.1 Programming process

The presentation development team designs and develops HTML pages and
JSPs, using WebSphere Studio and the DataDeliveryBeans developed by the
business logic development team.
As a result, a servlet can be generated by the presentation development team for

each JSP produced. This servlet is delivered back to the business logic
development team by importing it from WebSphere Studio to VisualAge for Java.
The business logic development team then customizes the servlet to implement
the required control mechanism and navigation.


12.2.2 Granularity
Designing the granularity of servlets and how servlets interact is not an easy
task.
One extreme design approach would be to have only one servlet per use case.
That servlet would then process all requests from the client, and forward the
request to one or more JSPs to display the result. The disadvantage to using this
approach is that we will have to implement a great deal of logic in that servlet.
Another extreme approach would be to have as many servlets as JSPs and

“chain” them together. That means that a servlet gets a request, executes the
proper action and calls a JSP specific to that servlet to display the result. The
disadvantage to using this approach is the confusion that results when trying to
figure out the flow of the application.
Our approach is based on the Model-View-Controller framework. Referring to our

model layer, it appears that we can transfer the granularity issue to the
CommandBean. Doing this makes our application model-centric: it is the model
layer that determines the granularity.
We recommend having only one servlet per CommandBean: that servlet being
the controller for the command execution and result. That means that a servlet
gets a request, executes the proper command, populates the resulting
DataDeliveryBean, and forwards the request to one or more JSPs for displaying
this DataDeliveryBean.
The issue of the command granularity then becomes a model design issue, with
the reminder that a CommandBean corresponds to specific business logic, such
as a query or an update.
12.2.3 Control mechanism and navigation

The controller servlet manages the navigation and makes the user interaction
(the request) understandable by the model layer (business logic). The controller
servlet:
1. Validates the request, request parameters, and session parameters.
2. Populates the CommandBean with request parameters.
3. Executes the command (which means use of a BusinessObject).
4. Receives the command results (which eventually refers to a JSP name and a
BusinessObject) and populates the DataDeliveryBean if needed.
5. Calls the appropriate JSP with the DataDeliveryBean.

Figure 12-1 illustrates the control mechanism.
1 BusinessObject
HTML page
or JSP
3
ControllerServlet
2 Command
5
4
JSP DataDeliveryBean
Figure 12-1 Control mechanism: servlet/command/JSP
Note: To this basic control mechanism, we could add two classes: the
RequestBean class and the ResultBean class. The RequestBean would be
the generic call contract between the controller servlet and the
CommandBean. The ResultBean would be the generic return contract
between the CommandBean and the servlet. Both the RequestBean and the
ResultBean could be dynamically populated using some kind of builder,
though our framework does not go this far.
12.2.4 Non JSP resulting servlets

Since we have one servlet for one CommandBean, we may need to implement
servlets that do not result in a JSP call (for example. when executing commands
that have no visual result).

During the handling of a request, a servlet may:
򐂰 Incorporate the result of another servlet into the output stream (include)
򐂰 Delegate the continued handling of the request to another servlet (forward)
Figure 12-2 illustrates include and forward.
Browser
Forward
Servlet A Servlet B
Content returned
to Browser
Browser
Include
Servlet A Servlet B
Content returned
to Browser
Figure 12-2 Servlets: Include and Forward
In the case of include and forward, you must remember that JSDK 2.1 adds a
new interface:
Javax.servlet.RequestDispatcher
This RequestDispatcher is acquired from the ServletContext and is used to

support the forwarding of processing to another servlet and also including the
result from another servlet in this response:
getServletContext().getRequestDispatcher("path");
path is an URI relative to ServletContext’s root
Note: This RequestDispatcher class is also useful to call a JSP from a servlet.
Actually, it is a good example of forward use.

12.2.5 A generic controller servlet
We recommend the use of an abstract controller servlet to provides generic
facilities and to structure the development.
All concrete controller servlets should inherit from this abstract controller servlet.
One servlet is linked to one Command implementation described by the
getCommandName method. The first time the getCommand method is
accessed, the appropriate CommandBean is created through the
CommandFactory.
The coding that follows is the recommended Java implementation of this generic
controller servlet:
public abstract class ControllerServlet extends HttpServlet {
private Command ivCommand;
public ControllerServlet() { //ControllerServlet default constructor.

super();
}
private final Command getCommand() { // Return the associated Command.

if (ivCommand == null) {
try {
ivCommand = CommandFactory.createInstance(getCommandClassName());
} catch (IllegalAccessException iae) {
handleException(iae);
} catch (InstantiationException ie) {
handleException(ie);
} catch (ClassNotFoundException cnfe) {
handleException(cnfe);
}
}
return ivCommand;
}
protected abstract String getCommandClassName(); // Return the associated

Command class name. To be redefined by subclasses.
}
In our approach to developing e-business applications, we recommend that the

doGet and doPost methods delegate to the same performTask method:
public void doGet(HttpServletRequest req, HttpServletResponse res) throws
ServletException, IOException {
performTask(req, res);
}

public void doPost(HttpServletRequest req, HttpServletResponse res) throws
ServletException, IOException {
performTask(req, res);
}
The performTask method is responsible for performing the needed task. It has to
be redefined by every subclass. The redefined performTask method will trap all
exceptions and not let any propagate out. The redefined performTask method
calls the executeCommand method.
public abstract void performTask(HttpServletRequest req, HttpServletResponse
res);
The executeCommand method provides a generic and uniform way to execute

the command:
protected final void executeCommand() {
try {
getCommand().execute();
} catch (CommandException ce) {
handleException(ce);
}
}
The following handleException method code provides an example for the Web
Application and WebSphere logfiles. This code should be redefined by concrete
controller servlets:
protected void handleException(Throwable throwable) {
// Prints a message to the default log file for the Web Application
System.out.println(throwable.getMessage());
// Prints a message to the WS3.0 console window
log(throwable.getMessage());
}
Note: Concerning the WAP issue, two ways can be explored:
One way is to implement a trigger in the performTask method to return the

appropriate JSP (HTML or WML based) according to the context.
Another way is to subclass any concrete controller servlet by a WAP servlet

which only redefines the performTask method.

13
Chapter 13. Testing and deployment

In this chapter we discuss the targeted application architecture that we
introduced in Chapter 2 and describe tools that will help you test your application.
After they have been developed, both the server-side and the client-side
components need to be tested. Following successful testing, the components
can be deployed into the production environment.
First, we focus on the VisualAge Pacbase (VAP) Test Tool, which is used to
validate server developments.
Next, we review the main servlet/JSPs testing tools available with VisualAge for
Java.
Finally, we introduce the issue of deployment.

13.1 Using the VisualAge Pacbase Test Tool
The VisualAge Pacbase Test Tool (VAP Test Tool) is a new feature of VisualAge
Pacbase Version 3.0.
VAP Test Tool basically provides a Folder Proxy browser. The purpose is to
identify problems related to:
Folders and elementary components design and implementation
Proxies generation
Communication and middleware
Using the VAP Test Tool permits you to validate your server development and
your communication infrastructure. The tool was created to save time: you do not
have to write or wait for a graphical user interface before testing your servers.
During testing, the VAP Test Tool also provides a good way to determine whether
anomalies are “server-side” or “client-side” problems.
The VAP Test Tool is limited. Excluded from VAP Test Tool are:
򐂰 Proxy API usage
򐂰 Servlets design and implementation
򐂰 JavaBeans design and implementation
򐂰 JSPs design and implementation
򐂰 WebSphere Application Server deployment
13.1.1 Installing the tool

For this redbook, we installed the VAP Test Tool from a compacted file (ZIP) into
the VisualAge for Java environment. Another option would be to install it as part
of the VisualAge for Pacbase Workbench.
Actually, the VAP Test Tool install we did uses the VisualAge for Java Tool API to
fully integrate the VAP Test Tool inside the VisualAge for Java IDE.
As a result, the tool is accessed through the Tools-->VisualAge Pacbase-->

Folder Browser sub-menu from the Workspace menu, as shown Figure 13-1.

Figure 13-1 VAP Test Tool launching menu
The tool can also be used through the same sub-menu from the Selected menu
(or right-clicking for a context menu) when selecting a project, a package, or a
Folder proxy class.
13.1.2 Configuring the tool

We configure VAP Test Tool using a specific configuration file. This configuration
file is named configuration.properties and is located in the tool directory:
<VisualAgeRootDirectory>\Ide\Tools\com-ibm-vapt-jface-plus
where <VisualAgeRootDirectory>is the root directory where you installed
VisualAge for Java, for example: E:\IBMVJava
Table 13-1 shows the configuration.properties main parameters.
Chapter 13. Testing and deployment 279

Table 13-1 Main parameters for configuration.properties file
Parameter name Description Default value
locationsFile Server locations file No default value,

(vaplocat.ini file) mandatory when not
using gatewayHost and
gatewayPort
parameters
gatewayHost IP address for the Empty, meaning we do

VisualAge Pacbase not use any gateway but
gateway in use instead we use the
middleware DLLs
directly
gatewayPort Port for the VisualAge No default value,

Pacbase gateway in use mandatory when
gatewayHost parameter
is not the default
gatewayPath Path for the gateway No default value

executable, if it is a local
gateway. Can be used to
automatically launch the
gateway if it is not running.
traceFile Name and path of the trace <Runtime "user.home"

file. directory> + "Traces.txt"
If no trace is desired,
then explicitly write
traceFile=
(that means empty)
generatedProxiesPackage Package that contains the No default value

generated proxies when
there is only one package
(as a result, the package is
added to the tool
classpath)
generatedProxiesPackage.n Package that contains the No default value

generated proxies when
there is more than one
package. That means that
a line with n=1, then n=2,
and so on, must be added
for each package
(as a result, each package
is added to the tool
classpath)

The following example shows the use of configuration parameters to run the tool
using a local gateway and three proxies packages:
gatewayHost=127.0.0.1
gatewayPort=5647
generatedProxiesPackage.1=com.cruise.cruise.proxies
generatedProxiesPackage.2=com.cruise.destination.proxies
generatedProxiesPackage.3=com.cruise.ship.proxies
13.1.3 Running the tool

This section is not intended to be a VAP Test Tool user guide. For such a user
guide, consult the documentation CD delivered with VisualAge Pacbase. Here,
we only want to give you an idea of the facilities provided by the VAP Test Tool.
Selecting the Tools-->VisualAge Pacbase--> Folder Browser menu choice

(either from Workspace or Selected menus), launches the VAP Test Tool as
Figure 13-2 VAP Test Tool folders browser

The different menu choices offer facilities to test all the Proxy APIs. Local Actions
that can be tested include:
򐂰 Initialization
򐂰 Updates
򐂰 Cancellation of updates
򐂰 Management of user services
Server actions that can be tested include:

򐂰 Selections
򐂰 Management of paging
򐂰 Sending of updates
򐂰 Management of dependent instances
򐂰 User services
򐂰 Asynchronous conversation
Two panels are provided to display instances (rows and details).
The folders panel (on the left of Figure 13-2) provides a hierarchical view of
available folders, as shown in Figure 13-3.
Figure 13-3 VAP Test Tool folders hierarchal view

Remember that not all of the folders are visible. To browse a Folder proxy, you
must describe its Java package in the configuration.properties file. A folder is
represented by a typical file folder icon, a dependent node is represented by a
kind of gear-looking icon, and a reference node is represented by a kind of
x-shaped icon labeled with a one-to-one cardinality. A pop-up menu is available
for each type of node, providing the contextual actions available for the node.
13.2 Other client-side test tools

During development, VisualAge for Java provides three integrated tools to test
the client-side application:
򐂰 The VisualAge for Java Debugger provides facilities to view, execute, and
monitor your Java code by setting breakpoints and changing the values of
switches and variables.
򐂰 The WebSphere Test Environment simulates a Web Server within VisualAge
for Java. It provides access to the Java Debugger for JavaBeans and Servlets
running in the simulated servlet engine.
򐂰 The JSP execution monitor provides facilities to review JSP compilation and
execution.
For more details on the VisualAge for Java Debugger, refer to the product
documentation.
For more details on how to build, test, and run servlets in the WebSphere Test
Environment, and for more information about the use of the JSP Execution
Monitor for the testing of JSPs, refer to Servlet and JSP Programming with IBM
WebSphere Studio and VisualAge for Java, SG24-5755. Chapter 7 of this
SG24-5755 redbook shows how to test complete Web applications.
13.3 Deploying an e-business application

This section provides information about deployment. We briefly discuss the
deployment of:
򐂰 Backend servers
򐂰 HTML Pages and JSPs (presentation layer)
򐂰 Servlets and JavaBeans (model and controller layers)

13.3.1 Deploying server side components
In order to deploy the backend servers, you must generate the application
components from the VisualAge Pacbase repository. This results in source
(COBOL) that must be compiled into your test environment where your servers
need to be positioned.
In addition, you will need to create and position the databases to support your
test data. In our case, we used DB2. Our DB2 test database was already in
existence and so we were able to leverage that for our testing. Had the database
not existed, we could have generated the DDL from VisualAge Pacbase and
used it to create our database. We could have also written, compiled, and
executed a simple batch COBOL program to process flat files and populate the
DB2 database with our test data.
13.3.2 Deploying HTML pages and JSPs

HTML pages and JSPs are deployed in the WebSphere Application Server
(WAS).
You should refer to Servlet and JSP Programming with IBM WebSphere Studio
and VisualAge for Java, SG24-5755. Chapter 6 of this SG24-5755 redbook
explains the administration environment that comes with WAS, how it is
structured, and how you will use it to configure your server environment. In our
redbook, we describe where HTML pages and JSPs are deployed, nothing more.
The topology within WebSphere is based on a containment hierarchy which can

be seen in Figure 13-4.

Admin Virtual
Node
Domain Host
Application Servlet
Servers Engine
Web
Applications
one
many
Servlets JSPs HTML
Figure 13-4 WebSphere Application Server topology
You can see that HTML pages and JSPs are deployed in a Web Application. After
creating the necessary components - such as a Web Application - in the
WebSphere Admin Console interface, you have to physically put the resource
files into the correct directories. Table 13-2 displays where HTML pages and
JSPs must reside.
Table 13-2 Deploying HTML pages and JSPs to WAS

Description File extension Directory path
HTML documents and .html, .shtml, .jhtml, .gif, The Web Application
related files .jpg, .au, and so forth document root (or under
the HTTP server root)
JavaServer Pages .jsp The Web Application

document root
We give a concrete example of such a deployment in Part 2 as we deploy the


13.3.3 Deploying servlets and JavaBeans
Servlets and JavaBeans are also deployed in WAS, specifically they are
deployed in a Web application, as described in the SG24-5755 redbook. Table
13-3 displays where particular files must reside.
Table 13-3 Deploying servlets and JavaBeans to WAS

Description File extensions Directory paths
Servlets, JavaBeans, and .class, .jar, .ser The application class path or the
other Java classes Application Server class path.
If the servlets are in a package,
mirror the package structure as
subdirectories under the
application class path
Servlet configuration file .servlet The directory that contains the

servlet
The SG24-5755 redbook also explains the way to define servlets in order to
invoke them by an alias name, which is the preferred technique when using WAS.
We give a concrete example of such a deployment in part 2 as we deploy the

13.4 Runtime testing

When development, testing, and deployment are complete, you can start your
Application Server and your Web Application.
Make sure that any backend servers required are running (for example in our
case we needed to start DB2), and then you can begin to test your e-business
application with a browser.
The SG24-5755 redbook discusses the different levels of tracing support with
WebSphere Application Server. As a reminder, within WAS there are three
different ways of collecting troubleshooting information:
򐂰 Messages: Messages are visible in the Console Message pane of the
Administrative Console.
򐂰 Logs: Log files are kept within the <Drive>\WebSphere\AppServer\logs
directory. Here you can find the standard error and standard output files for
each application server that is running.
򐂰 Traces: To enable WAS tracing, select the menu option Console-->
Trace-->Enabled.

Part 2
Part 2 VisualAge Pacbase

Cruise Lines sample
application
In Part 2, we develop an e-business application using VisualAge Pacbase 3.0,
WebSphere Studio, and VisualAge for Java. We discuss design, construction,
testing, and implementation. Our sample application establishes a Web site for
the VisualAge Cruise Line sample and provides a WAP version of the
implementation as well.

14
Chapter 14. VisualAge Cruise Lines

application specifications
In this chapter we present the specifications and description for the VisualAge
Cruise Lines sample application that we developed using VisualAge Pacbase
3.0, VisualAge for Java and WebSphere Studio. The application is not intended
to be an authentic application. We built it to demonstrate how to use VisualAge
Pacbase 3.0 along with VisualAge Java and WebSphere Studio to develop a
basic application.

14.1 VisualAge Cruise Lines background
VisualAge Cruise Lines buys blocks of tickets from different cruise lines that sail
within the Caribbean Sea and then resells these tickets to individuals. Their
activity is similar to a no-frills travel agency business. VisualAge Cruise Lines is
very successful and business is increasing rapidly. Customer volume increased
strongly for the past five years and the company staff grew 30% in the last two
years. VisualAge Cruise Lines did a study about customer satisfaction and asked
for suggestions from employees for improving operations.
Customers complain that they must go to the VisualAge Cruise Lines offices to
get their tickets. Often they must wait a long time before being served. Customers
say it is difficult to get cruise information from the sales person.
Employees complain that cruise information must be obtained from papers and
leaflets. Employees spend hours on the phone waiting to make a customer
reservation only to be refused if the cruise is sold out. Employees spend too
much time updating cruise reservations.
14.2 VisualAge Cruise Lines requirements

VisualAge Cruise Lines wants a new system to address both customer and
employee concerns. The requirements for the new system relative to our sample
application include:
򐂰 For customer concerns
– An Internet site for customers to view cruise information and make
reservations quickly
– Ability to view cruise information from several cruise lines
– Customers can select a cruise line and view information about the cruise
line and the cruises it offers
– Customers can select a cruise and see additional detail about the ship as
well as the departure and arrival destinations
– Customers can use the Internet site to determine if tickets are available for
a cruise, see the price per ticket, and complete a reservation
– Cruise tickets are mailed directly to the customer
򐂰 For employee concerns
– An internal system to manage destinations

14.3 Data considerations
This section discusses the data that will be used in the development of our
sample application. The objects, relationships, and attributes have been
simplified in order to place the emphasis on the process of developing the
e-business sample application in the chapters which follow.
14.3.1 Objects
The VisualAge Cruise Lines sample application needs to manage information
about the following objects:
򐂰 Cruise lines
򐂰 Ships
򐂰 Cruises
򐂰 Destinations
򐂰 Reservations
Cruise lines are the companies that provide blocks of tickets to VisualAge Cruise
Lines for resale. Some customers prefer to buy tickets based on a preference for
a specific cruise line and so we need a way to manage cruise line information.
The attributes for the cruise line include:
򐂰 Cruise Line ID, a system assigned number to uniquely identify the cruise line
򐂰 Name, the name of the cruise line as it is known to the customer
򐂰 Country, the name of the country for the cruise line
Ships are the vessels used to carry passengers. For our sample application we
need the following attributes for each ship:
򐂰 Cruise Line ID, the system assigned number to uniquely identify the cruise
line that operates the ship
򐂰 Registry, the number that represents the unique identifier for the ship
򐂰 Name, the name of the ship as it is known to the customer
򐂰 Description, free form text to describe the basic features of the ship
Cruises are actually blocks of tickets for resale by VisualAge Cruise Lines. The
attributes that we need in our sample application are:
line that operates the ship
򐂰 Cruise ID, the system assigned number that uniquely identifies the block of
tickets
򐂰 Cruise name, the name of the cruise as it is known to the customer
Chapter 14. VisualAge Cruise Lines application specifications 291

򐂰 Number of available tickets, the total tickets still available for customer
purchase
򐂰 Number of reservations, the number of tickets that have been purchased by
customers
򐂰 Price, the price for one ticket for this cruise
Destinations are ports of departure and arrival for the cruises. The attributes
needed for each destination are:
򐂰 Destination ID, this is a system assigned number to uniquely identify the
destination
򐂰 Port name, this is the name of the port as it is known to the customer
򐂰 Port country, this is the name of the country where the port is located
Reservation represents the purchase of one or more tickets for a cruise by the
customer. The attributes needed for the reservation include:
򐂰 Reservation ID, this is a system assigned number to uniquely identify the
reservation
line
򐂰 Cruise ID, the system assigned number that uniquely identifies the cruise
(block of tickets)
򐂰 Number of tickets, the number of tickets purchased by the customer
򐂰 Total price, the total cost of the tickets for the customer
14.3.2 Relationships
In this section we describe the relationships between the objects that make up
the VisualAge Cruise Lines sample application.
The first relationship of interest involves cruise line and ship. A cruise line can
operate one or more ships and a ship is operated by one and only one cruise
line. This relationship has been implemented hierarchically.
The second relationship involves ship and cruise. Recall that a cruise is a block
of tickets. A ship can have one or more blocks of tickets (cruises) associated with
it and a block of tickets must be related to one and only one ship. This
relationship has also been implemented hierarchically

The third relationship concerns cruise and destination. In this case, a cruise must
have two and only two destinations, a departure destination and an arrival
destination. A destination, however, can be related to several cruises for several
ships and can involve many cruise lines. This relationship therefore needs to be
implemented in a relational manner.
The fourth relationship is mentioned here because of the way it is represented in

our sample application. The reservation object previously discussed actually
implements the relationship between the customer (not specifically included in
our example) and the cruise. We treat the customer-cruise relationship as the
reservation object in order to manage the attributes that result from this
relationship.
14.3.3 Data implementation

In this section we describe the basic concepts used to implement the objects,
attributes, and relationships for our VisualAge Cruise Lines sample e-business
application.
All of the attributes were defined as data elements using the e-business
developer Workbench. Figure 14-1 shows a partial display of the elements from
the e-business Workbench.
Figure 14-1 Data elements supporting the sample application

Segments were created for the cruise line, ship, cruise, destination, and
reservation objects and populated with data elements corresponding to their
attributes. Figure 14-2, from the e-business Workbench, shows the segments
created to support our VisualAge Cruise Lines sample application.
Figure 14-2 Segments supporting the sample application

These segments were necessary to support the logical views for the sample
application, seen in Figure 14-3.
Figure 14-3 Logical views for the sample application
The hierarchical relationships between cruise line, ship, and cruise were
implemented as follows in VisualAge Pacbase with the e-business entity:
򐂰 Cruise line becomes a folder.
򐂰 Since the ship is hierarchically related to the cruise line in a mandatory
relationship, the ship becomes a dependent node in the cruise line folder.
򐂰 Since the cruise is hierarchically related to the ship in a mandatory
relationship, the cruise becomes a dependent node positioned under the ship
node in the cruise folder.

Figure 14-4 shows the folder established for our VisualAge Cruise Lines sample
application.
Figure 14-4 Folder content for sample application
The non-hierarchical relationships were implemented in VisualAge Pacbase as

follows:
򐂰 In order to implement the departure destination and the arrival destination for
the cruise, two reference nodes were added below the cruise.
– One reference node for destination called departure
– A second reference node for destination called arrival
– This is a reasonable way to implement relationships that have a fixed
cardinality, as is the case with the destination, the limit of relationships to
occurrences of destination is exactly two. Incidentally, the use of reference
nodes here demonstrates a method for implementing sub-types of objects
from a data model as well.
򐂰 Destination is implemented as a folder, referred to as a single node folder
because it does not contain any dependent nodes or reference nodes.
򐂰 Reservation is also implemented as a folder. In this folder, we established
cruise as a reference node.

The structure for our data implementation appears in Figure 14-5.
CRUISE LINE
(folder)
SHIP (Dependent node)
CRUISE (Dependent node)
Reference
nodes
for Departure
destination
DESTINATION Arrival
(folder, single node)
RESERVATIONS
CRUISE (Reference node)
Figure 14-5 Data implementation structure
14.4 Processing considerations and implementation

Our VisualAge Cruise Lines sample application requires us to consider the
processing, data access, and presentation aspects of our e-business application.
The following processing requirements are in no way the complete set of

requirements for an authentic cruise reservation system. The main processing
considerations are described here because they were included in the sample
application to demonstrate the use of VisualAge Pacbase.
When the customer requests a display of the cruise lines, ships, or cruises, the
list should be presented in alphabetical sequence.
If the customer has restricted the request to a specific cruise line, then the
information displayed must be for that cruise line only.

When a customer indicates a desire to purchase a ticket, the following is
required:
򐂰 The system must generate the identifier for the reservation
򐂰 The number of tickets available must be decreased by the number of tickets
being purchased
򐂰 When no more tickets are available for purchase, the display should indicate
“sold out.”
򐂰 The number of tickets purchased for the cruise must be increased by the
number purchased by the customer
򐂰 The total price of the tickets purchased by the customer must be calculated
and updated as part of the reservation
All of the preceding process considerations (generating unique identifiers,

calculations) were implemented with specific code in VisualAge Pacbase. Figure
14-6 shows the elementary components established for the VisualAge Cruise
Lines sample application.
Figure 14-6 Elementary components for the sample application

14.5 VisualAge Cruise Lines customer reservation
In this section we describe the customer reservation sample application that we
developed based on the requirements from the VisualAge Cruise Lines.
The customer reservation application is a Web-based system accessible to

customers through the Internet. When the homepage is reached, the customer
can select various options.
The homepage for VisualAge Cruise Lines is seen in Figure 14-7.
Figure 14-7 Homepage for the sample application

From the homepage, customers can proceed to a page where they can enter
search criteria for the cruise line or they can select to see information for all
cruise lines. This panel is shown in Figure 14-8.
Figure 14-8 Cruise line selection

The customer clicks either the All hyperlink or a hyperlink for a specific cruise
line. This results in the next panel, which displays the cruise line detail as shown
in Figure 14-9.
Figure 14-9 Cruise line detail

The cruise line detail panel lists the cruise line, its ships, and the available
cruises. The customer clicks on the hyperlink associated with the cruise to
proceed to the panel shown in Figure 14-10.
Figure 14-10 Specific cruise detail
The panel in the preceding figure displays the detail for the selected cruise and
includes:
򐂰 Cruise line
򐂰 Ship
򐂰 Ship description
򐂰 Cruise
򐂰 Tickets available
򐂰 Price per ticket

The panel allows the customer to indicate the quantity of tickets and to complete
the purchase using the Purchase button. This results in the panel in Figure
14-11.
Figure 14-11 Customer reservation confirmation
The preceding panel is used to confirm the reservation for the customer. The
customer confirmation includes:
򐂰 Reservation ID
򐂰 Number of tickets purchased
򐂰 Message indicating that the tickets will be mailed to the customer’s address

14.6 VisualAge Cruise Lines management
In this section we describe the cruise management sample application that we
developed based on the requirements from the VisualAge Cruise Lines.
The cruise management system runs on the VisualAge Cruise Lines intranet.
Employees use this system to add cruise lines and the corresponding cruise
details such as ships, cruises and related information for destinations.
For the purpose of this redbook we are building the process that adds
destinations in order to demonstrate how to use VisualAge Pacbase to produce a
Web-based application.
For simplification, we set up access to the cruise management system from the
homepage. Selecting the employees hyperlink from the homepage presents
Figure 14-12.
Figure 14-12 Employee sign on for cruise management

Following the login, the employee can choose to maintain any of several
catalogs. Figure 14-13 provides the necessary hyperlinks.
Figure 14-13 Employee intranet choices

For our redbook example, we implemented the destinations catalog. This is a
panel that allows the employee to add destinations which later can be used as
the departure and arrival ports for cruises. When the hyperlink for the
destinations catalog is clicked, the panel displays a list of the destinations that
are already established, as seen in Figure 14-14.
Figure 14-14 Destinations already established

To add a new destination to the catalog, the employee clicks the Add
Destination... button. This displays Figure 14-15, which is used to enter a
three-character code for the location and a more descriptive name. Pressing the
Submit button completes the addition of the destination and returns to the
previous panel, pressing the Reset button clears the entry fields.
Figure 14-15 Adding a destination

15
Chapter 15. Bridging from Rational Rose

In this chapter we describe the bridge from Rational Rose to VisualAge Pacbase,
the approach to using the bridge, and the constraints associated with the bridge.
The Rational Rose Bridge is an option that can be installed with the Workbench
e-business module.
The version of this bridge between Rational Rose and VisualAge Pacbase has
limited functionality, but it does provide the ability to populate the VisualAge
Pacbase database from a Rational Rose model. This chapter includes an
example of using the bridge between Rational Rose and VisualAge Pacbase.
The results obtained should be compared to the entities developed in the
preceding chapter.

15.1 Overview
The bridge between Rational Rose and VisualAge Pacbase is a one-way bridge
that starts at Rational Rose and ends with VisualAge Pacbase.
Modeling in Rational Rose is more or less neutral. This means that the modeler
using Rational Rose does not have to be overly concerned about the VisualAge
Pacbase concepts related to how the model will be implemented in the
repository.
The bridge uses the class diagram that results from the design activity in
Rational Rose to populate application components in the VisualAge Pacbase
repository. This combines the UML (universal modeling language) strengths of
Rational Rose with the application component management strengths of
VisualAge Pacbase.
The bridge uses the toolkit provided by Rational Rose. This is the same API as
the one used by VisualAge for Java. Using XML provides traceability for changes
to the model as it progresses from Rational Rose to VisualAge Pacbase. We use
this to track the changes between our entities in VisualAge Pacbase and the
original model in Rational Rose.
15.2 Approach
The approach to combining Rational Rose with VisualAge Pacbase proceeds in
three steps:
1. Developing the analysis model (Rational Rose)
2. Exporting the model and generating VisualAge Pacbase entities (the bridge)
3. Completing and customizing the resulting entities (VisualAge Pacbase)
15.2.1 Using Rational Rose

Developing the analysis model in Rational Rose follows the methods and
techniques of UML. The analysis activity focuses on use case descriptions. This
produces a use case diagram and a list of the use cases. The analysis produces
graphical representations of the business situation that reflect the understanding
of the modeler. These models need to be validated and confirmed by the
end-user or subject matter expert.

15.2.2 Using the bridge
Once the analysis modeling is finished, the modeler expands the activity to
include the attributes and to specify the identifiers (primary keys) of the business
objects. The bridge process begins with the export of the analysis model from
Rational Rose. The resulting file (.mdl) is processed by the bridge and produces
the application components for the VisualAge Pacbase repository. The entities
that are created include:
򐂰 Data elements, the definition
򐂰 Logical views, the definition and the list of data elements contained in the
logical view
򐂰 Folder
򐂰 Servers, generic segment calls
15.2.3 Using VisualAge Pacbase

After the entities have been imported into VisualAge Pacbase, the entities need
to be completed. For example, the data elements created have the definition but
not the description details such as labels, validation rules, and documentation to
support the generation of help information for the end-user. The VisualAge
Pacbase entities are completed by developers just as they would be during
normal VisualAge Pacbase development.
15.3 Constraints
Although the modeler using Rational Rose does not need to be thoroughly
educated in all of the concepts for VisualAge Pacbase, there are ways of working
in Rational Rose that will make the bridging between Rational Rose and
VisualAge Pacbase easier. Each class diagram implicitly represents a folder in
VisualAge Pacbase. This necessitates a set of rules to be followed when working
in Rational Rose. In addition, there are several constraints that must be followed
when using the bridge. These are discussed in this section.
15.3.1 Packages, diagrams, and folder

VisualAge Pacbase and Rational Rose unfortunately use the same terminology,
logical view, but with entirely different meanings. In Rational Rose, logical view
refers to an activity that creates a set of models. In our redbook, we use the term
Rose logical view to refer to this activity in Rational Rose. In VisualAge Pacbase,
a logical view is part of the description of a folder and is an entity managed within
the VisualAge Pacbase repository. In our redbook, we use the term logical view
without any qualifier to refer to the VisualAge Pacbase logical view.
Chapter 15. Bridging from Rational Rose 311

In Rational Rose, class diagrams are created as packages in the Rose logical
view. In Rational Rose, one package can contain multiple class diagrams,
however this should be avoided when developing class diagrams that will be
bridged to VisualAge Pacbase.
The following rules apply:

򐂰 There must not be a class diagram at the Rose logical view root.
򐂰 One package must contain one and only one class diagram.
򐂰 The package should be identified as type VAP, which will cause the Rose
bridge to exclude any other packages during processing.
These rules allow the bridge to produce one folder for each package.
15.3.2 Class diagrams

Class diagrams in Rational Rose relate directly to the folder architecture in
VisualAge Pacbase. Class diagrams are a data-oriented view and are used by
the bridge process to produce the data-related entities (data elements, logical
views) in VisualAge Pacbase.
Only one rule applies:

򐂰 Except for inheritance, do not use references to classes in other class
diagrams.
15.3.3 Classes and attributes

Regarding classes, there are officially no constraints other than those from
Rational Rose through the UML implementation.
As for attributes, the following rules apply:

򐂰 Indicate the primary key for each object using the DDL primary key field in
Rational Rose
򐂰 When no primary key is indicated, the bridge uses the first attribute in the list
as the primary key because it is invalid to specify the class without the
primary key
15.3.4 Operations
There are no constraints for operations except those imposed by the UML
implementation in Rational Rose.

15.3.5 Inheritance
During the bridging from Rational Rose to VisualAge Pacbase the inheritance will
be applied automatically using the information from the class diagram developed
during the design activity in Rational Rose.
Only attributes and operations in the class diagram are applied because the
bridge has no way of locating any other source of inheritance.
15.3.6 Relations
In general, all relations in the class diagram must be oriented. This means that
the relation must be described from the point of view of one of the objects
participating in the relationship. In order to use the bridge between Rational Rose
and VisualAge Pacbase, all relations must be oriented. This allows the bridge to
properly identify the root node of the folder. This is illustrated in Figure 15-1.
CRUISE LINE SHIP

NO
1..* 1..1
CRUISE LINE SHIP
YES
Figure 15-1 Orienting relations
15.3.7 Aggregation and references

Aggregation refers to relations that are hierarchical in nature. These can normally
be described as “A contains B” or “B is contained in A”. During the bridging
process from Rational Rose to VisualAge Pacbase, these aggregations result in
dependent nodes within the folder. In order for aggregations (hierarchical
relationships) to be properly bridged, they must conform to the cardinality in
Figure 15-2.

0..* 0..1
A B
1..* 1..1
A B
Figure 15-2 Cardinality constraints for aggregations
References refer to non-hierarchical relationships. During the bridging process,

these references result in reference nodes within the folder. Relations that are
references (non-hierarchical) must conform to the cardinalities in Figure 15-3.
0..* 0..1
A B
1..* 1..1
A B
Figure 15-3 Cardinality constraints for references
15.3.8 Associatives
Associatives result when one object (A) can be related to multiple occurrences of
another object (B), which can also be related to multiple occurrences of the other
object (A). This is referred to as a many-to-many relationship and is shown in the
top portion of the following figure. Implementing this type of relationship presents
technical difficulties in most database management systems.

In order to overcome these technical difficulties, the many-to-many relationship is
restructured by adding another object (C), which is referred to as the associative
entity. The cardinality used to relate the new object (C) to the original objects (A
and B) is changed so that the original objects (A and B) now participate in a
non-hierarchical relationship (reference) with the associative object (C). This is
seen in Figure 15-4.
0..* 0..*
A B
A B
1..1 1..1
Figure 15-4 Resolving many-to-many relations

15.3.9 Installed bridge
The bridge between Rational Rose and VisualAge Pacbase must be installed in a
Windows NT, 95, or 98 environment. The results of the installation include:
򐂰 A Rose Bridge tab in the e-business Workbench
򐂰 An icon on the tool bar for opening a rose model
򐂰 An icon on the tool bar to save the result in XML format
These are shown in Figure 14-5.
Figure 15-5 Workbench with Rose Bridge

15.4 Operating the bridge
In this section we describe the tasks you need to accomplish the bridge between
Rational Rose and VisualAge Pacbase. For our redbook effort, we created the
VisualAge Pacbase entities in the repository. Another option, would have been
for us to create a model in Rational Rose and then import and complete our
entities using the Rose Bridge process. The following discussion shows how this
alternative would look. In order to keep the resulting entities distinct from the
ones we created, we added another library in the VisualAge Pacbase database
to contain the bridged entities. This is shown in Figure 15-6.
Figure 15-6 Library to support the Rose Bridge

15.4.1 Importing the Rose model
The installation of the Rose bridge adds a tab to the e-business Workbench in
VisualAge Pacbase (Rose Bridge). Use this tab to run the import of the Rose
model file (.mdl extension). To open the .mdl file, use the toolbar icon that looks
like an open folder with the word Rose by it. Here we opened the .mdl file for our
Rose model and it was added to the display, as seen in Figure 15-7.
Figure 15-7 Opening the Rose model file

After the file loads, save the resulting XML file. This is done by using the icon on
the toolbar that looks like an open folder with the XML by it. The XML file
represents an intermediate step in importing the Rose model. Larger models
take longer to import. Saving the intermediate XML file allows you to reload the
model and reduce the amount of processing time.
Using the Rose Bridge tab, enter the normalized prefix for your components and
the libraries in the VisualAge Pacbase repository where you would like them
located. We used the settings shown in Figure 15-8.
Figure 15-8 Settings for the Rose Bridge import

15.4.2 Generating the VisualAge Pacbase entities
Run the generation of Pacbase components by clicking the icon on the toolbar
that looks like a set of gears. You can expect to see a panel open that represents
the Xo Console. These are the messages from the generation process. Close
this window. The duration of the generation depends on the size of the model.
After the generation we had the following data elements in our local workspace
as shown in Figure 15-9.
Figure 15-9 Imported data elements

We had the following logical views after the bridging process as shown in Figure
15-10.
Figure 15-10 Logical views from the bridging process

The bridging process created the following elementary components as shown in
Figure 15-11.
Figure 15-11 Elementary components from the bridging process
The resulting folders from the bridging process is seen in Figure 15-12.
Figure 15-12 Folder resulting from the bridging process

Lastly, the e-business application from the bridging process is seen in Figure
15-13.
Figure 15-13 e-business application from the bridging process
15.4.3 Completing the imported entities

Review and complete the created application components in the following order:
1. Data elements
2. Logical views
3. Elementary components
4. Folders
5. Application
For example, in Figure 15-14 you can see that the data elements created need
such things as:
򐂰 A better name
򐂰 An abstract data type
򐂰 A length for the variable field

Figure 15-14 Element detail to complete
The final step involves saving your components in the VisualAge Pacbase
repository. We recommend that you save each bridge in a separate local
workspace until your model stabilizes. When the model is stable you can then
save the components to the VisualAge Pacbase server repository.

16
Chapter 16. Completing server

development
In this chapter we show how we built the different components of our VisualAge
Pacbase e-business application. Some of these components, such as the
e-business application itself, the communication monitor, and the Destination
node and folder, have been described in Chapter 5. We also show how to
generate the proxies for use in VisualAge Java.

16.1 Logical views
We have built five logical views as described in Chapter 14. Here we show which
data elements we used in which logical view.
16.1.1 Cruise
Cruises are actually blocks of tickets for resale by VisualAge Cruise Lines.
Definition
We defined our logical view as follows:
򐂰 Code: Cruise
򐂰 Label: Cruise
򐂰 Short Code: BT05
Composition
Our composition is shown in Figure 16-1.
Figure 16-1 Composition of Cruise

16.1.2 CruiseLine
Cruise lines are the companies that provide blocks of tickets to VisualAge Cruise
Lines for resale.
Definition
򐂰 Code: CruiseLine
򐂰 Label: Cruise Line
򐂰 Short code: BT01
Composition
Figure 16-2 Composition of CruiseLine
16.1.3 Reservation
Reservation represents the purchase of one or more tickets for a cruise by the
customer.
Definition
򐂰 Code: Reservation
򐂰 Label: Reservation
Composition
Chapter 16. Completing server development 327

Figure 16-3 Composition of Reservation
16.1.4 Ship
Ships are the vessels used to carry passengers.
Definition
We defined our logical view as follows.
򐂰 Code: Ship
򐂰 Label: Ship
Composition
Figure 16-4 Composition of Ship

16.2 Elementary components
We have built an elementary component for every logical view.
16.2.1 Cruise
Here we supplement the logical view Cruise.
Definition
We defined our elementary component as follows:
򐂰 Code: Cruise
򐂰 Label: Cruise
򐂰 Short Code: EC1400
򐂰 Component Type: Hierarchical
򐂰 COBOL program ID: PGMCRU
Composition
Figure 16-5 Composition for Cruise

Our figure does not show the data element transfer. Our key field transfers were
filled as shown in Table 16-1.
Table 16-1 Key transfer Cruise

Source Target
LINEID LINEID
REGIST REGIST
CRUSID CRUSID
Our other fields (non-key) were filled in as shown in Table 16-2.
Table 16-2 Field transfer Cruise

LINEID LINEID
CRUSNM CRUSNM
DPPRID DPPRID
ARPRID ARPRID
NBAVTK NBAVTK
NBRES NBRES
FRETXT FRETXT
16.2.2 CruiseLine
Here we supplement the logical view CruiseLine.
Definition
We defined our elementary component as follows:
򐂰 Label: CruiseLine
򐂰 COBOL program ID: PGMLIN
Composition

Figure 16-6 Composition for Reservation
Our figure does not show the data element transfer. Our key filed transfers were
Table 16-3 Key transfer CruiseLIne

Source Key
LINEID LINEID
Table 16-4 Field transfer CruiseLine

Source Key
LINENM LINENM
CTRYNM CTRYNM

16.2.3 Reservation
Here we supplement the logical view Reservation.
Definition
We defined the elementary component Reservation as follows:
򐂰 COBOL program ID: PGMRES
Composition
Our composition of the elementary component Reservation is shown in Figure
16-7.
Figure 16-7 Composition for Reservation

Our figure does not show the data element transfer. Our key field transfer is filled
as shown in Table 16-5.
Table 16-5 key transfer Reservation

Source Target
RESID RESID
Table 16-6 Field transfer Reservation

Source Target
CRUSID CRUSID
NBTIK NBTIK
16.2.4 Ship
Here we supplement the logical view Ship.
Definition
We defined our elementary component Ship as follows:
Code: Ship
Label: Ship
Short Code: EC1300
Component Type: Hierarchical
COBOL program ID: PGMSHP
Type of code to generate: VisualAge COBOL
Composition

Figure 16-8 Composition for Ship
Our figure does not show the data element transfer. Our key field transfers were
Table 16-7 Key transfer Ship

Source Target
REGIST REGIST
Table 16-8 Field transfer Ship

Source Target
SHIPNM SHIPNM
FRETXT FRETXT

16.3 Folders
We have built three folders. Two of those are single node folders. The third one,
CruiseLine, is more complex. Since we described the Destinations folder in
Chapter 5 we only discuss the Reservation and CruiseLine folders here.
16.3.1 Reservation
The Reservation folder only contains the Reservation node.
Definition
We have defined the Reservation folder as follows:
򐂰 Short Code: RESERV
򐂰 e-business application short code: CruiseApplication
򐂰 COBOL program ID: RESERV
򐂰 Package code: com.cruise.reservation.proxies
Our node definition looks like Figure 16-9.
Figure 16-9 Properties for Reservation

16.3.2 CruiseLine
We built the CruiseLine folder with CruiseLine as a root node. It has two
dependent nodes, Ship and Cruise, which also dependent nodes. Cruise is also
referencing the Destination folder for the arrival and destination ports. This is
Figure 16-10 Folder composition for CruiseLine
We defined CruiseLine as follows:

򐂰 Label: CruiseLine
򐂰 Short Code: CRULIN
򐂰 e-business application short code: CruiseApplication
򐂰 COBOL program ID: CRULIN
򐂰 Type of code to generate: VisualAge Cobol
򐂰 Package code: com.cruise.cruiseline.proxies
Figure 16-11 shows our root node properties.

Figure 16-11 Properties for CruiseLine
Figure 16-12 shows the properties for the dependent node SHIP.
Figure 16-12 Properties for Ship

Figure 16-13 shows the properties for the node CRUISE which is dependent on
CRUISELINE and SHIP.
Figure 16-13 Properties for Cruise
The next node is the reference node Destination. This node is referenced for two
things, arrival ports and departure ports. The Departure reference is shown in
Figure 16-14.

Figure 16-14 Departure reference
Figure 16-15 shows the Arrival reference.

Figure 16-15 Arrival reference
16.4 Generating
There are two separate things which need to be generated from VisualAge
Pacbase 3.0, the servers and the Java Proxies. The generation of the servers is
done using the Generation Manager. Using the Generation Manager is shown in
Chapter 5.
16.4.1 Proxy generation

The proxy generation can be started from two places:

򐂰 The e-business tab
򐂰 The Folder tab
In both these tabs there is a generation button, shown in Figure 16-16.
Figure 16-16 Generate button
Clicking this button causes the Client/Server Facility-Generator appear. Here you
can select which folder or e-business application needs to be generated. The left
panel shows the composition and the right panel shows the definition of a
selected entity as shown in Figure 16-17.
Figure 16-17 Client/Server Facility-Generator

By clicking Next>> the second part of the Client/Server Facility Generator
appears as shown in Figure 16-18. Here the generation options are defined.
Figure 16-18 Generation options
By clicking the Finish button, VisualAge Pacbase 3.0 will generate the
necessary Java files. Importing these files into VisualAge Java is discussed in
the next chapter.

17
Chapter 17. Developing JavaBeans

In this chapter we describe how to develop the Model layer of the VisualAge
Cruise Lines sample application. All of the development is done in Java, using
VisualAge for Java.
This is based on the generic interfaces (BusinessObject and Command) we

introduced earlier in this redbook.

17.1 Preparing the VisualAge environment
This section provides information on the tasks we completed to prepare our
development environment:
򐂰 Creating the VisualAge for Java projects
򐂰 Creating the Java packages
򐂰 Setting the JSP version for the WTE
򐂰 Importing the VisualAge Pacbase proxies into VisualAge for Java
17.1.1 Creating the VisualAge projects

We loaded three projects in the VisualAge for Java Workbench:
򐂰 SG246201 Redbook Framework, which contains all generic classes and
interfaces we described earlier in this redbook
򐂰 VisualAge Pacbase Runtime, which contains all VisualAge Pacbase runtime
classes previously imported from the vaprun.jar file
򐂰 VisualAge Pacbase Swing, which contains all VisualAge Pacbase Swing
classes previously imported from the vapswing.jar file
We created two projects in VisualAge for Java:

򐂰 SG246201 Redbook VisualAge Cruise Lines, which contains all specific
classes (servlets and JavaBeans) we developed for the sample application
򐂰 SG246201 Redbook VisualAge Cruise Lines Proxies, which contains all proxy
classes we generated
Figure 17-1 shows the VisualAge for Java Workbench after these loads and
creations.

Figure 17-1 VisualAge for Java ready-to-use workbench
17.1.2 Creating the Java packages

In the sample application project (SG246201 Redbook VisualAge Cruise Lines)
we created four packages:
򐂰 com.ibm.redbooks.sg246201.cruiselines, which contains all the developed
classes concerning the customer activity when choosing a cruise
򐂰 com.ibm.redbooks.sg246201.destination, which contains all the developed
classes concerning the employee activity when managing destinations
򐂰 com.ibm.redbooks.sg246201.login, which contains all the developed classes
concerning the employee login
򐂰 com.ibm.redbooks.sg246201.reservation, which contains all the developed
classes concerning the customer activity when booking a cruise
Chapter 17. Developing JavaBeans 345

Figure 17-2 shows the created packages.
Figure 17-2 VisualAge Cruise Lines packages
17.1.3 WebSphere Test Environment setup

There are two steps that you need to perform to configure the WebSphere Test
Environment (WTE):
򐂰 Setting the Java classpath for WTE
򐂰 Setting the JavaServer Page (JSP) version for WTE

Setting the Java classpath
To set up the WTE Java classpath, perform these steps:
1. In the Workbench; find the IBM WebSphere Test Environment project and
select the com.ibm.servlet package. Find the SERunner class.
2. Select Run -> Check Class Path in the context menu of the SERunner class.
3. Select the Class Path tab. Click the Edit button to edit the Project Path.
Select the projects SG246201 Redbook Framework and SG246201 Redbook
VisualAge Cruise Lines. Save this setting by clicking OK.
Setting the JSP version

VisualAge for Java version 3 supports both JSP 0.91 and JSP 1.0 versions, and
defaults to JSP 0.91 for backward compatibility. To change the version of the JSP
support used by the WTE, perform these steps:
1. Open the configuration file of the default application:
<RootDirectory>\ide\project_resources\IBM WebSphere Test
Environment\hosts\default_host\default_app\servlets\default_app.webapp
where <RootDirectory> is the root directory on which VisualAge for Java was
installed (for example, d:\IBMVJava)
2. Note the JSP compiler servlet as follows:
<servlet>
<name>jsp</name>
<description>JSP support servlet</description>
<code>com.ibm.ivj.jsp.debugger.pagecompile.IBMPageCompileServlet</code>
<init-parameter>
3. Change the text for the <code> tag as follows:
<servlet>
<name>jsp</name>
<description>JSP support servlet</description>
<code>com.ibm.ivj.jsp.runtime.JspDebugServlet</code>
<init-parameter>
...

17.1.4 Importing the VisualAge Pacbase proxies
During the server-side development we generated the VisualAge Pacbase
proxies as Java files.
We then imported them into our dedicated project SG246201 Redbook

VisualAge Cruise Lines Proxies, using the menu File->Import->Directory.
Figure 17-3 shows the packages that were created during the import.
Figure 17-3 Imported packages for generated proxies

The package com.cruise.cruiseline.proxies contains the following classes:
򐂰 CruiseLineProxy, a folder proxy class (representing the CRULIN folder)
򐂰 ShipProxy, a dependent proxy class
򐂰 CruiseProxy, a dependent proxy class
򐂰 ArrivalProxy, a reference proxy class
򐂰 DepartureProxy, a reference proxy class
򐂰 All other related classes (CruiseLineData and CruiseLineSelectionCriteria
classes, for example) are also included
The package com.cruise.destination.proxies contains the single-node folder

proxy class DestinationProxy, and all related classes.
The package com.cruise.reservation.proxies contains the single-node folder

proxy class ReservationProxy, and all related classes.
17.2 Developing the business objects

This section provides information on how we developed the business objects for
the VisualAge Cruise Lines sample application. For each developed class, we
only focus on the important points.
17.2.1 Identifying the business objects

In the VisualAge Pacbase context, we use the business object as a services filter
for the services associated with the Folder proxy. The business object interface
encapsulates the Folder proxy interface, its dependent proxies interfaces, and its
reference proxies interfaces behind a single unified interface.
According to this definition, we created one BusinessObject implementor class

per generated folder proxy. We obtained the following classes:
򐂰 DestinationBusinessObject
򐂰 CruiseLineBusinessObject
򐂰 ReservationBusinessObject

17.2.2 Destination business object
The DestinationBusinessObject class follows, as shown in Figure 17-4.
Figure 17-4 DestinationBusinessObject class
This class extends the generated DestinationProxy class and implements the
BusinessObject interface.

Adding a destination
The method addDestination provides a service to create a new destination is as
follows:
public void addDestination(String destinationPortName, String
destinationCountry) throws LocalException, ServerException {
//create a new destination
detail().setPortid(getIdentifier(destinationPortName));
detail().setPortnm(destinationPortName);
detail().setCtrynm(destinationCountry);
//create the instance
createInstance();
//Update the folder (COMMIT)
updateFolder();
In the preceding figure, the process to create a new instance follows these steps:
1. Modifies locally the detail property of the proxy using the detail() method.
2. Creates locally a new instance from the modified detail property, using the
createInstance() method.
3. Sends the request for a new instance to the server, using the updateFolder()
method.
Modifying a destination
The method modifyDestination provides a service to modify a destination is as
follows:
public void modifyDestination(int destinationPortId, String
destinationPortName, String destinationCountry) throws LocalException,
ServerException {
//read the instance which port id is destinationPortId
selectionCriteria().setPortid(destinationPortId);
readInstance();
//modify the instance
detail().setPortnm(destinationPortName);
detail().setCtrynm(destinationCountry);
modifyInstance();
//update the folder (COMMIT)
updateFolder();
}

Referring to the preceding figure, the next steps describe the process to modify
an instance:
1. Fills the selection criteria to retrieve the needed instance, using the
selectionCriteria() method.
2. Reads the needed instance from the server, using the readInstance() method.
As a result, the requested instance is put in the detail property of the proxy.
3. Modifies locally this detail property, using the detail() method, and the
modifyInstance() method.
4. Sends the request for modifying the instance to the server, using the
updateFolder() method.
Getting all destinations

The method getDestinations provides a service to retrieve all destinations, sorted
by name is as follows:
public DataDescriptionVector getDestinations() throws LocalException,
ServerException {
//for local sort
setDataComparator(new DestinationDataComparator());
//select all
selectInstances();
return getRows();
}
In the preceding figure, the process to get all instances sorted is accomplished
by these steps:
1. Sets a new DataComparator class, here a DestinationDataComparator, which
is responsible for sorting the rows of the proxy.
2. Reads all requested instances, using the selectInstances() method.As a
result, the requested instances are put in the rows property of the proxy.
3. Returns the rows in a DataDescriptionVector instance, using the getRows()
method. Notice that this getRows() method is only available because our
business object inherits from the proxy. Actually, getRows() is a protected
method, the public method returning the rows is rows().

DestinationDataComparator class
The DestinationDataComparator class extends the DefaultDataComparator class
delivered with VisualAge Pacbase. It is used to locally sort a list of destinations.
Two methods are redefined. The first method redefines the inherited method, and
is called automatically by VisualAge Pacbase:
public int compare(Object daton1, Object daton2) {
return compare((DestinationData) daton1, (DestinationData) daton2);
}
It then redirects to the comparing method actually used:

private int compare(DestinationData daton1, DestinationData daton2) {
return daton1.getPortnm().compareTo(daton2.getPortnm());
}
Getting a specific destination using its unique key

The method getDestination provides a service to retrieve a specific destination
using its unique key as follows:
public DestinationData getDestination(int destinationPortId) throws
LocalException, ServerException {
//read the instance which port id is destinationPortId
selectionCriteria().setPortid(destinationPortId);
readInstance();
return detail();
}
In the preceding figure, the process to retrieve a specific instance is done by the
next steps:
1. Fills the selection criteria to retrieve the requested instance, using the
2. Reads the requested instance from the server, using the readInstance()
method. As a result, the requested instance is put in the detail property of the
proxy.
3. Returns the detail property, which is an instance of DestinationData.

17.2.3 CruiseLineBusinessObject
The CruiseLineBusinessObject class is shown in Figure 17-5.
Figure 17-5 CruiseLineBusinessObject class
This class extends the generated CruiseLineProxy class and implements the

Getting all cruise lines
The method getCruiseLines provides a service to retrieve all of the cruise lines,
sorted by name as follows:
public DataDescriptionVector getCruiseLines() throws LocalException,
ServerException {
//for local sort
setDataComparator(new CruiseLineDataComparator());
//select all
selectInstances();
return getRows();
}
We could have chosen to do a server sort, using an Extract method. In this case,
the code for the getCruises method is as follows:
public DataDescriptionVector getCruiseLines() throws LocalException,
ServerException {
//identify that no local sort will be used
setLocalSort(false);
//use the appropriate Extract method
setExtractMethodCode("SORTBYNAME");
//select all
selectInstances();
return getRows();
}
Getting all cruises for a cruise line

The method getCruises provides a service to retrieve all of the cruises that are
dependents of a specific cruise line.
It returns a vector. Each element of this vector is actually an array of

DataDescription beans. The first element of this array is an instance of
CruiseLineData, the second element of this array is an instance of ShipData, and
the third element of this array is an instance of CruiseData. This is as follows:
public Vector getCruises(int cruiseLineId) throws LocalException,
ServerException {
Vector resultVector = new Vector();
DataDescription[] dataArray = null;
//read the instance which identifier is cruiseLineId with all its children
selectionCriteria().setLineid(cruiseLineId);
readInstanceWithAllChildren();
//loop on depending ships to get all depending cruises
Enumeration venum = getShipProxy().rows().elements();
while (venum.hasMoreElements()) {
getShipProxy().getDetailFromDataDescription((ShipData)
venum.nextElement());
Enumeration venum2 = getCruiseProxy().rows().elements();

while (venum2.hasMoreElements()) {
getCruiseProxy().getDetailFromDataDescription((CruiseData)
venum2.nextElement());
dataArray = new DataDescription[3];
dataArray[0] = detail();
dataArray[1] = getShipProxy().detail();
dataArray[2] = getCruiseProxy().detail();
resultVector.addElement(dataArray);
}
}
return resultVector;
}
In the preceding coding, the process for getting all of the instances in a formatted
vector is described by the following steps:
1. Fills the selection criteria to retrieve the cruise line instance, using the
2. Reads the requested cruise line instance and all of its dependent nodes from
the server, using the readInstanceWithAllChildren() method. Note that calling
this readInstanceWithAllChildren() method does in one step the same thing s
calling the readInstance() method and then subsequently using the
readAllChildrenFromCurrentInstance() method.
3. Enumerates the rows of the first depending node (ShipProxy). For each
ShipData, positions it as the current proxy detail by using the
readDetailFromDataDescription method.
4. Next enumerates the rows of the second depending node (CruiseProxy). For
each CruiseData, positions it as the current proxy detail by using the
readDetailFromDataDescription method. It further constitutes one return
array by aggregating the current detail properties for CruiseLineProxy,
ShipProxy, and CruiseProxy and adds this array to the resulting vector.
5. Returns the resulting vector.

Getting a specific cruise
The method getCruise provides a service to retrieve a specific cruise based on
its keys as follows:
public CruiseData getCruise(int cruiseLineId, String shipRegistry, int
cruiseId) throws LocalException, ServerException {
getCruiseProxy().selectionCriteria().setLineid(cruiseLineId);
getCruiseProxy().selectionCriteria().setRegist(shipRegistry);
getCruiseProxy().selectionCriteria().setCrusid(cruiseId);
getCruiseProxy().readInstance();
loadArrivalReferenceNode();
loadDepartureReferenceNode();
return getCruiseProxy().detail();
}
In the preceding coding, we decided not to use the proxy cache. Had we used
the proxy cache, the code would look like the following:
public CruiseData getCruise(int cruiseId) throws LocalException,
ServerException {
CruiseData data = new CruiseData();
data.setCrusid(cruiseId);
getCruiseProxy().restoreSelection(data);
return getCruiseProxy().detail();
}
Also In the preceding coding, we use two private methods to load the linked
reference nodes from the server.
For example, the loadArrivalReferenceNode() shows how to load the linked

arrival destination reference in the cache and how to put the appropriate instance
in the detail property of the reference node:
private void loadArrivalReferenceNode() throws LocalException, ServerException
{
DestinationSelectionCriteriaARR selectARR =
getCruiseProxy().getArrival().selectionCriteria();
getCruiseProxy().initializeKeyUsingReference(selectARR, "ARR");
getCruiseProxy().getArrival().readInstance();
}
To access this instance that we have just loaded, we use the following method:
public DestinationDataARR getArrivalData() {
return (DestinationDataARR) getCruiseProxy().getArrival().detail();
}

17.2.4 ReservationBusinessObject
The ReservationBusinessObject class is shown in Figure 17-6.
Figure 17-6 ReservationBusinessObject class
This class extends the generated ReservationProxy class and implements the
The method addReservation provides a service to create a new reservation as

follows:
public void addReservation(int cruiseIdentifier, int numberOfTickets, int
reservationIdentifier) throws LocalException, ServerException {
//create a new reservation
detail().setCrusid(cruiseIdentifier);//cruise identifier

detail().setNbtik(numberOfTickets);//number of reserved tickets
detail().setResid(reservationIdentifier);//reservation identifier
//create the instance
createInstance();
//Update the folder (COMMIT)
updateFolder();
}
17.3 Developing commands

This section provides information on how we developed the commands for the
VisualAge Cruise Lines sample application. For each developed class, we focus
on the execute() method only.
17.3.1 Identifying the commands

The command pattern allows an object to issue requests to another object
without knowing anything about the mechanics of how the operation being
requested will be accomplished or which object will process the request.
A command object corresponds to specific business logic, such as a query or an

update.
According to this definition, we created one Command implementor class per

business service provided by our business objects. We obtained the following
classes:
򐂰 GetDestinationsCommand
򐂰 GetUniqueDestinationCommand
򐂰 ModifyDestinationCommand
򐂰 AddDestinationCommand
򐂰 GetCruiseLinesCommand
򐂰 GetCruisesCommand
򐂰 GetCruiseDetailCommand
򐂰 BookCruiseCommand

17.3.2 Destination commands
This section focuses on commands related to employee tasks when managing
destinations.
GetDestinationsCommand
The GetDestinationsCommand class is shown in Figure 17-7.
Figure 17-7 GetDestinationsCommand class

The execute() method creates a new instance of DestinationBusinessObject,
calls the getDestinations service, and returns the result in an array:
public void execute() throws CommandException {
DestinationBusinessObject destinationBO = null;
DataDescriptionVector ddv = null;
try {
destinationBO = (DestinationBusinessObject)
BusinessObjectFactory.createInstance("com.ibm.redbooks.sg246201.destination.Des
tinationBusinessObject");
ddv = destinationBO.getDestinations();
} catch (Throwable t) {
throw new CommandException(t);
}
setDestinations(toArray(ddv));
}
An implementation of the toArray method can be:

private DestinationData[] toArray(DataDescriptionVector ddv) {
int index = 0;
DestinationData[] dda = new DestinationData[ddv.size()];
Java.util.Enumeration enum = ddv.elements();
while (enum.hasMoreElements()) {
DestinationData data = (DestinationData) enum.nextElement();
dda[index] = data;
index++;
}
return dda;
}
GetUniqueDestinationCommand
The GetUniqueDestinationCommand class is shown in Figure 17-8.

Figure 17-8 GetUniqueDestinationCommand class

calls the getDestination service, and sets the destination property:
DestinationData dd = null;
try {
dd = destinationBO.getDestination(getDestinationPortId());

}
setDestination(dd);
}
ModifyDestinationCommand
The ModifyDestinationCommand class is shown in Figure 17-9.
Figure 17-9 ModifyDestinationCommand class

and calls the modifyDestination service:
try {
destinationBO.modifyDestination(getDestinationPortId(),
getDestinationPortName(), getDestinationCountry());
}
}
AddDestinationCommand
The AddDestinationCommand class is shown in Figure 17-10.

Figure 17-10 AddDestinationCommand class
In the preceding figure, we can see that input and output arguments are coded
as JavaBean properties.
The reset() method initializes the content of these properties, and the
isReadyToCallExecute() method checks that all needed properties are filled
before calling the execute() method. The same applies for all other commands,
so we will not discuss this anymore since the code is always similar.

When the phase property is not set to “one” (we will see this particular point with
the JSP and servlet implementation), the execute() method creates a new
instance of DestinationBusinessObject, and calls the addDestination service:
if (getPhase().equals("one")) {
//do nothing
} else {
//create and save the new destination
try {
destinationBO.addDestination(getDestinationPortName(),
getDestinationCountry());
}
}
}
Note: Creating a BusinessObject instance on each execution is not always a

good practice. Actually, it means that no information is persistent between two
calls. The disadvantage is that we do not use the caching facilities of the
VisualAge Pacbase proxy. The advantage, however, is that it keeps each
command call independent and unitary, which is often a good idea in an
Internet context.
17.3.3 Cruise line commands

This section focuses on commands related to customer tasks when selecting a
cruise.
GetCruiseLinesCommand
The GetCruiseLinesCommand class is shown in Figure 17-11.

Figure 17-11 GetCruiseLinesCommand class
The execute() method creates a new instance of CruiseLineBusinessObject,

calls the getCruiseLines service, and sets the cruiseLines property in an array:
CruiseLineBusinessObject cruiseLineBO = null;
DataDescriptionVector ddv = null;
try {
cruiseLineBO = (CruiseLineBusinessObject)
BusinessObjectFactory.createInstance("com.ibm.redbooks.sg246201.cruiselines.Cru
iseLineBusinessObject");
ddv = cruiseLineBO.getCruiseLines();

}
setCruiseLines(toArray(ddv));
}
GetCruisesCommand
The GetCruisesCommand class is shown in Figure 17-12.
Figure 17-12 GetCruisesCommand class

calls the getCruises service, and sets the cruises property in an array:
Vector v = null;
try {
v = cruiseLineBO.getCruises(getCruiseLineId());
}
setCruises(toArray(v));
}
The toArray method is responsible for transforming the vector, which is in fact a
vector of [CruiseLineData,ShipData,CruiseData] arrays, into a
CruiseDataDeliveryBean array:
private CruiseDataDeliveryBean[] toArray(Vector v) throws LocalException {
int index = 0;
CruiseDataDeliveryBean[] cdba = new CruiseDataDeliveryBean[v.size()];
Enumeration e = v.elements();
while (e.hasMoreElements()) {
//get one [CruiseLineData,ShipData,CruiseData] data array
DataDescription[] dataArray = (DataDescription[]) e.nextElement();
CruiseLineData cruiseLineData = (CruiseLineData) dataArray[0];
ShipData shipData = (ShipData) dataArray[1];
CruiseData cruiseData = (CruiseData) dataArray[2];
//create a new cruiseDataDeliveryBean and populates it
CruiseDataDeliveryBean cddb = new CruiseDataDeliveryBean();
//cruise line information
cddb.setCruiseLineCountry(cruiseLineData.getCtrynm());
...
//ship information
cddb.setShipRegistry(shipData.getRegist());
...
//cruise information
cddb.setId(cruiseData.getCrusid());
...
cdba[index] = cddb;
index++;
}
return cdba;
}

GetCruiseDetailCommand
The GetCruiseDetailCommand class is shown in Figure 17-13.
Figure 17-13 GetCruiseDetailCommand class

calls the getCruise service, and sets the returned cruiseData, shipData,
cruiseLineData, arrivalData, and departureData properties:
CruiseData cd = null;
ShipData sd = null;
CruiseLineData cld = null;
DestinationDataARR arrivalData = null;
DestinationDataDEP departureData = null;
try {
cd = cruiseLineBO.getCruise(getCruiseLineId(), getShipRegistry(),
getCruiseId());
sd = (ShipData) cruiseLineBO.getShipProxy().detail();
cld = (CruiseLineData) cruiseLineBO.detail();
arrivalData = cruiseLineBO.getArrivalData();
departureData = cruiseLineBO.getDepartureData();
}
setCruiseData(cd);
setShipData(sd);
setCruiseLineData(cld);
setArrivalData(arrivalData);
setDepartureData(departureData);
}
17.3.4 Reservation commands

This section focuses on commands related to customer tasks when booking a
cruise.
BookCruiseCommand
The BookCruiseCommand is shown in Figure 17-14.

Figure 17-14 BookCruiseCommand class

The execute() method creates a new instance of ReservationBusinessObject,
calls the computeIdentifier and addReservation services, and sets the returned
reservationId property:
//create and save the new reservation
ReservationBusinessObject reservationBO = null;
int reservationId = 0;
try {
reservationBO = (ReservationBusinessObject)
BusinessObjectFactory.createInstance("com.ibm.redbooks.sg246201.reservation.Res
ervationBusinessObject");
reservationId = reservationBO.computeIdentifier(getCruiseIdentifier());
reservationBO.addReservation(getCruiseIdentifier(),
getNumberOfTickets(), reservationId);
}
setReservationId(reservationId);
}

18
Chapter 18. Building JSPs and servlets

In this chapter we describe how to develop the presentation and control layers of
the VisualAge Cruise Lines sample application. Servlets and JavaBeans are
developed in Java, using VisualAge for Java. HTML pages and JavaServer
Pages are developed using WebSphere Studio.
This discussion is based on the generic classes (ControllerServlet and

DataDeliveryBean) that we introduced earlier in this book.

18.1 Preparing the WebSphere Studio environment
This section provides information on the tasks we completed to prepare our
development environment:
򐂰 Creating the WebSphere Studio project
򐂰 Setting versions for the JSP and the application server
򐂰 Creating the folders
򐂰 Customizing the stages
18.1.1 Creating the WebSphere Studio project

We created the SG246201 Redbook project, using the menu File -> New
Project.
Once the project was created, two folders named servlet and theme were
created by default. Included in the theme folder was a cascading style sheet
named Master.css. Using this cascading style sheet allows the designer to
standardize the appearance of the pages by defining HTML tags once and then
referencing the tags from the other pages.
18.1.2 Setting versions for the JSP and the application server
WebSphere Studio version 3 supports both JSP 0.91 and JSP 1.0 versions. JSP
version is set for each project.
Concerning our project, we specified the JSP 1.0 version and the AppServerV3
application server version, using the Edit -> Properties menu, as shown in
Figure 18-1.

Figure 18-1 Setting the JSP version in WebSphere Studio
Chapter 18. Building JSPs and servlets 377

18.1.3 Creating the folders
To organize our project resources into logical groupings, we defined the folder
structure shown in Figure 18-2.
Figure 18-2 Folder structure for SG246201 Redbook project
Referring to the preceding figure, we see the following:

򐂰 All HTML pages are contained in html
򐂰 All JavaServer Pages (JSPs) are located in jsp
򐂰 Two specific pages (index.html and very_simple.jsp)are placed in sample and
used to validate the communication from any Web browser
򐂰 Servlets (Java packages resulting into folder structures) are contained in
servlet
򐂰 The Master.css cascading style sheet and all of the images are located in
theme

18.1.4 Customizing the stages
WebSphere Studio allows you to set up multiple publishing stages for deploying
WebSphere Studio resources to different locations. WebSphere Studio provides
two publishing stages by default, Test and Production:
򐂰 The Test stage is configured to publish all files to the document root of the
IBM HTTP Server on the localhost.
򐂰 The Production stage should be used to publish to the WebSphere
Application Server and IBM HTTP Server, using the real TCP/IP hostname.
For our VisualAge Cruise Lines sample application we decided to add a new
stage, named WebSphere Test Environment. We used this for publishing to the
WebSphere Test Environment.
To do that, we set our WebSphere Studio project to the Publishing view by

selecting View -> Publishing. Next, we clicked the Project -> Customize
Publishing Stages menu, and then the Add button.
To configure this new stage, we selected it by selecting Project -> Publishing

Stage -> WebSphere Test Environment. For more information on this
configuration process, refer to Servlet JSP Programming with IBM WebSphere
Studio and VisualAge for Java, SG24-5755. The actual publishing paths are
listed in Table 18-1.
Table 18-1 Publishing paths for the WebSphere Test Environment

Resource type (folder name) Path
html d:\IBMVJava\ide\project_resources\IBM
WebSphere Test
Environment\hosts\default_host\default_a
pp\web
servlet d:\IBMVJava\ide\project_resources\IBM
WebSphere Test
Environment\hosts\default_host\default_a
pp\servlets

Figure 18-3 shows the resulting publishing stage, WebSphere Test Environment.
Figure 18-3 WebSphere Test Environment publishing page
18.2 Implementing HTML pages

This section briefly describes the HTML pages we developed for the VisualAge
Cruise Lines sample application. You can see how each page looks in chapter 14
of this redbook. We do not discuss the HTML source code detail, but instead we
show the WebSphere Studio relations view for each HTML page.
We developed five HTML pages.
VisualAgeCruiseLines.html is the main HTML page containing two frames (one

for the menu, one for the principal view) as shown in Figure 18-4.
Figure 18-4 VisualAgeCruiseLine HTML page

MainMenu.html is the left-side menu of the application as shown in Figure 18-5.
Figure 18-5 MainMenu HTML page
Empty.html is the welcome page as shown in Figure 18-6.
Figure 18-6 Empty HTML page
EmployeeHomePage.html contains the employee login form as shown in Figure

18-7.
Figure 18-7 EmployeeHomePage HTML page
EmployeeActions.html provides links to the other employee pages as shown in

Figure 18-8.

Figure 18-8 EmployeeActions HTML page
Every HTML page is linked to the Master.css style sheet, and references various
icons in GIF format.
18.3 Developing the JavaServer pages

This section briefly describes the JSPs we developed for the VisualAge Cruise
Lines sample application. Here too, we show the WebSphere Studio relations
view for each page, and we focus on the use of JSP tags.
18.3.1 Employee JSPs

This section provides information on the following JSPs we developed for the
employee activities:
򐂰 DestinationsCatalog.jsp
򐂰 DestinationAdding.jsp
򐂰 DestinationDetail.jsp
DestinationsCatalog.jsp
The DestinationsCatalog.jsp page displays a list of destinations. Two actions are
possible:
򐂰 Clicking a line from the display opens the appropriate destination detail page
by calling the GetUniqueDestinationServlet class.
򐂰 Clicking the Add destination button opens an empty destination page by
calling the AddDestinationServlet class.
The WebSphere Studio relations view for this page is shown in Figure 18-9.

Figure 18-9 DestinationsCatalog JSP
To display the destinations list, we use the appropriate DataDeliveryBean:

<jsp:useBean
id="destinationArrayDataDeliveryBean"
class=
"com.ibm.redbooks.sg246201.destination.DestinationArrayDataDeliveryBean"
scope="request" />
We use this DataDeliveryBean when building the list, using the jsp:repeat tag as
follows:
<TABLE border="1" width="400">
<TBODY>
<TR bgcolor="#993366">
<TH><FONT color="#FFFFFF">Port name</FONT></TH>
<TH><FONT color="#FFFFFF">Country</FONT></TH>
</TR>
<tsx:repeat index="i">
<TR>
<TD><A
href="/servlet/com.ibm.redbooks.sg246201.destination.GetUniqueDestinationServle
t?code=<%= destinationArrayDataDeliveryBean.getDestinationPortId(i) %>"><%=
destinationArrayDataDeliveryBean.getDestinationPortName(i) %></A></TD>
<TD><%= destinationArrayDataDeliveryBean.getDestinationCountry(i) %></TD>
</TR>
</tsx:repeat>
</TBODY>
</TABLE>
In the preceding code, notice that the destinationPortId attribute for each line is
used as a parameter when calling the GetUniqueDestinationServlet class.
DestinationAdding.jsp
The DestinationsAdding.jsp page displays an empty destination form. After filling
in the fields, the employee can save the new destination by clicking the Submit
button, which will call the AddDestinationServlet class.

Figure 18-10 DestinationAdding JSP
DestinationDetail.jsp
The DestinationDetail.jsp page displays the selected destination detail. The
employee can save the modified destination by clicking the Submit button, which
will call the ModifyDestinationServlet class.
Figure 18-11 DestinationDetail JSP
To display the destination detail, we use the appropriate DataDeliveryBean:

<jsp:useBean
id="destinationDataDeliveryBean"
class="com.ibm.redbooks.sg246201.destination.DestinationDataDeliveryBean"
scope="request" />
We use this DataDeliveryBean with jsp:getProperty tag when setting the existing
value for fields:
<INPUT size="20" type="text" name="DestinationCodeTextField"
value="<jsp:getProperty name="destinationDataDeliveryBean"
property="destinationPortName"/>"><BR>
<INPUT size="20" type="text" name="DestinationLabelTextField"
property="destinationCountry"/>"><BR>
<INPUT type="hidden" name="code"
property="destinationPortId"/>"><BR>
18.3.2 Customer JSPs

This section provides information on the JSPs we developed for the customer
activities:
򐂰 CustomerHomePage.jsp

򐂰 CruisesList.jsp
򐂰 CruiseDetail.jsp
򐂰 Confirmation.jsp
CustomerHomePage.JSP
The CustomerHomePage.jsp page displays the cruise lines list. The customer
can select one cruise line by clicking it, which will call the GetCruisesServlet
class.
WebSphere Studio relations view for this page is shown in Figure 18-12.
Figure 18-12 CustomerHomePage JSP
To display the cruise lines list, we use the appropriate DataDeliveryBean:

<jsp:useBean
id="cruiseLineArrayDataDeliveryBean"
class=
"com.ibm.redbooks.sg246201.cruiselines.CruiseLineArrayDataDeliveryBean"
scope="request" />
We use this DataDeliveryBean when building the list, using the jsp:repeat tag, in
the same way that we did for the destinations list.
CruisesList.JSP
The CruisesList.jsp page displays the cruises list. The customer can select one
cruise by clicking it, which will call the GetCruiseDetailServlet class.
Figure 18-13 CruisesList JSP

Just as we did for the cruise lines list, we use the appropriate DataDeliveryBean
(CruiseArrayDataDeliveryBean) and a jsp:repeat tag to display the cruise lines
list.
CruiseDetail.JSP
The CruiseDetail.jsp page displays the selected cruise detail. The customer can
choose the number of tickets and click the Purchase button, which will call the
BookCruiseServlet class.
Figure 18-14 CruiseDetail JSP
To display the cruise detail, we use the appropriate DataDeliveryBean:

<jsp:useBean
id="cruiseDataDeliveryBean"
class="com.ibm.redbooks.sg246201.cruiselines.CruiseDataDeliveryBean"
scope="session" />
We use this DataDeliveryBean with jsp:getProperty tag when setting the existing
value for fields.
Notice here that we use the session scope for the DataDeliveryBean, instead of
request scope. We reuse it in the next section.
Confirmation.JSP
The Confirmation.jsp page displays the reservation identifier and confirms the
cruise detail.
Figure 18-15 Confirmation JSP
To display the cruise detail, we use the same DataDeliveryBean as before:

<jsp:useBean
id="cruiseDataDeliveryBean"
scope="session" />
To display the reservation identifier, we use another DataDeliveryBean:
<jsp:useBean
id="reservationDataDeliveryBean"
class="com.ibm.redbooks.sg246201.reservation.ReservationDataDeliveryBean"
scope="request" />
We use both of these DataDeliveryBeans with jsp:getProperty tag when setting

the existing value for fields.
18.3.3 CommandException.JSP
CommandException.jsp is a simple error page for reporting application errors,
and more precisely the command exceptions.
Figure 18-16 CommandException JSP
An example of source code for this JSP follows:

<HTML>
<HEAD>
<TITLE>Command Exception</TITLE>
</HEAD>
<jsp:useBean id="commandException"
class="com.ibm.redbooks.sg246201.framework.command.CommandException"
scope="request" />
<BODY BGCOLOR="#FFFFFF">
<H1> <%= commandException.getClass().getName() %> </H1>
<H4>An error has occured while processing request: <%=
HttpUtils.getRequestURL(request) %></H4>
<B>Message: </B><%= commandException.getMessage() %><BR>
<B>Details: </B><%= commandException.getDetailMessage() %>
</BODY>
</HTML>

18.4 Developing the DataDeliveryBeans
This section provides information on how we developed the DataDeliveryBeans
for the VisualAge Cruise Lines sample application.
18.4.1 Identifying the DataDeliveryBeans

DataDeliveryBeans provide the dynamic content for JSPs that produce output.
DataDeliveryBeans function under the control of a servlet, which instructs each
DataDeliveryBean as to what data is needed and how that data is to be
delivered.
Obviously, the identification of the DataDeliveryBeans needed is determined by

the presentation layer: DataDeliveryBeans result from analysis of the JSPs.
There are two types of DataDeliveryBeans:

Unitary DataDeliveryBeans, which provide data for one instance
Array DataDeliveryBeans, which provide data for a list of instances
For our VisualAge Cruise Lines sample application, we needed the following
Unitary DataDeliveryBeans:
򐂰 CruiseDataDeliveryBean
򐂰 ReservationDataDeliveryBean
򐂰 DestinationDataDeliveryBean
For our VisualAge Cruise Lines sample application, we needed the following
Array DataDeliveryBeans:
򐂰 CruiseLinesArrayDeliveryBean
򐂰 CruisesArrayDeliveryBean
򐂰 DestinationsArrayDataDeliveryBean
18.4.2 Destination DataDeliveryBeans

This section focuses on DataDeliveryBeans related to employee tasks when
managing destinations.
DestinationArrayDataDeliveryBean
The DestinationArrayDataDeliveryBean class inherits from the
DataDeliveryBean class and provides data for displaying the list of destinations.
For each indexed destination, it provides the following services:
򐂰 public String getDestinationCountry(int index)
򐂰 public int getDestinationPortId(int index)
򐂰 public String getDestinationPortName(int index)

All of these services are coded in the same way. For example, the
getDestinationPortName implementation follows:
public String getDestinationPortName(int index) {
if (getDestinationDataArray() == null)
throw new ArrayIndexOutOfBoundsException(); //to provoke end of repeat
tag in JSP
return ((DestinationData) getDestinationDataArray()[index]).getPortnm();
}
In our VisualAge Cruise Lines sample application, the

DestinationArrayDataDeliveryBean class is populated by the
GetDestinationsServlet class and is used by the DestinationsCatalog.jsp page.
DestinationDataDeliveryBean
The DestinationDataDeliveryBean class inherits from the DataDeliveryBean
class and provides data for displaying a specific destination. It provides the
following properties as shown in Figure 18-17.
Figure 18-17 DestinationDeliveryBean properties

DestinationDataDeliveryBean class is populated by the
GetUniqueDestinationServlet class and is used by the DestinationDetail.jsp
page.
18.4.3 Cruise line DataDeliveryBeans

This section focuses on DataDeliveryBeans related to customer tasks when
selecting a cruise.
CruiseArrayDataDeliveryBean
The CruiseArrayDataDeliveryBean class inherits from the DataDeliveryBean
class and provides data for displaying the list of cruises. For each indexed cruise,
it provides the following services:
򐂰 public int getCruiseId(int index)
򐂰 public int getCruiseLineId(int index)

򐂰 public String getCruiseLineName(int index)
򐂰 public String getCruiseName(int index)
򐂰 public String getShipName(int index)
򐂰 public String getShipRegistry(int index)
All of these services are coded in the same way. For example, the
getShipRegistry implementation follows:
public String getShipRegistry(int index) {
if (getCruiseDataDeliveryBeanArray() == null)
throw new ArrayIndexOutOfBoundsException(); //to provoke end of repeat
tag in JSP
return ((CruiseDataDeliveryBean)
getCruiseDataDeliveryBeanArray()[index]).getShipRegistry();
}

CruiseArrayDataDeliveryBean class is populated by the GetCruisesServlet class
and is used by the CruisesList.jsp page.
CruiseDataDeliveryBean
The CruiseDataDeliveryBean class inherits from the DataDeliveryBean class
and provides data for displaying a specific cruise. It provides the following
properties as shown in Figure 18-18.
Figure 18-18 CruiseDataDeliveryBean properties

In our VisualAge Cruise Lines sample application, the CruiseDataDeliveryBean
class is populated by the GetCruiseDetailServlet class and is used by both the
CruiseDetail.jsp and Confirmation.jsp pages.
CruiseLineArrayDataDeliveryBean
The CruiseLineArrayDataDeliveryBean class inherits from the DataDeliveryBean
class and provides data for displaying the list of cruise lines. For each indexed
cruise line, it provides the following services:
򐂰 public int getCruiseLineId(int index)
򐂰 public String getCruiseLineName(int index)

CruiseLineArrayDataDeliveryBean class is populated by the
GetCruiseLinesServlet class and is used by the CustomerHomePage.jsp page.
18.4.4 Reservation DataDeliveryBeans

This section focuses on DataDeliveryBeans related to customer tasks when
booking a cruise.
ReservationDataDeliveryBean
The ReservationDataDeliveryBean class inherits from the DataDeliveryBean
class and provides data for displaying a specific reservation. It provides the
following properties as shown in Figure 18-19.
Figure 18-19 ReservationDataDeliveryBean properties

ReservationDataDeliveryBean class is populated by the BookCruiseServlet class
and is used by the Confirmation.jsp page.

18.5 Developing the servlets
This section provides information on how we developed the controller servlets for
the VisualAge Cruise Lines sample application.
18.5.1 Identifying the servlets

A controller servlet manages the navigation for the specific business logic, and is
linked to one and only one command.
Implementing the navigation consists of:

򐂰 Constructing DataDeliveryBeans consistent with the presentation
򐂰 Managing the JSP, which handles the output to the browser
According to this definition, we created one ControllerServlet subclass per

Command implementor class developed in the preceding chapter. We obtained
the following classes:
򐂰 AddDestinationServlet
򐂰 GetDestinationsServlet
򐂰 GetUniqueDestinationServlet
򐂰 ModifyDestinationServlet
򐂰 GetCruiseLinesServlet
򐂰 GetCruisesServlet
򐂰 GetCruiseDetailServlet
򐂰 BookCruiseServlet

18.5.2 Destination servlets
This section focuses on servlets related to employee tasks when managing
destinations.
GetDestinationsServlet
The GetDestinationsServlet class is shown in Figure 18-20.
Figure 18-20 GetDestinationsServlet class
In the preceding figure, the getCommandClassName method explicitly identifies

the command class to be executed:
protected String getCommandClassName() {
return "com.ibm.redbooks.sg246201.destination.GetDestinationsCommand";
}

The performTask method executes the command, populates the appropriate
DataDeliveryBean, puts it in the request, and forwards the request to the
DestinationCatalog JSP as follows:
public void performTask(HttpServletRequest req, HttpServletResponse res) {
//execute the command
executeCommand();
//populates the dataDeliveryBean
DestinationArrayDataDeliveryBean dadd = new
DestinationArrayDataDeliveryBean();
dadd.setDestinationDataArray(((GetDestinationsCommand)
getCommand()).getDestinations());
//put this DataDeliveryBean in the scope of the request
req.setAttribute("destinationArrayDataDeliveryBean", dadd);
//forward the request to the next JSP
try {
getServletContext().getRequestDispatcher("/jsp/DestinationsCatalog.jsp").forwar
d(req, res);
} catch (IOException ioe) {
handleException(ioe);
} catch (ServletException se) {
handleException(se);
}
}
Note: In the preceding code, we explictly referenced some servlet and/or JSP
names. Please note that we did this in order to present more readable source
code for this redbook. Explicit references are not the recommended practice.
Instead, you should use static methods or variables to centralize such
hard-coded information, and eventually externalize it.

AddDestinationServlet
The AddDestinationServlet class is shown in Figure 18-21.
Figure 18-21 AddDestinationServlet class

return "com.ibm.redbooks.sg246201.destination.AddDestinationCommand";
}
The performTask method first checks the phase. In phase “one”, it executes the
command to create an empty destination, and then forwards the request to the
DestinationAdding JSP as follows:

//get the request parameters
String phase = (String) req.getParameter("phase");
//reset the command
getCommand().reset();
((AddDestinationCommand) getCommand()).setPhase(phase);
//perform the appropriate task
if (phase.equals("one")) {
//create a new empty destination
executeCommand();
DestinationDataDeliveryBean ddd = new DestinationDataDeliveryBean();
req.setAttribute("destinationDataDeliveryBean", ddd);
try {
getServletContext().getRequestDispatcher("/jsp/DestinationAdding.jsp").forward(
req, res);
}
In phase “two”, it populates the command, executes it to create the new

destination, populates the appropriate DataDeliveryBean, and forwards the
request to the GetDestinationsServlet as follows:
} else {
//create and save the new destination
//get the request parameters
String destinationPortName = (String)
req.getParameter("DestinationCodeTextField");
String destinationCountry = (String)
req.getParameter("DestinationLabelTextField");
//populates the command
((AddDestinationCommand)
getCommand()).setDestinationPortName(destinationPortName);
((AddDestinationCommand)
getCommand()).setDestinationCountry(destinationCountry);
executeCommand();
//forward to the GetDestinationsServlet
try {
getServletContext().getRequestDispatcher("/servlet/com.ibm.redbooks.sg246201.de
stination.GetDestinationsServlet").forward(req, res);

}
}
}
18.5.3 GetUniqueDestinationServlet
The GetUniqueDestinationServlet class is shown in Figure 18-22.
Figure 18-22 GetUniqueDestinationServlet class

return "com.ibm.redbooks.sg246201.destination.GetUniqueDestinationCommand";
}

The performTask method populates the command, executes it, populates the
appropriate DataDeliveryBean, puts it in the request, and forwards the request to
the DestinationDetail JSP as follows:
//retrieve the code parameter if any
String code = (String) req.getParameter("code");
int identifier = Integer.parseInt(code);
//reset and populate the command
((GetUniqueDestinationCommand)
getCommand()).setDestinationPortId(identifier);
executeCommand();
DestinationData dd = ((GetUniqueDestinationCommand)
getCommand()).getDestination();
DestinationDataDeliveryBean ddd = new DestinationDataDeliveryBean();
ddd.setDestinationPortId(dd.getPortid());
ddd.setDestinationPortName(dd.getPortnm());
ddd.setDestinationCountry(dd.getCtrynm());
//put this DataDeliveryBean in the scope of the session
req.setAttribute("destinationDataDeliveryBean", ddd);
try {
getServletContext().getRequestDispatcher("/jsp/DestinationDetail.jsp").forward(
req, res);
}
ModifyDestinationServlet
The ModifyDestinationServlet classis shown in Figure 18-23.

Figure 18-23 ModifyDestinationServlet class

return "com.ibm.redbooks.sg246201.destination.ModifyDestinationCommand";
}
appropriate DataDeliveryBean, and forwards the request to the
GetDestinationsServlet.
This code is not displayed here because it is always the same.

18.5.4 Cruise line servlets
This section focuses on servlets related to customer tasks when selecting a
cruise.
GetCruiseLinesServlet
The GetCruiseLinesServlet class is shown in Figure 18-24.
Figure 18-24 GetCruiseLinesServlet class

return "com.ibm.redbooks.sg246201.cruiselines.GetCruiseLinesCommand";
}

The performTask method executes the command, populates the appropriate
DataDeliveryBean, puts it in the request, and forwards the request to the
CustomerHomePage JSP.
Figure 18-25 summarizes the flow for this first step of the customer activity.
CruiseLines
BusinessObject
HTML
Main Menu
GetCruiseLines GetCruiseLines
Servlet Command
JSP CruiseLinesArray
Customer
DataDeliveryBean
Home Page
Figure 18-25 Putting it all together: GetCruiseLinesServlet
GetCruisesServlet
The GetCruisesServlet class is shown in Figure 18-26.

Figure 18-26 GetCruisesServlet class

return "com.ibm.redbooks.sg246201.cruiselines.GetCruisesCommand";
}
the CruisesList JSP.

Figure 18-27 describes the flow for this second step of the customer activity.
Reservation
BusinessObject
JSP
Cruise Detail
BookCruise BookCruise
Servlet Command
JSP Reservation
Confirmation DataDeliveryBean
Cruise
DataDeliveryBean
Figure 18-27 Putting it all together: GetCruiseServlet

GetCruiseDetailServlet
The GetCruiseDetailServlet class is shown in Figure 18-28.
Figure 18-28 GetCruiseDetailServlet class

return "com.ibm.redbooks.sg246201.cruiselines.GetCruiseDetailCommand";
}
appropriate DataDeliveryBean, puts it in the session, and forwards the request to
the CruiseDetail JSP.

Figure 18-29 summarizes the flow for this third step of the customer activity.
Reservation
BusinessObject
JSP
Cruise Detail
Servlet Command
JSP Reservation
Cruise
DataDeliveryBean
Figure 18-29 Putting it all together: GetCruiseDetailServlet

18.5.5 Reservation servlets
This section focuses on servlets related to customer tasks when booking a
cruise.
BookCruiseServlet
The BookCruiseServlet class is shown in Figure 18-30.
Figure 18-30 BookCruiseServlet class

return "com.ibm.redbooks.sg246201.reservation.BookCruiseCommand";
}

the Confirmation JSP as follows:
//reset the command
//get the request and session parameters
HttpSession session = req.getSession(false);
int cruiseIdentifier = ((CruiseDataDeliveryBean)
session.getValue("cruiseDataDeliveryBean")).getId();
int numberOfTickets =
Integer.parseInt(req.getParameter("NumberTicketsToPurchaseDDL"));
((BookCruiseCommand) getCommand()).setCruiseIdentifier(cruiseIdentifier);
((BookCruiseCommand) getCommand()).setNumberOfTickets(numberOfTickets);
executeCommand();
ReservationDataDeliveryBean rddb = new ReservationDataDeliveryBean();
rddb.setReservationId(((BookCruiseCommand)
getCommand()).getReservationId());
rddb.setNumberOfTickets(((BookCruiseCommand)
getCommand()).getNumberOfTickets());
//and remember that the CruiseDataDeliveryBean is already in the session
request.setAttribute("reservationDataDeliveryBean", rddb);
//forward to the Confirmation JSP
try {
getServletContext().getRequestDispatcher("/jsp/Confirmation.jsp").forward(req,
res);
}
}

Figure 18-31 summarizes the flow for this fourth step of the customer activity.
Reservation
BusinessObject
JSP
Cruise Detail
Servlet Command
JSP Reservation
Cruise
DataDeliveryBean
Figure 18-31 Putting it all together: BookCruiseServlet
18.6 Introducing the WAP application

WAP means Wireless Application Protocol. It refers to the use of remote devices
to interactively access the Internet.
This section discusses the changes we made to our sample application to make
it WAP-compliant.
The main point to remember is that to make your application WAP-compliant you
have nothing to change regarding the Model layer. The commands, business
objects, proxies, and servers are the same, only the presentation differs.
As a result, making your application WAP-compliant consists of:

򐂰 Adapting your presentation to WAP by developing new WML pages and WML
JSPs, while reusing the DataDeliveryBeans
򐂰 Adapting your controllers by subclassing servlets

18.6.1 Adapting the presentation to the WAP
Adapting the presentation to WAP is basically a change from HTML to WML.
One thing to keep in mind is that the nature of the WAP presentation is textual
rather than the familiar mix of graphics and text that makes up most Web pages.
Because the WAP presentation is limited, you must be concise and to the point
when communicating through the WAP interface. This can easily be seen by
comparing the VisualAge Cruise Lines sample application (WAP) presented in
this chapter with the example pages supplied in chapter 14 of this redbook.
The following code was used to produce the WML homepage for VisualAge
Cruise LInes sample application (WAP) as follows:
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.wapforum.org/DTD/wml_1.1.xml">
<wml>
<head><meta http-equiv="Cache-Control" content="max-age=30"
forua="true"/></head>
<card id="VCLHomePage" title="VCL">
<p>Welcome to the VisualAge Cruise Lines WAP site<br/>
</p>
<p><a
href="/servlet/com.ibm.redbooks.sg246201.cruiselines.wap.GetCruiseLinesServlet"
>Customer Area</a>
</p>
<do type="prev" label="Back"><prev/></do>
</card>
</wml>
18.6.2 Developing the WML-based JSPs

This section briefly describes the WML-based JSPs we developed for the
VisualAge Cruise Lines sample application:
򐂰 WapCustomerHomePage.jsp
򐂰 WapCruisesList.jsp
򐂰 WapCruiseDetail.jsp
򐂰 WapConfirmation.jsp
WML-based JSPs means that we use WML tags and JSP tags. On each JSP, we
have to specify the content type, adding the following directive tag:
<%@ page language="Java" contentType="text/vnd.wap.wml" %>
WapCustomerHomePage.jsp
The following code was used to produce the customer homepage for VisualAge
Cruise LInes sample application (WAP) as follows:

<wml>
<head><meta http-equiv="Cache-Control" content="max-age=30" forua="true"
/></head>
<jsp:useBean id="cruiseLineArrayDataDeliveryBean"
class="com.ibm.redbooks.sg246201.cruiselines.CruiseLineArrayDataDeliveryBean"
scope="request" />
<card id="CustomerArea" title="Customer Area">
<p>Only our discount cruises are available from the WAP site.<br/>
For more cruises, please refer to the Web site.<br/>
</p>
<p><a
href="/servlet/com.ibm.redbooks.sg246201.cruiselines.wap.GetCruisesServlet?code
=<%= cruiseLineArrayDataDeliveryBean.getCruiseLineId(i) %>"><%=
cruiseLineArrayDataDeliveryBean.getCruiseLineName(i) %></a></p>
</tsx:repeat>
</card>
</wml>
The homepage for VisualAge Cruise Lines (WAP) is shown in Figure 18-32.
Figure 18-32 VisualAge Cruise Lines WAP homepage
WapCruisesList.jsp
The code for the display of the cruises list follows:
<wml>
/></head>
<jsp:useBean id="cruiseArrayDataDeliveryBean"
class="com.ibm.redbooks.sg246201.cruiselines.CruiseArrayDataDeliveryBean"

scope="request" />
<card id="CruisesList" title="Cruises List">
<p>Here are the current discounts:<br/>
</p>
<p><a
href="/servlet/com.ibm.redbooks.sg246201.cruiselines.wap.GetCruiseDetailServlet
?cruiseline=<%= cruiseArrayDataDeliveryBean.getCruiseLineId(i) %>&ship=<%=
cruiseArrayDataDeliveryBean.getShipRegistry(i) %>&cruise=<%=
cruiseArrayDataDeliveryBean.getCruiseId(i) %>"><%=
cruiseArrayDataDeliveryBean.getCruiseName(i) %></a></p>
</tsx:repeat>
</card>
</wml>
From the homepage, customers can proceed to a page where they can enter
they can select all cruise lines or a specific cruise line. This is shown in Figure
18-33.
Figure 18-33 Cruise line selection through WAP
WapCruiseDetail.jsp
Detailed information about the cruise is built and presented with the following
code as follows:
<wml>
/></head>
<jsp:useBean id="cruiseDataDeliveryBean"
scope="session" />
<card id="CruiseDetail" title="Cruise Detail">

<p align="left">
Cruise line name: <jsp:getProperty name="cruiseDataDeliveryBean"
property="cruiseLineName"/><br/>
Cruise name: <jsp:getProperty name="cruiseDataDeliveryBean"
property="name"/><br/>
Ship name: <jsp:getProperty name="cruiseDataDeliveryBean"
property="shipName"/><br/>
Ship registry: <jsp:getProperty name="cruiseDataDeliveryBean"
property="shipRegistry"/><br/>
Departure: <jsp:getProperty name="cruiseDataDeliveryBean"
property="departurePortName"/><br/>
Arrival: <jsp:getProperty name="cruiseDataDeliveryBean"
property="arrivalPortName"/><br/>
</p>
<do type="accept" label="Reserve cruise">
<go
href="/servlet/com.ibm.redbooks.sg246201.reservation.wap.BookCruiseServlet"/>
</do>
</card>
</wml>
This results in Figure 18-34 which shows the display of the cruises detail.
Figure 18-34 Cruise detail through WAP
WapConfirmation.jsp
Detailed information about the confirmation is built and presented with the
following code as follows:
?xml version="1.0"?>

<wml>
/></head>
<jsp:useBean id="reservationDataDeliveryBean"
class="com.ibm.redbooks.sg246201.reservation.ReservationDataDeliveryBean"
scope="request" />
<card id="ReservationOK" title="Reservation is done">
<p align="left">
Congratulations ! You will receive a complete reservation form by
mail.<br/>
Your reservation identifier is: <jsp:getProperty
name="reservationDataDeliveryBean" property="reservationId"/>
</p>
</card>
</wml>
This results in Figure 18-35 which shows the display of the cruises detail.
Figure 18-35 Purchase confirmation through WAP
18.6.3 Subclassing the servlets

When adapting from HTML to WML, the changes for the controller servlet are
basically related to the navigation.
There is a way to determine whether your client request is WAP or HTTP.

However, you should not try to adapt your controller servlets directly. A good
practice is to subclass the existing controller servlets and to redefine only the
performTask method, which is the unique method dedicated to control and
navigation.
We decided to create two new packages dedicated to WAP servlets:

򐂰 com.ibm.redbooks.sg246201.cruiselines.wap
򐂰 com.ibm.redbooks.sg246201.reservation.wap

If you take a look at the performTask method for the WAP BookCruiseServlet,
you will notice that it has been simplified a lot to display only the needed
information. However, the general behavior of this performTask method is similar
to the inherited one:
1. Resets the command.
2. Gets parameters from the session.
3. Populates the command.
4. Executes the command.
5. Populates the DataDeliveryBean.
6. Puts the DataDeliveryBean into the HTTP request or session.
7. Calls the appropriate WML JSP.
How we redefined this performTask method for the WAP BookCruiseServlet

follows:
//reset the command
//get the request and session parameters
HttpSession session = req.getSession(false);
int cruiseIdentifier = ((CruiseDataDeliveryBean)
session.getValue("cruiseDataDeliveryBean")).getId();
int numberOfTickets = 1; //hard-coded in WAP version
((BookCruiseCommand) getCommand()).setCruiseIdentifier(cruiseIdentifier);
((BookCruiseCommand) getCommand()).setNumberOfTickets(numberOfTickets);
executeCommand();
ReservationDataDeliveryBean rddb = new ReservationDataDeliveryBean();
rddb.setReservationId(((BookCruiseCommand)
getCommand()).getReservationId());
rddb.setNumberOfTickets(((BookCruiseCommand)
getCommand()).getNumberOfTickets());
req.setAttribute("reservationDataDeliveryBean", rddb);
//formard to the Confirmation JSP
try {
getServletContext().getRequestDispatcher("/wml/WapConfirmation.jsp").forward(re
q, res);
}
}

Note: Using the session for persistency is useful, but it is not always a good
practice when developing a WAP site. Actually, when deploying a WAP site,
you will have to deploy a WAP gateway between your WAP browser and your
HTTP server. As a result, the HTTP server will in most cases see the WAP
gateway as a unique HTTP client. This means that the session will be shared
between all WAP browsers, which is not what we want. New WAP gateways
are providing real HTTP session support, but if the one you deploy does not
support this, you will have to use a URL rewriting technique for persistency.
This can be done in the performTask method.
18.6.4 Testing with the WAP application

The real testing environment would use a WAP device (with a WAP browser), a
WAP gateway, and WebSphere Test Environment (WTE) as a simulated Web
application server.
Fortunately, on the Internet you can find free limited versions of software that
simulates a WAP browser without needing a WAP gateway. These products
interact with an HTTP server, assuming that the return (HTTP response) will be
WML-compliant.
To make WTE handle WML-based pages, you have to configure the

default.servlet_engine file, adding some new acceptable MIME types .
You can find this file in the directory:

<RootDirectory>\ide\project_resources\IBM WebSphere Test Environment
where <RootDirectory> is the directory where VisualAge for Java were installed
(d:\IBMVJava, for example)
The code to add to this file follows:

<mime type="text/vnd.wap.wml">
<ext>wml</ext>
<ext>WML</ext>
</mime>
<mime type="text/vnd.wap.wbmp">
<ext>wbmp</ext>
<ext>WBMP</ext>
</mime>
All JSPs must be suffixed with .jsp, to make sure that WTE will compile them. On
each WML-based JSP, you have to specify the content type, adding the following
directive tag:

19
Chapter 19. Deploying the application

In this chapter we discuss the deployment of the sample application. This
discussion roughly follows our model-view-controller architecture.
Recall from our earlier discussion the fundamentals of the model-view-controller

framework:
򐂰 The model is responsible for the underlying data, and for managing any
transactions that are associated with it. This is the business logic.
򐂰 The view is responsible for displaying the data. This is the presentation logic.
򐂰 The controller is responsible for decoupling the interactions between the
model and the view. The controller manages the end-user interactions and
calls the appropriate business logic to complete the functional request. This
allows the model to be reused with different views.
In addition, this chapter covers the additional technical aspects needed to

complete the e-business application.

19.1 Deploying the VisualAge Cruise Lines Application
Deploying our VisualAge Cruise Lines sample application is basically creating
and configuring a specific Web application for all the servlets and JSPs that have
to work together.
In WebSphere Application server terminology, a Web application represents a

grouping of servlets, JSPs, and their related resources. Managing these
elements as a unit allows you to start and stop servlets in a single step.
Concerning the WebSphere terminology and the deployment process, you will
find more detail in Servlet and JSP Programming with IBM WebSphere Studio
and VisualAge for Java, SG24-5755.
19.1.1 Creating the VisualAge Cruise Lines Web application

Creating the VisualAge Cruise Lines Web application is done through the
WebSphere Administrative Console.
The WebSphere Administrative Console is a graphical administrative client that

enables you to access and make changes to resources in the domain.
Starting the Administrative Console

To start the WebSphere Administrative Console, you first have to check if the
WebSphere administrative Server is successfully started. You can do this
through the Control Panel - > Services window as shown in Figure 19-1.

Figure 19-1 Starting WebSphere Application Server as a service
If the WebSphere administrative Server status shows that it is started, you can
start the Administrative Console from the Start menu by selecting the
Administrator’s Console in the IBM WebSphere -> Application Server 3.0
folder.
Using the Task Wizard

Tasks wizards can be found by selecting the Task tab in the Administrative
Console. Select the Configure a Web application wizard, and click the green
Start Task button. The wizard appears and prompts you for the name of the new
Web application, vcl for example, and the level of JSP support as shown in
Figure 19-2.
Chapter 19. Deploying the application 419

Figure 19-2 Configuring the Web application: name, servlets, JSP support
Click Next and you are prompted to select the servlet engine as shown in Figure
19-3.
Figure 19-3 Configuring the Web application: servlet engine

The next step prompts you for the virtual host and the Web application Web path.
We selected the default virtual host (default_host), and we set up the Web path
as /vcl. This is shown in Figure 19-4.
Figure 19-4 Configuring the Web application: virtual host and Web path
The last step prompts you for the document root and the classpath (for servlets)
of the Web application. The directories that are proposed are based on the Web
path specified in the previous step as shown in Figure 19-5.
Figure 19-5 Configuring the Web application: document root and class path

These directories are not automatically created for you (see next section). Leave
the proposed values and click Finished. Check for the message pane for a
confirmation: Command “WebApplication.create” completed successfully.
19.1.2 Creating the required Web application directories

Beneath the WebSphere/AppServer/hosts/default_host directory you will find a
directory for each of the Web applications that are part of the default_host. For
each Web application directory, you normally have a servlets directory for the
classpath and a web directory for the document root.
Figure 19-6 shows the directories we created for our new Web application vcl.
Figure 19-6 Web application director structure
In the preceding figure, you can see the following objects:

򐂰 AppServer is the directory for our WebSphere Application Server.
򐂰 default_host is the directory for our virtual host.
򐂰 vcl is the directory for our Web application.
򐂰 servlets is the directory were we deploy our servlets and JavaBeans.
򐂰 web is the directory where we deploy our HTML pages, JSPs, and images.

19.1.3 Deploying files to WAS
This section briefly describes the deployment we did for our VisualAge Cruise
Lines sample application.
Deploying files can be done manually by using the Windows NT Explorer, or

automatically by using the exporting and publishing facilities from WebSphere
Studio and VisualAge for Java. These techniques are fully described in the
SG24-5755 book.
Deploying the view layer

Deploying the view layer means deploying the HTML pages, WML pages, JSPs
and related files (images, for example) under the Web application document root.
A good way to do that is by using the publishing facility from WebSphere Studio.
Figure 19-7 shows the directory structure after deploying the view.
Figure 19-7 View layer directory structure
Deploying the model and the controller layers

Deploying the model and controller layers means deploying the Java files for
servlets, JavaBeans, and proxies. A good way to do that is to export these files in
a JAR format from VisualAge for Java:
򐂰 vclfmk.jar contains all Java classes constituting our development framework.
򐂰 vclapp.jar contains all Java classes constituting our VisualAge Cruise Lines
application.
򐂰 vclproxies.jar contains all generated Java proxies.
Figure 19-8 shows the resulting directory.
Figure 19-8 Controller and Model layers directory structure

Changing the Web application classpath
The preceding JAR files have to be added to the Web application classpath. On
the Administrative Console, choose the Topology tab, then select your Web
application, and choose the Advanced tab. You can then customize the
classpath, as shown in Figure 19-8.
Figure 19-9 Updating the Web application classpath
Changing the application server classpath

Since generated proxies are based on generic classes, we want to add these
VisualAge Pacbase generic classes to the application server classpath. Actually,
we want to add the two packages we installed in chapter 4:
򐂰 vaprun.jar, which contains all generic runtime classes for VisualAge Pacbase
򐂰 vapswing.jar, which contains all JDK1.1 Swing classes for VisualAge
Pacbase
To do this, we set up a command-line argument:

-classpath d:\a\RedbookVapb\vaprun.jar;d:\a\RedbookVapb\vapswing.jar
This is shown in Figure 19-10.

Figure 19-10 Updating the application server classpath
You must restart the application server, which adds the additional directories and
jar files to the system class loader classpath.
19.1.4 Starting the Web application

If the application server is already running, you can start your new Web
application from the Administrative Console. Right-click the Web application and
select Restart Web App. The Web application is also started when the
application server is started or restarted.
For our VisualAge Cruise Lines Web application we selected the default
virtual_host, and set up the Web path as /vcl. Therefore, the URL for testing our
application will be:
http://<IP address>/vcl/html/VisualAgeCruiseLines.html
The URL for accessing a servlet will be:

http://<IP address>/vcl/servlet/...servlet name...
When testing our application with WebSphere Test Environment (WTE), we

deployed our files to default_app Web application. As a result, we need to apply
changes to adapt them to vcl Web application. Make sure that all your calls to
servlets are preceded by:
/vcl/...
Note: To avoid changing all servlet calls when deploying into a different
directory structure, we recommend that you externalize explicit references to
servlets and/or JSPs.

19.1.5 Defining servlets
We set up the Web application in a way that servlets can be invoked by class
name. WAS also enables us to invoke servlets by an alias name, and this is the
preferred technique.
We defined all our servlets in WAS by selecting the vcl Web application in the
Topology tab, and selecting Create -> Servlet from the context menu.
Figure 19-11 shows the result for our vcl Web application.
Figure 19-11 Defining servlets for vcl Web application
Note: Another way to define servlets is to customize the XML config file. We
will not discuss this further, but it is a practical solution when you have a lot of
servlets to define.
19.2 Additional deployment considerations

This section discusses additional technical considerations in addition to the
model-view-controller considerations. The information in this section relates to
the deployment of technical aspects of our e-business application.
19.2.1 The e-business application

The e-business application originates in VisualAge Pacbase and is defined using
the e-business Workbench. The e-business application groups a set of technical

components which are common to elementary components such as folders. The
e-business application must be defined previous to creating the folders.
The e-business application may contain several technical components such as

communication monitors, folders, and elementary components, but will only
contain one error server.
The main purpose of the e-business application is to establish the technical

components needed to correctly run the application in a manner that makes
these technical components common to all of the application components. This
eliminates multiple versions of these technical components and prevents
duplicating technical components for each of the application components. This
simplifies not only the deployment of the application, but the maintenance and
re-deployment of the application as well.
For an example of the need for a technical component, consider that all
elementary components that call each other must have the same user buffer and
the same server buffer which are defined once in the e-business application.
Thus, the e-business application in VisualAge Pacbase is purely a technical
component which groups a set of programs that can call each other and that
share other common characteristics.
When the proxy is generated, the e-business application component

corresponds to the package that contains all the reusable classes of the proxies
(DataDescription, SelectionCriteria, UserContext, UserDataDescription). The
e-business application role typically applies when using the multi-services
request, which can work only between proxies that belong to the same
e-business application, where proxies are generated from folders of the same
application.
Considering these facts, the main criteria for defining an e-business application
centers on the user buffer requirements to support the calling of programs within
the deployed application. The content of the e-business application is based on
this technical concern. Resist the temptation to use the e-business application as
a functional grouping.
19.2.2 Communications monitor

The communications monitor is a major technical component defined as part of
the e-business application. To define the communications monitor you must
specify a message size (the default size is 2 KB, but the message can be as
large as 48 KB) and a communication protocol. As the name implies, the
communications monitor is responsible for sending and receiving messages. In
addition, the communications monitor calls the appropriate folder managers to
process the transaction and plays a part in error management (commit/rollback).

19.2.3 Working file
Working file refers to the technical file that is used by the communication monitor
to store and manage temporary information during the execution of the
application. This temporary information is necessary in order to build the request
or its response when several messages are involved. Depending on your
hardware, communications, operating system, and database management
system, the working file may be implemented in a variety of ways. The working
file could easily be a DB2 table, for example, or even an indexed file.
For our VisualAge Cruise Lines sample application, we used an indexed file for
our working file. We followed these steps to accomplish this:
1. The path to this working file needs to be indicated in the Windows/NT
environment parameters, so that the folder manager finds it at runtime. We
defined a user variable named WF00IX.
2. We defined two data elements to support the detail of our working file:
– Keywf, 37-characters long, alphanumeric, defined as the segment key
– Detail, 250 characters long, alphanumeric, as a simple field
3. We also defined the working file as a segment in VisualAge Pacbase in order
for the e-business application components to know its logical name and
structure. This segment contained two data elements:
– Keywf, the segment key
– Detail, as a data field
4. We also built, generated, and compiled a simple program using VisualAge
Pacbase to produce this file.
19.2.4 Error server

The error server is a technical component that is defined as part of the
e-business application in VisualAge Pacbase. The error server manages
application specific errors. VisualAge Pacbase presents you with choices
concerning error management depending on your hardware, communications,
operating system, and database management system.
VisualAge Pacbase allows you to generate the source for error messages as a
file that consists of a key to retrieve the message and the text of the error
message. This file can be processed with a utility, for example, to load it into a
DB2 table for use with an application. In our sample application, we chose to use
the file to populate the Java properties. When application specific errors occurred
on the server, the key for the error was sent back to the client. The key was then
used by the client to retrieve the corresponding error message so that the text of
the message could be displayed to the end-user.

Part 3
Part 3 Appendixes
In this section, we provide the supplentary coding examples that go along with
this book.

A
Appendix A. Additional material

This redbook refers to additional material that can be downloaded from the
Internet as described below.
Locating the Web material

The Web material associated with this redbook is available in softcopy on the
Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG246201
Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with
the redbook form number, SG246201.
Using the Web material

The additional Web material that accompanies this redbook includes the
following files:
File name Description
VAJRepositoryData.zip Zipped VisualAge for Java repository data

WStudioWAR.zip Zipped WebSphere Studio archive file
System requirements for downloading the Web material

The following system configuration is recommended:
Hard disk space : 2 MB minimum
Operating System: Windows NT 4.0 SP5
Processor : Pentium II or higher
Memory: 128 MB minimum
How to use the Web material

Create a subdirectory (folder) on your workstation, and unzip the contents of the
Web material zip file into this folder.
In the following sections, we explain how to prepare your environment to install

and manipulate this Web material.
Preparation involves two things:

1. Importing VisualAge for Java repository data into your VisualAge for Java
Version 3.02 environment.
2. Restoring the WebSphere Studio .WAR archive file into your WebSphere
Studio Version 3.0 environment.
Importing VisualAge for Java repository data

The Web material includes VisualAge for Java repository data for the extended
samples. You need to import this repository data into your VisualAge for Java
environment.
The repository data is zipped inside the VAJRepositoryData.zip file. Unzip this
file in a VAJRepositoryData subdirectory. The repository data is now located
at...\VAJRepositoryData\SG246201.dat.
When you import the repository data, select the following projects, and add each
to your Workbench:
򐂰 SG246201 Redbook Framework, which includes the following packages:
– com.ibm.redbooks.sg246201.framework.businessobject
– com.ibm.redbooks.sg246201.framework.command
– com.ibm.redbooks.sg246201.framework.forms
– com.ibm.redbooks.sg246201.framework.servlet

򐂰 SG246201 Redbook VisualAge Cruise Lines, which includes the following
packages:
– com.ibm.redbooks.sg246201.cruiselines
– com.ibm.redbooks.sg246201.cruiselines.wap
– com.ibm.redbooks.sg246201.destination
– com.ibm.redbooks.sg246201.login
– com.ibm.redbooks.sg246201.reservation
– com.ibm.redbooks.sg246201.reservation.wap
򐂰 SG246201 Redbook VisualAge Cruise Lines Proxies, which includes the
following packages:
– com.cruise.cruiseline.proxies
– com.cruise.destination.proxies
– com.cruise.reservation.proxies
Importing the WebSphere Studio .WAR file

The Web material includes the WebSphere Studio .WAR file for the extended
samples. You need to import this archive file into your WebSphere Studio
environment.
The repository data is zipped inside the WStudioWAR.zip file. Unzip this file in a
WStudioWAR subdirectory. The repository data is now located at:
...\WStudioWAR\SG246201.war.
To import this .WAR file, select File->Open Archive... and open the above .WAR
file. You are then presented with options that pertain to importing the archive.
At the Extract tab, select Create new project and extract entire archive.
At the Destination tab, select Custom locations and type in the directory name
that you want to use.
At the Options tab, select Use archived publishing targets so that you do not
have to set up your publishing target again.
When you finish selecting the options, click the Extract button.
Appendix A. Additional material 433

Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks”
on page 437.
򐂰 Connecting the Enterprise to the Internet with MQSeries and VisualAge Java,
SG24-2144
򐂰 Application Development with VisualAge for Java Enterprise, SG24-5081
򐂰 VisualAge for Java Enterprise Version 2 Team Support, SG24-5245
򐂰 Programming with VisualAge for Java Version 2, SG24-5264, published by
Prentice Hall, ISBN 0130212989, 1999 (IBM form number SR23-9016)
򐂰 Developing an e-business Application for the IBM WebSphere Application
Server, SG24-5423
򐂰 VisualAge for Java Version 3: Persistence Builder with GUIs, Servlets, and
Java Server Pages, SG24-5426
򐂰 WebSphere Application Servers: Standard and Advanced Editions,
SG24-5460
򐂰 IBM WebSphere and VisualAge for Java Database Integration with DB2,
Oracle, and SQL Server, SG24-5471
򐂰 The XML Files: Using XML and XSL with IBM WebSphere 3.0, SG24-5479
򐂰 The Front of IBM WebSphere, Building e-business User Interfaces,
SG24-5488
򐂰 WebSphere Version 3 Performance Tuning Guide, SG24-5657
򐂰 Servlet/JSP/EJB Design and Implementation Guide, SG24-5754
򐂰 Servlet and JSP Programming with IBM WebSphere Studio and VisualAge for
Java, SG24-5755
򐂰 User to Business Patterns for Topology 1 and 2 using WebSphere Advanced
Edition, SG24-5864

Other resources
These publications are also relevant as further information sources:
򐂰 Design Patterns - Elements of Reusable Object-Oriented Software, Erich
Gamma, Richard Helm, Ralph Johnson, and John Vlissides published by
Addison-Wesley Professional Computing Series ISBN 0201633612 (IBM form
number SR28-5629)
򐂰 The Unified Modeling Language User Guide (The Addison-Wesley Object
Technology Series), Grady Booch, Ivar Jacobson and James Rumbaugh,
published by Addison-Wesley ISBN 0201571684
򐂰 UML Distilled, Second Edition: A Brief Guide to the Standard Object Modeling
Language (The Addison-Wesley Object Technology Series), Martin Fowler,
Kendall Scott (contributor), Grady Booch published by Addison-Wesley ISBN
020165783X
򐂰 Managing the Software Process, Watts S. Humphrey Booch published by
Addison-Wesley ISBN 0201180952
Referenced Web sites

These Web sites are also relevant as further information sources:
򐂰 VisualAge Pacbase
http://www.ibm.com/software/ad/vapacbase
򐂰 WebSphere Application Servers
http://www.ibm.com/software/webservers/appserv
򐂰 WebSphere Studio
http://www.ibm.com/software/webservers/studio
򐂰 VisualAge for Java
http://www.ibm.com/software/ad/vaJava
򐂰 DB2 Universal Database
http://www.ibm.com/software/data/db2/udb
򐂰 MQSeries
http://www.ibm.com/software/ts/mqseries
򐂰 Rational Rose
http://www.rational.com

How to get IBM Redbooks
You can order hardcopy Redbooks, as well as view, download, or search for
Redbooks at the following Web site:
ibm.com/redbooks
You can also download additional materials (code samples or diskette/CD-ROM

images) from that site.
IBM Redbooks collections

Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the
Redbooks Web site for information about all the CD-ROMs offered, as well as
updates and formats.
Related publications 437

Index
building the model layer 245
A business object framework 252
adapting the presentation to the WAP 409
business object programming process 255
add persistence object button 174
business pattern
add relational database button 174
application integration 18
AddDestinationCommand 364
business-to-business 18
AddDestinationCommand class 365
user-to-business 18
AddDestinationServlet 395
user-to-data 18
AddDestinationServlet class 395
user-to-online buying 18
adding a destination 351
user-to-user 18
adding a feature to the VisualAge for Java work-
BusinessObject interface 253
bench 92
BusinessObjectFactory class 253
adding the Programs tab 88
additional communications information 76
additional deployment considerations 426 C
additonal directory locations 58 call one or more data elements button 162
administration database directory structure 65 cardinality constraints for aggregations 314
administrative library layer 189 cardinality constraints for references 314
administrator sign on 132 changing a directory location 52
administrator Workbench menu bar 104 changing the application server classpath 424
aggregation and references 313 changing the error message text using the parame-
analysis and design 202–203 ters browser 110
application architecture overview 17 changing the Web application classpath 424
arrival reference 340 choose data elements to call screen 163
associatives 314 choosing a business pattern 18
available cross-references 197 choosing a runtime topology 19
choosing an application topology 19
choosing the administration database location 49
B class
backward development path 203
ShipData 233
batch programming workbench 30
ShipDataBeanInfo 234
batch programs and macros 195
ShipDataUpdate 233
beginning the administration database installation
ShipDataUpdateBeanInfo 234
47
ShipProxyBeanInfo 234
BookCruiseCommand 371
ShipProxyTableModel 233
BookCruiseCommand class 372
ShipProxyUpdateTableModel 233–234
BookCruiseServlet 406
ShipSelectionCriteria 233
BookCruiseServlet class 406
ShipSelectionCriteriaBeanInfo 234
bridging from Rational Rose 309
Class and method comments 26
building a proxy 219
class diagrams 312
building a services node 206
classes and attributes 312
building a services system 207
Client/Server Facility-Generator 341
building folder views 226
client-side implementation 208
building JSPs and servlets 375
client-side test tools 283
building services and data access 213

code in the macro 170 client-side, presentation, navigation 203
command bean design pattern 21 presentation and navigation 203
command framework 249 refinement 204
command interface 249 server-side 202
command line processing 115 server-side components 203
command Lines 115 content of the Input folder 66
command pattern 248 content of the Journal folder 66
command programming process 252 content of the Nls folder 62
command state diagram 250 content of the Pgm folder 63
CommandException class 250 content of the Proc folder 63
CommandException JSP 387 content of the Save folder 66
CommandException.JSP 387 content of the Setbases folder 63
CommandFactory class 252 content of the Tmp folder 67
comments 261 contents of Base folder 65
commonly encountered Web problems 13 contents of Skel folder 64
communication monitor 216, 219 control mechanism and navigation 272
communication/middleware 13 control mechanism servlet/command/JSP 273
communications monitor 27, 427 controller
complete product environment 37 servlet 23
completing server development 325 controller and model layers directory structure 423
completing the imported entities 323 cookies 269
completing the system installation 46 create a function/sub-function button 170
completion of the installation of Workbench 82 create a macro structure button 169
components 5 create a segment button 161
components of JavaServer pages 258 create data element button 158
composition for Cruise 329 create generation command line SmartGuide 154
composition for Reservation 331–332 create new command line button 153
composition for Ship 334 create new communication monitor button 182
composition of Cruise 326 create new composition button 175
composition of CruiseLine 327 create new e-business application button 179
composition of Reservation 328 create new elementary component (EC) button 173
composition of Ship 328 create new folder (FO) button 180
configuration file manager 85 create new logical view button 171
configuring the Web application - document root and create property button 160
class path 421 create value button 160
Configuring the Web application - name, servlets, creating nodes 222
JSP support 420 creating presentation with JSPs 257
configuring the Web application - servlet engine creating the folders 378
420 creating the Java packages 345
configuring the Web application - virtual host and creating the required Web application directories
Web path 421 422
Confirmation JSP 386 creating the VisualAge Cruise Lines Web applica-
Confirmation.JSP 386 tion 418
confirming the development database installation creating the VisualAge projects 344
60 creating the WebSphere Studio project 376
confirming the system installation 44 cross-reference considerations 197
connecting additional databases 78 cross-references 197
construction cruise detail through WAP 412
client-side components 204 Cruise line commands 366

Cruise line DataDeliveryBeans 389 describing the folder 221
cruise line selection through WAP 411 design techniques used 20
Cruise line servlets 400 designing a VisualAge Pacbase application 204
CruiseArrayDataDeliveryBean 389 destination business object 350
CruiseDataDeliveryBean 390 destination DataDeliveryBeans 388
CruiseDataDeliveryBean properties 390 destination servlets 393
CruiseDetail JSP 386 DestinationAdding JSP 384
CruiseDetail.JSP 386 DestinationAdding.jsp 383
CruiseLineArrayDataDeliveryBean 391 DestinationArrayDataDeliveryBean 388
CruiseLineBusinessObject 354 DestinationBusinessObject class 350
CruiseLineBusinessOpbject class 354 DestinationDataComparator class 353
CruisesList JSP 385 DestinationDataDeliveryBean 389
CruisesList.JSP 385 DestinationDeliveryBean properties 389
customer JSPs 384 DestinationDetail JSP 384
CustomerHomePage JSP 385 DestinationDetail.jsp 384
CustomerHomePage.JSP 385 DestinationsCatalog JSP 383
customizing the stages 379 DestinationsCatalog.jsp 382
details of data elements 149
developing commands 359
D developing JavaBeans 343
data elements workbench 159
developing navigation 209
data entities 191
developing presentation 209
data integrity 14
developing services components 208
data structure create button 161
developing the business objects 349
data structures and segments 192
developing the DataDeliveryBeans 388
database blocks 192
developing the JavaServer pages 382
databases 114
developing the servlets 392
DB2 Universal Database 34
developing the WML-based JSPs 409
DB2 Universal Database (UDB) 32
development approach 22
dcoumenting text pages 111
development database directory structure 68
declarations 260
development libraries 190
default location for the development database 57
development paths 202
defining servlets 426
development process summary 210
defining servlets for vcl Web application 426
development products 20
defining the application architecture 20
DB2 Universal Database (database develop-
definition window 174
ment) 20
definitions 4
VisualAge for COBOL (Compiling COBOL serv-
departure reference 339
ers) 20
DependentProxyLv 233
VisualAge for Java (Java development) 20
deploying an e-business application 283
VisualAge Pacbase (Servers) 20
deploying files to WAS 423
WebSphere Studio (HTML and JSPs develop-
deploying HTML pages and JSPs 284
ment) 20
deploying server side components 284
development standards 24
deploying servlets and JavaBeans 286
development with the e-business Workbench 158
deploying the application 417
diagrams 311
deploying the view layer 423
directory structure for the workstation 83
deploying the VisualAge Cruise Lines Application
directory structure from Workbench installation 83
418
discard all changes button 151
deployment 212
discard button 145
Index 441
distributing the work among development teams folder resulting from the bridging process 322
211 folder structure for SG246201 Redbook project 378
documentation entities 193 folder view 217
dynamic part of the tool bar 145 folders 335
forward development path 202
framework overview 22
E Function 60 157
e-business application 215, 219, 426
e-business application from the bridging process
323 G
edit host options 80 gateway considerations 98
editing the workspace class path 95 generate button 341
editing the workspace resources (options window) generated applications 199
94 generated methods 239
element detail to complete 324 generating 340
elementary component 177, 214, 222 generating the VisualAge Pacbase entities 320
elementary components 329 generation manager 152–153
Cruise 329 generation options 342
CruiseLine 330 generic controller servlet 275
Reservation 332 GetCruiseDetailCommand 370
Ship 333 GetCruiseDetailCommand class 370
elementary components from the bridging process GetCruiseDetailServlet 404
322 GetCruiseDetailServlet class 404
employee JSPs 382 GetCruiseLinesCommand 366
EmployeeActions HTML page 382 GetCruiseLinesCommand class 367
EmployeeHomePage HTML page 381 GetCruiseLinesServlet 400
Empty HTML page 381 GetCruiseLinesServlet class 400
empty Workbench 140 GetCruisesCommand 368
environment GetCruisesCommand class 368
administration 39 GetCruisesServlet 401
installation 39 GetCruisesServlet class 402
setup 39 GetDestinationsCommand 360
error file 219 GetDestinationsCommand class 360
error handling 23 GetDestinationsServlet 393
error server 216, 428 GetDestinationsServlet class 393
example using the DataDeliveryBean 264 getting a specific cruise 357
expressions 261 getting a specific destination using its unique key
external controls 130 353
extract method 220 getting all cruise lines 355
getting all cruises for a cruise line 355
getting all destinations 352
F GetUniqueDestinationCommand 361
factory pattern 247
GetUniqueDestinationCommand class 362
file menu 141
GetUniqueDestinationServlet 397
finishing the folder 226
GetUniqueDestinationServlet class 397
Folder 233
granularity 272
folder 216, 311
CruiseLine 336
Reservation 335 H
folder composition for CruiseLine 336 help menu 143

HierarchicalProxyLv 232 base 35
hierarchy of generated proxies 232 integration of VisualAge for Java with WebSphere
hierarchy overview 232 Application Server 36
HTML pages 15 integration of VisualAge for Java with WebSphere
Studio 35
integration of WebSphere Application Server with
I DB2 36
identifying the business objects 349
integration of WebSphere Studio with WebSphere
identifying the commands 359
Application Server 36
identifying the DataDeliveryBeans 388
interfaces to legacy applications 14
identifying the servlets 392
introducing the WAP application 408
implementing HTML pages 380
introduction to Java servlets 268
implementing navigation with servlets 267
introduction to JavaServer pages 258
implementing the navigation 271
introduction to patterns 18
implementing the presentation 263
implementing the singleton pattern in Java 246
implementing wireless presentation using JSP 265 J
implicit objects 261 Java class standards 25
import from repository button 146 Java license acceptance 71
import/create by code button 148 Java method standards 25
imported data elements 320 Java package standards 25
imported packages for generated proxies 348 Java proxy classes hierarchy 232
importing jar file options 96 Java Servlet API 268
importing jar files into the class path 94 Java variables standards 25
importing jar files into VisualAge for Java projects JavaBeans 15
95 JavaServer Pages (JSPs) 16
importing the Rose model 318 JSP actions 262
importing the VisualAge Pacbase proxies 348 JSP directives 259
include directive 260 JSP getProperty tag 262
indicating the destination folder 73 JSP scripting 260
inheritance 313 JSP setProperty tag 263
initialization controls 131 JSP tags guidelines 264
installation/setup of VisualAge Pacbase 3.0 respos- JSP useBean tag 262
itory 40 JSP/servlet architecture main components 14
installed bridge 316
installing a development database 55
installing the administration database 46
L
levelling 156
installing the communication DLLs 98
libraries 188
installing the software 43
library to support the Rose Bridge 317
installing the VisualAge Pacbase Java environment
listener 27
93
logical view 214, 220
installing the VisualAge Pacbase middleware 98
Cruise 326
installing the VisualAge Pacbase system 43
CruiseLine 327
installing the VisualAge Pacbase Workbench 69
Reservation 327
installing the WebSphere test environment feature
Ship 328
92
logical views 326
integration of Rational Rose with VisualAge for Java
logical views from the bridging process 321
35
lower half of the import SmartGuide 147
integration of Rational Rose with VisualAge Pac-
Index 443
M opening the Rose model file 318
main local services for a dependent or reference operating the bridge 317
proxy 235 operations 312
main local services for a folder proxy 234 options for the administration database 48
MainMenu HTML page 381 organizing the repository for reusability 187
maintenance considerations 197 orienting relations 313
making VisualAge Pacbase Java environment a fea-
ture 97
managing libraries 134
P
Pac/Transfer 120
mapping between dependent proxy and server 238 Pac/Transfer database selection 122
mapping between folder proxy and server 236 Pac/Transfer selection criteria tabs 123
mapping between reference proxy and server 238 Pac/Transfer SmartGuide 121
menu bar 140 packages 311
method page directive 259
detail() 235–236 parameterized input aid 194
getDetailFromDataDescription(aData) parameters added by default 119
235–236 partial listing of files for workstation 84
getTableModel() 235–236 patterns design process
getUpdatedFoldersTableModel() 235 choose application topology 18
getUpdatedInstancesTableModel() 235–236 choose business pattern 18
getXxx() (for example, getCabinProxy()) 235 choose runtime topology 18
selectionCriteria() 235–236 defining application architecture 18
undoLocalFolderUpdates(aDataUpdate) 235 defining products 18
undoLocalUpdate(aDataUpdate) 235 defining the runtime context 18
methodology support 5 development framework 18
middleware 27 development standards 18
middleware communications type 79 within the development context 18
model within the runtime context 18
command bean and business objects 22 performance 13
model layer summary 255–256 persistence management 14
Model-View-Controller (MVC) framework 21 persistency management 269
ModifyDestinationCommand 363 PO cinemtics window 175
ModifyDestinationCommand class 363 portability 199
ModifyDestinationServlet 398 positioning the repository 191
ModifyDestinationServlet class 399 preparing the VisualAge environment 344
modifying a destination 351 preparing the WebSphere Studio environment 376
MQSeries 34 proceeding to install the administration database
MQSeries messaging environment 32 53
proceeding with the Workbench installation 81
N processing entities 194
node by node retrieval, option 1 241 product mapping 20
node by node retrieval, option 2 242 profiles 116
nodes 221 programming bar 164
non JSP resulting servlets 273 programming concepts 155
programming process 263, 271
Programs tab added to the workbench 89
O progress of the system installation 45
one-layer architecture 8
properties for Cruise 338
opening default.cfg for the Workbench 86

properties for CruiseLine 337 quick start window 139
properties for Reservation 335
properties for Ship 337
properties window 181
R
Rational Rose 5, 32
providing a user and organization 42
Rational Rose modeling environment 32
proxy 16
Redbooks Web site 437
proxy dynamics 240
Contact us xvii
node by node retrieval, open 2 242
ReferenceProxyLv 233
node by node retrieval, option 1 242
refresh all button 151
retrieving all dependent nodes at once 243
refresh button 144
retrieving root instances 241
refresh invalid entities button 152
proxy features 231
refresh updated entities list button 151
proxy generation 340
relation to the Rational Rose toolkit 206
proxy generation process 230
relation to Unified Modeling Language (UML) 204
proxy object 4
relations 313
proxy related generated classes 233
removing a tab 91
proxy service
reports 196
checkExistenceOfDependentInstances() 236,
repositioning a tab 90
238
repositiry
executeUserService() 237–238
users 31
readAllChildren(RacineData) 237
repository 31
readAllChildrenFromCurrentInstance() 237
batch programs 31
readFirstChildren(DependantData) 238
data elements 31
readFirstChildren(RacineData) 237
data structures 31
readFirstChildrenFromCurrentInstance()
database blocks 31
237–238
documentation 31
readInstance() 237–239
e-business programs 31
readInstanceWithAllChildren() 237
libraries 31
readInstanceWithFirstChildren() 237–238
methodology 31
readNextPage() 237–239
reports 31
selectInstances() 237–239
segments 31
setExtractMethodCode(String) 237–239
repository content 199
setGlobalSelection(boolean) 237–239
required components 204
setMaximumNumberOfRequestedInstanc-
Reservation commands 371
es(int) 237–239
Reservation DataDeliveryBeans 391
setUserServiceCode(String) 237–238
reservation servlets 406
updateFolder() 237
ReservationBusinessObject 358
ProxyLv 232
ReservationBusinessObject class 358
public services of generated proxies 234
ReservationDataDeliveryBean 391
publishing facility 194
ReservationDataDeliveryBean properties 391
purchase confirmation through WAP 413
resolving many-to-many relations 315
Putting it all together - BookCruiseServlet 408
retrieving all dependent instances at once 243
Putting it all together - GetCruiseDetailServlet 405
retrieving dependent instances 241
Putting it all together - GetCruiseLinesServlet 401
retrieving root instances 241
Putting it all together - GetCruiseServlet 403
reusability 186
reusable components 186
Q runtime products 20
qQuick tour of the Workbench 139 DB2 Universal Database 5.0 (database man-
Index 445
agement) 20 specifying Pac/Transfer change numbers (DSMS
IBM HTTP Server (HTTP server) 20 only) 127
JDK1.1.7 (Java Virtual Machine) 20 specifying sessions for Pac/Transfer 124
WebSphere Application Server Advanced Edi- specifying source and target libraries 125
tion (Java application server) 20 specifying the communications type 75
Windows NT 4.0 (operating system) 20 specifying the external controls 130
runtime testing 286 specifying the gateway IP address and port 77
runtime topology specifying user codes for Pac/Transfer 126
communications 19 standard tool bar icons 144
database management system 19 starting the Administrative Console 418
operating system 19 starting the administrator workbench 101
starting the installation 41
starting the Web application 425
S starting WebSphere Application Server as a service
sample proxy hierarchy 240
419
save all button 151
subclassing the servlets 413
save button 145
submit and save button 155
scriptlets 260
successful installation of development database 61
search button 144
successful installation of the administration data-
security 14
base 54
select identifier window 182
summary of development environment 37
selecting the WebSphere Test Environment feature
summary of runtime environment 38
93
support for e-business 6
selecting the Workbench modules 74
system directories 62
server-side implementation 206
services manager 217
serving dynamic WML content using servlets and T
JSPs 265 tabs for the VisualAge Pacbase administrator work-
servlet process flow 268 bench 106
ServletContext group 269 tabs for the workbench 87
servlets 15 team considerations 211
servlets - Include and Forward 274 technical environment 218
session 270 terminology 4
setting a technical context 207 testing 210
setting the Java classpath 347 testing and deployment 203–204, 277
setting the JSP version 347 testing the e-business application 227
setting the JSP version in WebSphere Studio 377 testing with the WAP application 415
setting versions for the JSP and the application serv- three-layer architecture with applet/servlet 11
er 376 three-layer architecture with JSP/servlet 12
settings for the Rose Bridge import 319 top half of the import SmartGuide 146
show details button 148 traffic loads 13
signing on to the VisualAge Pacbase administrator two-layer architecture 9
workbench 102 two-layer architecture with applets and JDBC 10
signon library view 198
singleton pattern 246
SmartGuide for adding a profile 117
U
Unified Modeling Language (UML) 5
SmartGuide for Workbench installation 70
updating the application server classpath 425
specifying a development database 56
updating the Web application classpath 424
specifying additional locations 50
useful patterns 246

user options for the Workbench 72 destinations object 291
user REDBOOK 129 elementary components for the sample applica-
users 128 tion 298
user-to-business application topology 19 employee concerns 290
using Rational Rose 310 employee intranet choices 305
using the administrator Workbench 113 employee sign on for cruise management 304
using the Profiles tab 116 first relationship 292
using the Rational Rose bridge 311 folder content for sample application 296
using the Task Wizard 419 fourth relationship 293
using VisualAge Pacbase 311 homepage for the sample application 299
logical views for the sample application 295
management 304
V name attribute 291
validity controls 131
number of available tickets attribute 292
VAP Test Tool folders browser 281
number of reservations attribute 292
VAP Test Tool folders hierarchal view 282
number of tickets attribute 292
VAP Test Tool launching menu 279
objects 291
VapGateway.exe parameters 99
port country attribute 292
verifying the administration database install 64
port name attribute 292
verifying the development database install 67
price attribute 292
verifying the installation 61
processing considerations and implementation
verifying the system installation 62
297
view
registry attirbute 291
JSPs 23
relationships 292
view layer directory structure 423
requirements 290
VisualAge Cruise Lines
reservation ID attribute 292
adding a destination 307
reservations object 291
application specifications 289
second relationship 292
background 290
segments supporting the sample application
country attibute 291
294
cruise ID attirbute 291
ships object 291
cruise line detail 301
specific cruise detail 302
cruise line ID attirbute 291
third relationship 293
cruise line ID attribute 291–292
total price attribute 292
cruise line selection 300
VisualAge Cruise Lines packages 346
cruise lines object 291
VisualAge Cruise Lines WAP homepage 410
cruise name attribute 291
VisualAge for Java 33
cruises object 291
VisualAge for Java development environment 32
customer concerns 290
VisualAge for Java ready-to-use workbench 345
customer reservation 299
VisualAge Pacbase
customer reservation confirmation 303
administrator icons 129
data considerations 291
administrator Workbench tabs 113
data elements supporting the sample application
advantages 4
293
architecture 27
data implementation 293
base administration 131
data implementation structure 297
development 137
description attribute 291
development process 201
destination ID attribute 292
overview 3
destinations already established 306
Parameters browser 109
Index 447
products overview 29
proxy 16, 229
proxy as an interface for the server 17
proxy components 16
proxy is generated 17
repository 30
reuse and portability 185
runtime project 97
Security Browser 107
server 30
site administration 100
targeted application architecture 7
Test Tool 278
utilities 135
workbench 30
VisualAge project standards 24
VisualAge version names standards 26
VisualAgeCruiseLine HTML page 380
W
WAP in the architecture 266
WAP relative to our e-business architecture 266
WapConfirmation.jsp 412
WapCruiseDetail.jsp 411
WapCruisesList.jsp 410
WapCustomerHomePage.jsp 409
Web application director structure 422
Web applications 8
Web architectures 8
WebSphere Application Server 34
WebSphere Application Server execution environ-
ment 32
WebSphere Application Server topology 285
WebSphere specific tags 263
WebSphere Studio 33
WebSphere Studio development environment 32
WebSphere Test Environment publishing page 380
WebSphere Test Environment setup 346
what is a VAP proxy 230
window menu 142
Wireless Application Protocol (WAP) 265
Workbench in general 138
workbench with Rose Bridge 316
working file 428
workspace manager 149–150
workspace menu 142

VisualAge Pacbase
for e-business Applications
(1.0” spine)
0.875”<->1.498”
460 <-> 788 pages
Back cover ®
VisualAge Pacbase
for e-business
Applications
An overview of This IBM Redbook provides you with information that will
VisualAge Pacbase allow you to use VisualAge Pacbase 3.0 (VAP) to create,
INTERNATIONAL
V3 manage, and deploy e-business applications in an application TECHNICAL
repository environment. SUPPORT
Step-by-by guide to ORGANIZATION
In Part 1, we focus on the installation of VisualAge Pacbase
develop an
and the administration and use of the product. We describe
e-business
the targeted application architecture and provide an overview
application of the products, other required tools, and their integration with BUILDING TECHNICAL
VisualAge Pacbase, as well as the VisualAge Pacbase INFORMATION BASED ON
Develop JSPs and PRACTICAL EXPERIENCE
development model. We present the advantages of using the
EJBs VisualAge Pacbase proxy for e-business applications and
explain how to build a view with the proxy on the client side IBM Redbooks are developed by
of the application. the IBM International Technical
Support Organization. Experts
from IBM, Customers and
In Part 2, we develop an e-business application using
Partners from around the world
VisualAge Pacbase 3.0, WebSphere Studio, and VisualAge for create timely technical
Java. We discuss design, construction, testing, and information based on realistic
implementation. Our sample application establishes a Web scenarios. Specific
site for the VisualAge Cruise Line sample and provides a WAP recommendations are provided
to help you implement IT
version of the implementation as well.
solutions more effectively in
your environment.
For more information:

ibm.com/redbooks
SG24-6201-00 ISBN 0738421200

Visual Age Pacbase

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Visual Age Pacbase

Hochgeladen von

Copyright:

Verfügbare Formate

Front cover

Step-by-by guide to develop an

Develop JSPs and EJBs

VisualAge Pacbase for e-business Applications

First Edition (December 2002)

© Copyright International Business Machines Corporation 2002. All rights reserved.

Part 1. e-business application development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. VisualAge Pacbase overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2. VisualAge Pacbase targeted application architecture . . . . . . . 7

© Copyright IBM Corp. 2002. All rights reserved. iii

Chapter 3. VisualAge Pacbase products: overview . . . . . . . . . . . . . . . . . . 29

Chapter 4. Environment setup, installation, and administration . . . . . . . 39

iv VisualAge Pacbase for e-business Applications

Chapter 5. VisualAge Pacbase 3.0 development . . . . . . . . . . . . . . . . . . . 137

Chapter 6. Reuse and portability in VisualAge Pacbase . . . . . . . . . . . . . 185

Chapter 7. VisualAge Pacbase development process . . . . . . . . . . . . . . . 201

Chapter 8. Building services and data access . . . . . . . . . . . . . . . . . . . . . 213

vi VisualAge Pacbase for e-business Applications

Chapter 9. The VisualAge Pacbase proxy . . . . . . . . . . . . . . . . . . . . . . . . . 229

Chapter 10. Building the model layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Chapter 11. Creating presentation with JSPs. . . . . . . . . . . . . . . . . . . . . . 257

Chapter 12. Implementing navigation with servlets. . . . . . . . . . . . . . . . . 267

Chapter 13. Testing and deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Part 2. VisualAge Pacbase Cruise Lines sample application . . . . . . . . . . . . . . . . . . . . . . 287

Chapter 14. VisualAge Cruise Lines application specifications . . . . . . . 289

viii VisualAge Pacbase for e-business Applications

Chapter 15. Bridging from Rational Rose . . . . . . . . . . . . . . . . . . . . . . . . . 309

Chapter 16. Completing server development . . . . . . . . . . . . . . . . . . . . . . 325

Chapter 17. Developing JavaBeans . . . . . . . . . . ...... ....... ...... . 343

Chapter 18. Building JSPs and servlets . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Chapter 19. Deploying the application . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

x VisualAge Pacbase for e-business Applications

Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

Related publications . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 435

© Copyright IBM Corp. 2002. All rights reserved. xiii

Balance® IBM eServer™ Redbooks™

Approach® Lotus® Word Pro®

The following terms are trademarks of other companies:

xiv VisualAge Pacbase for e-business Applications

In Part 1, we focus on the installation of VisualAge Pacbase and the

In Part 2, we develop an e-business application using VisualAge Pacbase 3.0,

The team that wrote this redbook

Richard Brijde is a VAP Specialist with New Age Consultancy in The

Randall Holleger is a Product Implementation Manager with e-Applications

© Copyright IBM Corp. 2002. All rights reserved. xv

Become a published author

xvi VisualAge Pacbase for e-business Applications

We want our Redbooks to be as helpful as possible. Send us your comments

© Copyright IBM Corp. 2002. All rights reserved. 1

Chapter 1. VisualAge Pacbase overview

© Copyright IBM Corp. 2002. All rights reserved. 3

VisualAge Pacbase offers the following advantages for e-business applications:

VisualAge Pacbase 3.0 implements a modern development environment

VisualAge Pacbase 3.0 operates on a variety of hardware platforms and

4 VisualAge Pacbase for e-business Applications

Both the developer’s and administrator’s Workbenches have been completely

1.2 Methodology support

Chapter 1. VisualAge Pacbase overview 5

1.4 Support for e-business

Developers customize their VisualAge Pacbase development workstations to a

VisualAge Pacbase offers a practical solution to increase the use of Java