visual age pacbase

ibm.com/redbooks

VisualAge Pacbasefor e-businessApplications

Richard BrijdeRandall Holleger

David Quantin

An overview of VisualAge Pacbase V3

Step-by-by guide to develop an e-business application

Develop JSPs and EJBs

Front cover

VisualAge Pacbase for e-business Applications

December 2002

International Technical Support Organization

SG24-6201-00

© Copyright International Business Machines Corporation 2002. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADPSchedule Contract with IBM Corp.

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.

Note: Before using this information and the product it supports, read the information in “Notices” on page xiii.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvThe team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Part 1. e-business application development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. VisualAge Pacbase overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Definitions and terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2 Methodology support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.4 Support for e-business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2. VisualAge Pacbase targeted application architecture . . . . . . . 72.1 About Web applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.2 Main architectures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3 Commonly encountered problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.4 JSPs/servlet architecture main components . . . . . . . . . . . . . . . . . . . . . . . 14

2.4.1 HTML pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.4.2 Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.4.3 JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.4.4 JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.5 VisualAge Pacbase proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.6 Application architecture overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.6.1 Introduction to patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.6.2 Choosing the business pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.6.3 Choosing the application topology . . . . . . . . . . . . . . . . . . . . . . . . . . 192.6.4 Choosing a runtime topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.6.5 Product mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.7 Defining the application architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.7.1 Design techniques used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.7.2 Development approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.7.3 Development standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.8 Basic VisualAge Pacbase architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.8.1 Middleware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.8.2 Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

© Copyright IBM Corp. 2002. All rights reserved. iii

2.8.3 Communications monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3. VisualAge Pacbase products: overview . . . . . . . . . . . . . . . . . . 293.1 VisualAge Pacbase 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3.1.1 The Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.1.2 The repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3.2 Other tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.2.1 About Rational Rose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.2.2 About VisualAge for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.2.3 About WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.2.4 About WebSphere Application Server. . . . . . . . . . . . . . . . . . . . . . . . 343.2.5 About DB2 Universal Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.2.6 About MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

3.3 Tools integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.3.1 Integration of Rational Rose with VisualAge Pacbase . . . . . . . . . . . 353.3.2 Integration of Rational Rose with VisualAge for Java . . . . . . . . . . . . 353.3.3 Integration of VisualAge for Java with WebSphere Studio . . . . . . . . 353.3.4 Integration of VisualAge for Java with WAS . . . . . . . . . . . . . . . . . . . 363.3.5 Integration of WebSphere Studio with WAS . . . . . . . . . . . . . . . . . . . 363.3.6 Integration of WebSphere Application Server with DB2 . . . . . . . . . . 363.3.7 Complete product environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 4. Environment setup, installation, and administration . . . . . . . 394.1 Installation/setup: VisualAge Pacbase 3.0 repository . . . . . . . . . . . . . . . . 40

4.1.1 Special considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404.1.2 Running the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

4.2 Installing the VisualAge Pacbase Workbench . . . . . . . . . . . . . . . . . . . . . . 694.2.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

4.3 Impacts on other tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924.3.1 Installing the WebSphere test environment feature . . . . . . . . . . . . . 924.3.2 Installing the VisualAge Pacbase Java environment . . . . . . . . . . . . 93

4.4 VisualAge Pacbase 3.0: Site administration . . . . . . . . . . . . . . . . . . . . . . 1004.4.1 Starting the administrator Workbench. . . . . . . . . . . . . . . . . . . . . . . 1014.4.2 Menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044.4.3 Using the administrator Workbench . . . . . . . . . . . . . . . . . . . . . . . . 1134.4.4 Command lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154.4.5 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1164.4.6 Pac/Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204.4.7 Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1284.4.8 Tool bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

4.5 External controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304.5.1 Validity controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314.5.2 Initialization controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

iv VisualAge Pacbase for e-business Applications

4.6 VisualAge Pacbase 3.0: Base administration . . . . . . . . . . . . . . . . . . . . . 1314.6.1 Menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324.6.2 Base administration tab options . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

4.7 VisualAge Pacbase utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354.7.1 Changes from previous releases . . . . . . . . . . . . . . . . . . . . . . . . . . 1354.7.2 New to this release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Chapter 5. VisualAge Pacbase 3.0 development . . . . . . . . . . . . . . . . . . . 1375.1 The Workbench in general . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

5.1.1 Logging on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385.1.2 Quick tour of the Workbench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

5.2 The workspace manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495.2.1 The local update tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505.2.2 All problems tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1525.2.3 Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1525.2.4 Log tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

5.3 Generation manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1525.3.1 Generation command lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535.3.2 JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

5.4 Programming concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1555.5 Development with the e-business Workbench . . . . . . . . . . . . . . . . . . . . 158

5.5.1 Data elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1585.5.2 Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615.5.3 Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645.5.4 Logical views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715.5.5 Elementary components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725.5.6 e-business application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785.5.7 Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1805.5.8 Communication monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Chapter 6. Reuse and portability in VisualAge Pacbase . . . . . . . . . . . . . 1856.1 Reusability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

6.1.1 Reusable components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866.1.2 Organizing the repository for reusability . . . . . . . . . . . . . . . . . . . . . 1876.1.3 Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886.1.4 Positioning the repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

6.2 Data entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916.2.1 Data elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916.2.2 Data structures and segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926.2.3 Database blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

6.3 Documentation entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936.3.1 Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1936.3.2 Publishing facility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Contents v

6.3.3 Parameterized input aid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946.4 Processing entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

6.4.1 e-business. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956.4.2 Batch programs and macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956.4.3 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

6.5 Cross-references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976.5.1 Available cross-references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976.5.2 Maintenance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976.5.3 Cross-reference considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

6.6 Portability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1996.6.1 Repository content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1996.6.2 Generated applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Chapter 7. VisualAge Pacbase development process . . . . . . . . . . . . . . . 2017.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2027.2 Development paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

7.2.1 Forward development path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2027.2.2 Analysis and design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2027.2.3 Backward development path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

7.3 Designing a VisualAge Pacbase application . . . . . . . . . . . . . . . . . . . . . . 2047.3.1 Required components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2047.3.2 Relation to Unified Modeling Language (UML) . . . . . . . . . . . . . . . . 2047.3.3 Relation to the Rational Rose Toolkit . . . . . . . . . . . . . . . . . . . . . . . 206

7.4 Server-side implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067.4.1 Building a services node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067.4.2 Building a services system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077.4.3 Setting a technical context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077.4.4 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

7.5 Client-side implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087.5.1 Developing services components . . . . . . . . . . . . . . . . . . . . . . . . . . 2087.5.2 Developing presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097.5.3 Developing navigation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097.5.4 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

7.6 Development process summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2107.7 Team considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

7.7.1 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Chapter 8. Building services and data access . . . . . . . . . . . . . . . . . . . . . 2138.1 Logical view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2148.2 Elementary component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2148.3 The e-business application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

8.3.1 Error server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2168.4 Communication monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

vi VisualAge Pacbase for e-business Applications

8.5 Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2168.5.1 The Services Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178.5.2 Folder view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

8.6 Technical considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2188.6.1 Technical environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2188.6.2 Building a proxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2198.6.3 Testing the e-business application . . . . . . . . . . . . . . . . . . . . . . . . . 227

Chapter 9. The VisualAge Pacbase proxy . . . . . . . . . . . . . . . . . . . . . . . . . 2299.1 What is a VAP proxy? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2309.2 Proxy features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

9.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2319.2.2 Hierarchy of generated proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2329.2.3 Public services of generated proxies . . . . . . . . . . . . . . . . . . . . . . . 2349.2.4 More about proxy dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Chapter 10. Building the model layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24510.1 Useful patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

10.1.1 Singleton pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24610.1.2 Implementing the singleton pattern in Java. . . . . . . . . . . . . . . . . . 24610.1.3 Factory pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24710.1.4 Command pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

10.2 Command framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24910.2.1 Command interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24910.2.2 CommandException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25010.2.3 CommandFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25210.2.4 Command programming process . . . . . . . . . . . . . . . . . . . . . . . . . 252

10.3 Business object framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25210.3.1 BusinessObject interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25310.3.2 BusinessObjectFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25310.3.3 Business object programming process . . . . . . . . . . . . . . . . . . . . . 25510.3.4 Relation to the command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

10.4 Model layer summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Chapter 11. Creating presentation with JSPs. . . . . . . . . . . . . . . . . . . . . . 25711.1 Introduction to JavaServer pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25811.2 Components of JavaServer pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

11.2.1 JSP directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25911.2.2 Page directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25911.2.3 JSP scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26011.2.4 Comments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26111.2.5 JSP actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26211.2.6 About WebSphere specific tags . . . . . . . . . . . . . . . . . . . . . . . . . . 263

11.3 Implementing the presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Contents vii

11.3.1 Programming process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26311.3.2 JSP tags guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26411.3.3 A very simple example using the DataDeliveryBean . . . . . . . . . . 264

11.4 Implementing wireless presentation using JSP. . . . . . . . . . . . . . . . . . . 26511.4.1 About the Wireless Application Protocol (WAP) . . . . . . . . . . . . . . 26511.4.2 Serving dynamic WML content using servlets and JSPs . . . . . . . 26511.4.3 WAP relative to our e-business architecture . . . . . . . . . . . . . . . . . 266

Chapter 12. Implementing navigation with servlets. . . . . . . . . . . . . . . . . 26712.1 Introduction to Java servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

12.1.1 Servlet process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26812.1.2 The Java Servlet API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26812.1.3 Persistency management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26912.1.4 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

12.2 Implementing the navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27112.2.1 Programming process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27112.2.2 Granularity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27212.2.3 Control mechanism and navigation. . . . . . . . . . . . . . . . . . . . . . . . 27212.2.4 Non JSP resulting servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27312.2.5 A generic controller servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Chapter 13. Testing and deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27713.1 Using the VisualAge Pacbase Test Tool . . . . . . . . . . . . . . . . . . . . . . . . 278

13.1.1 Installing the tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27813.1.2 Configuring the tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27913.1.3 Running the tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

13.2 Other client-side test tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28313.3 Deploying an e-business application . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

13.3.1 Deploying server side components . . . . . . . . . . . . . . . . . . . . . . . . 28413.3.2 Deploying HTML pages and JSPs . . . . . . . . . . . . . . . . . . . . . . . . 28413.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 . . . . . . . 28914.1 VisualAge Cruise Lines background . . . . . . . . . . . . . . . . . . . . . . . . . . . 29014.2 VisualAge Cruise Lines requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 29014.3 Data considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

14.3.1 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29114.3.2 Relationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29214.3.3 Data implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

14.4 Processing considerations and implementation . . . . . . . . . . . . . . . . . . 29714.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 . . . . . . . . . . . . . . . . . . . . . . . . . 30915.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31015.2 Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

15.2.1 Using Rational Rose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31015.2.2 Using the bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31115.2.3 Using VisualAge Pacbase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

15.3 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31115.3.1 Packages, diagrams, and folder . . . . . . . . . . . . . . . . . . . . . . . . . . 31115.3.2 Class diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31215.3.3 Classes and attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31215.3.4 Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31215.3.5 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31315.3.6 Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31315.3.7 Aggregation and references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31315.3.8 Associatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31415.3.9 Installed bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

15.4 Operating the bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31715.4.1 Importing the Rose model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31815.4.2 Generating the VisualAge Pacbase entities . . . . . . . . . . . . . . . . . 32015.4.3 Completing the imported entities. . . . . . . . . . . . . . . . . . . . . . . . . . 323

Chapter 16. Completing server development . . . . . . . . . . . . . . . . . . . . . . 32516.1 Logical views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

16.1.1 Cruise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32616.1.2 CruiseLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32716.1.3 Reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32716.1.4 Ship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

16.2 Elementary components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32916.2.1 Cruise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32916.2.2 CruiseLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33016.2.3 Reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33216.2.4 Ship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

16.3 Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33516.3.1 Reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33516.3.2 CruiseLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

16.4 Generating. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34016.4.1 Proxy generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Chapter 17. Developing JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34317.1 Preparing the VisualAge environment . . . . . . . . . . . . . . . . . . . . . . . . . . 344

17.1.1 Creating the VisualAge projects . . . . . . . . . . . . . . . . . . . . . . . . . . 34417.1.2 Creating the Java packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Contents ix

17.1.3 WebSphere Test Environment setup . . . . . . . . . . . . . . . . . . . . . . 34617.1.4 Importing the VisualAge Pacbase proxies . . . . . . . . . . . . . . . . . . 348

17.2 Developing the business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34917.2.1 Identifying the business objects . . . . . . . . . . . . . . . . . . . . . . . . . . 34917.2.2 Destination business object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35017.2.3 CruiseLineBusinessObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35417.2.4 ReservationBusinessObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

17.3 Developing commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35917.3.1 Identifying the commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35917.3.2 Destination commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36017.3.3 Cruise line commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36617.3.4 Reservation commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

Chapter 18. Building JSPs and servlets . . . . . . . . . . . . . . . . . . . . . . . . . . 37518.1 Preparing the WebSphere Studio environment . . . . . . . . . . . . . . . . . . . 376

18.1.1 Creating the WebSphere Studio project . . . . . . . . . . . . . . . . . . . . 37618.1.2 Setting versions for the JSP and the application server . . . . . . . . 37618.1.3 Creating the folders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37818.1.4 Customizing the stages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

18.2 Implementing HTML pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38018.3 Developing the JavaServer pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

18.3.1 Employee JSPs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38218.3.2 Customer JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38418.3.3 CommandException.JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

18.4 Developing the DataDeliveryBeans. . . . . . . . . . . . . . . . . . . . . . . . . . . . 38818.4.1 Identifying the DataDeliveryBeans . . . . . . . . . . . . . . . . . . . . . . . . 38818.4.2 Destination DataDeliveryBeans . . . . . . . . . . . . . . . . . . . . . . . . . . 38818.4.3 Cruise line DataDeliveryBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . 38918.4.4 Reservation DataDeliveryBeans . . . . . . . . . . . . . . . . . . . . . . . . . . 391

18.5 Developing the servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39218.5.1 Identifying the servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39218.5.2 Destination servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39318.5.3 GetUniqueDestinationServlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39718.5.4 Cruise line servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40018.5.5 Reservation servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

18.6 Introducing the WAP application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40818.6.1 Adapting the presentation to the WAP . . . . . . . . . . . . . . . . . . . . . 40918.6.2 Developing the WML-based JSPs . . . . . . . . . . . . . . . . . . . . . . . . 40918.6.3 Subclassing the servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41318.6.4 Testing with the WAP application . . . . . . . . . . . . . . . . . . . . . . . . . 415

Chapter 19. Deploying the application . . . . . . . . . . . . . . . . . . . . . . . . . . . 41719.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 . . . . . . . . . 41819.1.2 Creating the required Web application directories . . . . . . . . . . . . 42219.1.3 Deploying files to WAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42319.1.4 Starting the Web application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42519.1.5 Defining servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

19.2 Additional deployment considerations. . . . . . . . . . . . . . . . . . . . . . . . . . 42619.2.1 The e-business application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42619.2.2 Communications monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42719.2.3 Working file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42819.2.4 Error server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

System requirements for downloading the Web material . . . . . . . . . . . . . 432How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436How 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

TrademarksThe following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

Balance®CICS®DB2®DB2 Universal Database™IBM®

IBM eServer™MQSeries®MVS™Perform™RACF®

Redbooks™Redbooks (logo)™SP™VisualAge®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 redbookThis 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 authorJoin 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

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html

Comments welcomeYour 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:

[email protected]

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. 1WLB Building 80-E2650 Harry RoadSan Jose, California 95120-6099

Preface xvii

http://www.redbooks.ibm.com/

http://www.ibm.com/redbooks/


http://www.redbooks.ibm.com/contacts.html

xviii VisualAge Pacbase for e-business Applications

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.

Part 1

© Copyright IBM Corp. 2002. All rights reserved. 1

2 VisualAge Pacbase for e-business Applications

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.1 Definitions and terminologyVisualAge 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 supportUnified 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 ComponentsThe 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-businessVisualAge 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.


http://www.software.ibm.com/ad/

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


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

2.2 Main architecturesDuring 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 architectureThe 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.

Figure 2-1 One-layer architecture

* HTML* GIF/JPEG* MOV/AVI* Javascript* Java Applet

Client Server

HTMLBrowser Files

URL


Two-layer architectureThe 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.

Figure 2-2 Two-layer architecture

HTTP

* HTML* GIF/JPEG* MOV/AVI* Javascript* Java Applet

Client Server

HTMLServer

HTMLBrowser

Chapter 2. VisualAge Pacbase targeted application architecture 9

Two-layer architecture with applets and JDBCAnother 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.

Figure 2-3 Two-layer architecture with applet and JDBC

* HTML* GIF/JPEG* MOV/AVI* Javascript

Client Server

HTMLServer

HTTP

Java Applet

JDBC

Database

HTMLBrowser

Files


Three-layer architecture: applet/servletThe 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.

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

* HTML* GIF/JPEG* MOV/AVI* Javascript

Client Server

HTTP

Java Applet

Java Servlet

JDBC

Application Server

HTMLServer

RMI

RMI

HTMLBrowser

Files

Database


Three-layer architecture: JSP/servletAnother 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.

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.

Client Server

HTTP

Application Server

LegacyJava Bean

Java Servlet

JSPs

HTTP

HTMLBrowser

Files Database

Application Server


2.3 Commonly encountered problemsRegardless 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/middlewareCommunication/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.

PerformancePerformance 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 loadsTraffic 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.


SecuritySecurity 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 integrityData 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 applicationsAnother 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 managementDepending 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 componentsIn this topic we present an overview of the JSPs/servlet main components.


2.4.1 HTML pagesHTML (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 ServletsServlets 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 JavaBeansThe 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 JSPsA 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 proxyThis 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.


Figure 2-6 VisualAge Pacbase proxy is generated

Figure 2-7 VisualAge Pacbase proxy as an interface for the server

2.6 Application architecture overviewIn this topic we provide an overview of the targeted application architecture using VisualAge Pacbase.

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.)

Folder PROXY Java Bean

events

attributesmethods

Generation

Folder

ClientProxy

CommunicationMonitor

FolderServer

ElementaryServers


2.6.1 Introduction to patternsFor 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 patternb. Choosing the application topologyc. Choosing the runtime topology

2. Defining the products

a. Within the development contextb. Within the runtime context

3. Defining the application architecture

a. Development frameworkb. Development standards

2.6.2 Choosing the business patternIn 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 topologyAfter 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.

Figure 2-8 User-to-business application topology

2.6.4 Choosing a runtime topologyThe 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.

Presentationsynchronous /asynchronous

ApplicationApplicationsynchronous

Read/Write data

Application nodecontaining new ormodified components

Application node containingexisting components withno need for modification orwhich cannot be changed


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 mappingWe 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 productsThe 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 productsThe 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 architectureWe 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 usedTo 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 frameworkDesigning 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 patternThe 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 approachNext we outline a brief development approach.

IntroductionWe 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.

Figure 2-9 Framework overview

Model: Command bean and business objectsIn 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.

inherits from

implements

Generic request for services

Specific request for services

Return of data

Constraint for data deliver

Request for presentation

Request for specific data

CommandBusiness

ObjectProxy

ControllerServlet

XBusinessObjectXCommandBean

DataDeliveryBean

XDataDeliveryBeanJSPs

1HttpRequest

HttpResponse

XControllerServlet

4

2

3

56

7

1

2

3 4

5

6

7

,


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: JSPsWhen 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: servletTo 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 handlingAs 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 standardsOur 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 standardsThe 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 standardsThe 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 standardsThe 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 standardsThe 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 standardsThe 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 standardsThe 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 standardsWe 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 architectureIn 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 MiddlewareThe 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 ListenerThe 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 monitorThe 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.


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


3.1 VisualAge Pacbase 3.0VisualAge 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 WorkbenchThe 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 repositoryThe 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 toolsProviding 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 RoseThe 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 JavaVisualAge 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 StudioWebSphere 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/


http://www.ibm.com/software/ad/vaJava/

http://www.ibm.com/software/webservers/studio/


3.2.4 About WebSphere Application ServerWebSphere 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 DatabaseDB2 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 MQSeriesMQSeries 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/


http://www.ibm.com/software/webservers/appserv/

http://www.ibm.com/software/data/db2/udb/

http://www.ibm.com/software/ts/mqseries/

3.3 Tools integrationEarlier, 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 PacbaseRational 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 JavaRational 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 StudioWebSphere 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 WASVisualAge 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 WASTwo 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 DB2Two 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 environmentFigure 3-2 summarizes the development environment.

Figure 3-2 Summary of development environment

ANALYSISAND

DESIGNAnalysis Model

-----> Design Model

VisualAge Pacbase

RationalRose

Business ComponentsFolder

Database

WebSphereText

Environment

JSPMonitor

VAP TestTool

Servlet JSP Proxy

HTML,JSP

Servlet,JavaBean

WebSphereStudio

VisualAgefor Java

Servlet

JavaBean

Proxy

IMPLEMENTATION

TESTING


Figure 3-3 summarizes the runtime environment.

Figure 3-3 Summary of runtime environment

DEVELOPMENT

VisualAge PacbaseBusiness Application

WebSphere Studio

HTML Browser

HTTPWebSphere

Application Server

Database

DEPLOYMENT

VisualAgePacbase

VisualAgefor Java

DB2

FoldersElementary Components

DB2

VA

P M

idd

lew

are

MQ Series

(Socket)

HTMLJSPs

ServletsJavaBeans

Proxies


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


4.1 Installation/setup: VisualAge Pacbase 3.0 repositoryIn 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 considerationsVisualAge 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 installationThe 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 softwareFigure 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 databaseIn 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 databaseInstalling 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 installationBefore 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 installationAfter 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 installFigure 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 installFigure 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 resultsThe 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 WorkbenchIn 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 InstallationIn 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 installationIn 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 WorkbenchesThis 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 managerIn 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 toolsIn 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 featureThis 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 environmentThe 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 pathTo 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 projectsThe 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.

Making VisualAge Pacbase Java environment a featureThe 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.

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.


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 middlewareThe 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 DLLsDuring 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 considerationsFor 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 offd:cd A\RedBookVapbVapGateway -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 administrationIn 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 WorkbenchAfter 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 iconYou 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 menuYou 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=08192MONITOR=DECOMDMWARE=SOCKETMWAREADDRESS=127.0.0.1 7030MWTIMEOUT=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 barThe VisualAge Pacbase administrator Workbench menu bar is shown in Figure 4-63.

Figure 4-64 The administrator Workbench menu bar

File optionsWhen 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 optionsThe 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 optionsThe 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 browserThe 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 browserThe 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

SelectedThe 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.

WorkspaceThe 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.

HelpThe 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 WorkbenchFigure 4-70 shows the basic tabs of the administrator Workbench.

Figure 4-70 VisualAge Pacbase administrator Workbench tabs


DatabasesThe 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 linesWhen 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.

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.

Command lines atbeginning 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 atend of jobstream


4.4.5 ProfilesVisualAge 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/TransferThe 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 setDefining 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 criteriaTo 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 criteriaTo 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 criteriaTo 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 criteriaTo 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 criteriaThis 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 UsersThe 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 barThe 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 controlsVisualAge 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 controlsValidity 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 controlsInitialization 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 administrationBase 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 barThe Menu Bar contains the same options and looks similar to that used for site administration.

4.6.2 Base administration tab optionsBase 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 relationshipsMeta 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.

LibrariesThe 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 aidsInput 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 utilitiesThis 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 releasesVisualAge 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 releaseChanges 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.


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


5.1 The Workbench in generalTo 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 onThe 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 WorkbenchAfter 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 barOn 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 barOut 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 menuBy 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 menuThis 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 menuTo 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 iconsA 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 buttonThe 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 buttonThe 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 buttonThe 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 iconsThe 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... buttonThe 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 buttonThe 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 buttonThe 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 managerIn 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 tabThis 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 listThis 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 changesDo 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 allInstead 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 tabWhenever 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 LibrariesThis 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 tabThe 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 managerVisualAge 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 linesFigure 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 buttonClicking 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 buttonThis will save the command lines you have entered.

Submit and Save buttonThis 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 JCLThis 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 conceptsEvery 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 WorkbenchWe will now explain the tabs in the e-business Workbench. These tabs represent different VisualAge Pacbase 3.0 entities.

5.5.1 Data elementsA 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 windowWhen 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 tabThis 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 ControlsValue 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 SegmentsA 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 windowYou 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 tabYou 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


5.5.3 ProgramsThe 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

Structured codeThe 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

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

Button Function

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.


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

OperatorsVisualAge 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.


Condition typesCondition 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.

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.

Operator Function Usage


Table 5-3 Relative positioning condition types

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 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.

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


As in every other programming language VisualAge Pacbase 3.0 has programming conditions as shown in Table 5-5.

Table 5-5 Programming conditions

*C BS ABS RBS P

Places code before Begin Server (BS)Replaces code of Begin Server (BS)Places code behind Begin Server (BS)


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.

Condition type Condition line Explanation


Creating a macroWhen 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

ParametersA 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:

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’.



� 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 tabThe 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 viewsA 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 definitionLike 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 tabHere you will find the definition you produced with the SmartGuide.

Composition tabThe 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

Extract Methods tabAn 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.

5.5.5 Elementary componentsAn 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.

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.

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.


Creating an elementary componentThe 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, shown in Figure 5-45.

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 tabIn 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 tabIn 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 shown in Figure 5-46.

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

Table 5-8 Data element transfer fields

Structured code tabThe 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 codeThe 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.

Source identifier Target identifier

Portid Portid

Source field Target field

Portnm Portnm

Ctrynm Ctrynm


Figure 5-51 Elementary component


Macro calls tabAfter 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 applicationThe 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 fileThe 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 fileWe 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 applicationWe 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 tabBy using the SmartGuide we have filled in all the things we needed on our definition screen.

e-error ServerHere we give our error server its generation details. We call the error segment we created before.

GenerationOur 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 FileHere 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 areaThis is not used in our redbook sample application.

e-databaseHere 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 FoldersA 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 folderWe 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 monitorsThe 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� Type of code to generate: VisualAge COBOL


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


6.1 ReusabilityUsing 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 componentsRe-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 reusabilityThe 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 considerationsData 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 considerationsDocumentation 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 considerationsVisualAge 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 considerationsEntities 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 LibrariesLibraries 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.


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.

STD

VR2

SY1

AP1

VR1

SY2

AP2

MAC

DTA

Development

Administrative


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

STD

VR2

SY1

AP1

VR1

SY2

AP2

MAC

DTA

Development

Administrative


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 repositoryThe 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 entitiesEntities 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 elementsData 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 segmentsCollections 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 blocksThe 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 entitiesVisualAge 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 DescriptionsDescriptive 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 facilityThe 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 aidEvery 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 entitiesProcessing 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-businessThe 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 macrosThe 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 ReportsThe 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-referencesCross-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-referencesCross-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 considerationsCross-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 considerationsBoth 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.

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.

Scope of your default viewof the library hierarchy

Sign-on library

STD

DTA

VR2

SY1

AP1

VR1

SY2

AP2

MAC


6.6 PortabilityPortability, 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 contentVisualAge 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 applicationsThe 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.


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


7.1 OverviewFor 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 pathsIn this section we describe the forward and backward development paths.

7.2.1 Forward development pathThe forward development path is a top-down approach.

7.2.2 Analysis and designThis 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, navigationFollowing 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 deploymentAfter 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 pathThe 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 designAnalysis and design are incorporated iteratively in a prototyping approach to development.

Construction: presentation and navigationThis 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 componentsThis 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 componentsFrom this point, we return to the client-side:

8. Developing service components, using the VisualAge Pacbase proxy

Construction: refinement9. Refining the presentation and navigation

Testing and deploymentAfter 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 applicationThis section discusses the required components, the relation to the UML modeling, and the use of the Rational Rose Toolkit.

7.3.1 Required componentsImplementing 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 ToolkitRational 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 implementationThis 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 nodeA 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 systemThe 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 contextThere 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 ResultsAfter 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.

7.5 Client-side implementationThis topic focuses on the client-side steps to implement navigation, presentation, and access to services.

7.5.1 Developing services componentsServices 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.

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.


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 presentationPresentation 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 navigationWebSphere 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 TestingVisualAge 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 summaryFigure 7-1 summarizes the development process using VisualAge Pacbase.

Figure 7-1 Development process summary

Server Developer DatabaseAdministrator

Business components, folder, ...

Database

Application Assembler Bean Provider

Proxy

Page Producer

HTML pages, JSP

Data Delivery Bean

Servlet

Command Beans

Data Bean


7.7 Team considerationsFigure 7-2 summarizes the distribution of work among e-business development teams.

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

BusinessSubsystem

PersistancySubsystem

FunctionalSubsystem

WorkflowSubsystem

UI Subsystem

Navigation Commands

Page Producer Application Assembler

Bean Provider Server Developer

DatabaseAdministrator

HTML, JSP,...

Servlets

Elementary components, folder, ...

Database

Beans

Proxy


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 DeploymentFigure 7-3 describes how the e-business application components are deployed.

Figure 7-3 Deployment

WebSphere Application Server

Elementary components, folder, ...

Database

ProxyHTML, JSP JavaBeans

Servlet

Web browser (no deployment) VisualAge Pacbase

business application

Database


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


8.1 Logical viewThe 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).

8.2 Elementary componentAn 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 updateA 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.

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.


SelectionThis 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 serviceA 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 lockA 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 applicationThe 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.

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 e-business application.

Note: The e-business application is considered to be purely a technical component which groups a set of programs that can call each other.

Chapter 8. Building services and data access 215

8.3.1 Error serverThe 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 monitorThe 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 FolderA 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 ManagerFor 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 viewConsidering 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 considerationsHere 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 environmentA 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 fileThe 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 fileThe 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 proxyWe will now discuss the steps and the sequence to follow in order to generate a VisualAge Pacbase proxy.

The e-business applicationThe 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 monitorAfter 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 viewThe 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 methodExtract 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 folderThe 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

NodesAccess 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.


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.

Elementary componentThe 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 nodesIn 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.

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.

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.


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 folderWe 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 viewsA 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 applicationThe 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.


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


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).

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.

VisualAge Pacbase Repository

Folder

Nodes Elementary Component/Logical View . . .

Folder Proxy

Elementary Proxy

Description FileVisualAge Pacbase

Java GeneratorJava File

Generator Import

Input Output

VisualAge for Java Repository


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 featuresThis section focuses on the Java implementation of the VisualAge Pacbase proxy, and provides information on the main features.

9.2.1 OverviewThe 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 proxiesThis section introduces the Java hierarchy for the VAP proxy.

Hierarchy overviewFigure 9-2 shows the Java generic proxy classes hierarchy.

Figure 9-2 Java proxy classes hierarchy

ProxyLvThis class is the abstract root class of all generated proxy classes.

HierarchicalProxyLvThis class is the abstract parent class of dependent proxies and folders. It provides the facility for managing proxy hierarchies.


DependentProxyLvThis class is the abstract parent class of generated dependent proxies.

FolderThis class is the abstract parent class of generated folders.

ReferenceProxyLvThis class is the abstract parent class of generated reference proxies.

Proxy related generated classesWhen 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

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.

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.

ShipProxyUpdateTableModel

PacbaseUpdateTableModel

Class used to represent a 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

9.2.3 Public services of generated proxiesThis section briefly describes the main public services that are generated when generating a VAP proxy.

Main local services for a folder proxyNot 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.

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.

ShipProxyUpdateTableModel

PacbaseUpdateTableModel

Class used to represent updated rows of a SHIP node.

ShipSelectionCriteriaBeanInfo

SimpleBeanInfo Bean information about the ShipSelectionCriteria class.


Table 9-3 Folder proxy local services

Main local services for a dependent or reference proxyNot 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.

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.


Table 9-4 Dependent or reference proxy local service

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

Table 9-5 Mapping between folder proxy and server

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.

getUpdatedInstancesTableModel() Gets the UpdatedInstancesTableModel 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.

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

Folder 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.

readAllChildren(RacineData)readAllChildrenFromCurrentInstance()

Reads some or all hierarchical dependent instances based on the parameter. This kind of all inclusive retrieval must be specified on the server side.

readFirstChildren(RacineData)readFirstChildrenFromCurrentInstance()

Reads some or all first level hierarchical 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.

setMaximumNumberOfRequestedInstances(int)

Sets the maximum number of requested 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.

Folder proxy services Server


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

Table 9-6 Mapping between dependent proxy and server

Mapping between reference proxy and serverTable 9-7 shows what happens on the server for specific reference node proxy services.

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)readFirstChildrenFromCurrentInstance()

Reads some or all first level hierarchical dependent instances of the parameter.

readInstance() Reads one instance.

readInstanceWithFirstChildren() Reads one instance with all its first level hierarchical dependent instances.





Sets the maximum number of requested instances to use as parameter when selecting instances

setUserServiceCode(String) Sets the user service code to use when calling a user service.



Table 9-7 Mapping between reference proxy and server

More about generated methodsThe 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()

Reference node proxy services Server

readInstance() Reads one instance.





Sets the maximum number of requested instances to use as parameter when selecting instances.



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 dynamicsIn 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.

Figure 9-3 Sample proxy hierarchy

R o o t P r o x y

F i r s t D e p P r o x y

S e c o n d D e p P r o x y

r o o t p r o x y

f i s r t l e v e l d e p e n d e n t p r o x y

s e c o n d l e v


Retrieving root instancesWe 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.

Figure 9-4 Proxy dynamics: retrieving root instances

Retrieving dependent instancesThis 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 1We 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.

FirstDepProxy

SecondDepProxy

RootProxy

Rows: emptyDetail: empty



FirstDepProxy

SecondDepProxy

RootProxy

Rows: listDetail: empty



FirstDepProxy

SecondDepProxy

RootProxy

Rows: list

Detail: rootA



selectInstances() getDetailFromDataDescription(rootA)


Figure 9-5 Proxy dynamics: node by node retrieval, option 1

Node by node retrieval, option 2This 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.

Figure 9-6 Proxy dynamics: node by node retrieval, open 2

FirstDepProxy

SecondDepProxy

RootProxy

Rows: listDetail: rootA



FirstDepProxy

SecondDepProxy

RootProxy

Rows: list

Detail: rootA

Rows: childrenForRootADetail: empty


readFirstChildrenFromCurrentInstance()

FirstDepProxy

SecondDepProxy

RootProxy

Rows: list

Detail: rootA



FirstDepProxy

SecondDepProxy

RootProxy




readNextPage()


Retrieving all dependent instances at onceThis 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.

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.

FirstDepProxy

SecondDepProxy

RootProxy

Rows: list

Detail: rootA



FirstDepProxy

SecondDepProxy

RootProxy

Rows: list

Detail: rootA



FirstDepProxy

SecondDepProxy

RootProxy


Rows: childrenForRootADetail: childOne

Rows: childrenForChildOneDetail: empty

readAllChildrenFromCurrentInstance() getDetailFromDataDescription(rootA)


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


10.1 Useful patternsSoftware 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 patternThis section introduces the singleton pattern, and provides a Java implementation for this pattern.

IntroductionOften 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 e-business application.

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 JavaPure 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 instanceprivate static Singleton cvInstance = null;

//constructorprivate Singleton() {// ...

}

// Return the unique instance of this classprivate static Singleton getInstance() {

if(cvInstance == null) {cvInstance = new Singleton();//lazy initialization

} return cvInstance;

}

//Technical or business instance methodprivate String getNewIdentifier() {

//...}

//Static accessor to the preceding instance methodpublic static String getIdentifier() {

return getInstance().getNewIdentifier();}

}

10.1.3 Factory patternA 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 instanceprivate static Singleton cvInstance = null;

//constructorprivate 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 patternThe 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 frameworkThe 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 interfaceThe 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.

Figure 10-1 Command state diagram

10.2.2 CommandExceptionThe 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() {

NEW INITIALIZED EXECUTED

setXxx getXxx

ExecuteList requiredsetXxx

Reset

Instantiation


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 CommandFactoryThe 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 processThe 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 frameworkBusiness 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 interfaceThe 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 BusinessObjectFactoryThe 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 middlewareprivate final static boolean cvUsingGateway = false;

//default locations file nameprivate final static String cvLocationsFile = "vaplocat.ini";

//default is local gateway


private final static String cvHost = "127.0.0.1";

//default gateway port is 5647private 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(); //castingif (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 processThe 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 commandA 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 summaryFigure 10-2 summarizes the Model layer.


Figure 10-2 Model layer summary

Command Factory

Business Object Factory

Proxy

Request for Service

Command

XCommand

Instantiation

Implements

XBusinessObject

Business Object

Instantiation

Implements

O.. O..


Chapter 11. Creating presentation with JSPs

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). 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.

11

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 pagesJavaServer 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 pagesThe 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 directivesA 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 directiveThe 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 directiveThe 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 scriptingScripting covers the following tags:

� Declarations� Scriptlets� Expressions

DeclarationsA 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..;}%>

ScriptletsScriptlets 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

ExpressionsExpressions 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 objectsWithin 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

11.2.4 CommentsYou 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 --%>

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.5 JSP actionsThe 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 tagThe 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 tagOnce 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 tagYou 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 tagsWebSphere 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 presentationPresentation 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).

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 processThe 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 guidelinesHere 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 DataDeliveryBeanThe 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 JSPA 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 JSPsBuilding 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 architectureFigure 11-1 shows the impact of WAP technology relative to our e-business architecture.

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.

WAP Gateway

HTMLBrowser

Command

BusinessObject

Proxy

ServletJSP

WML-basedJSP

WAP Servlet

DataDeliveryBean

WebSphere Application Server

HTTP

HTTPWAP


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


12.1 Introduction to Java servletsServlets 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 flowServlets 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 APIThe 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 managementWhen 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.

ServletContextA 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.

CookiesCookies 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 SessionThe 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 navigationNavigation 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 processThe 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 GranularityDesigning 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 navigationThe 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.

Figure 12-1 Control mechanism: servlet/command/JSP

12.2.4 Non JSP resulting servletsSince 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).

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.

HTML pageor JSP

JSP

ControllerServlet Command

BusinessObject

DataDeliveryBean

1

2

3

45


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.

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.

Servlet BForward

Servlet B

Browser

Browser

Include

Content returnedto Browser

Servlet A

Servlet A

Servlet B

Servlet B

Content returned to Browser


12.2.5 A generic controller servletWe 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 ApplicationSystem.out.println(throwable.getMessage());// Prints a message to the WS3.0 console windowlog(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.


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


13.1 Using the VisualAge Pacbase Test ToolThe 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 implementationProxies generationCommunication 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 toolFor 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 toolWe 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-pluswhere <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 (vaplocat.ini file)

No default value, mandatory when not using gatewayHost and gatewayPort parameters

gatewayHost IP address for the VisualAge Pacbase gateway in use

Empty, meaning we do not use any gateway but instead we use the middleware DLLs directly

gatewayPort Port for the VisualAge Pacbase gateway in use

No default value, mandatory when gatewayHost parameter is not the default

gatewayPath Path for the gateway executable, if it is a local gateway. Can be used to automatically launch the gateway if it is not running.

No default value

traceFile Name and path of the trace file.

<Runtime "user.home" directory> + "Traces.txt"If no trace is desired, then explicitly write traceFile=(that means empty)

generatedProxiesPackage Package that contains the generated proxies when there is only one package(as a result, the package is added to the tool classpath)

No default value

generatedProxiesPackage.n Package that contains the 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)

No default value


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.1gatewayPort=5647generatedProxiesPackage.1=com.cruise.cruise.proxiesgeneratedProxiesPackage.2=com.cruise.destination.proxiesgeneratedProxiesPackage.3=com.cruise.ship.proxies

13.1.3 Running the toolThis 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 shown in Figure 13-2.

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 toolsDuring 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 applicationThis 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 componentsIn 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 JSPsHTML 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.


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

We give a concrete example of such a deployment in Part 2 as we deploy the VisualAge Cruise Lines sample application.

Description File extension Directory path

HTML documents and related files

.html, .shtml, .jhtml, .gif,

.jpg, .au, and so forthThe Web Application document root (or under the HTTP server root)

JavaServer Pages .jsp The Web Application document root

AdminDomain

one

many

Node

ApplicationServers

ServletEngine

Servlets JSPs HTML

VirtualHost

Web Applications


13.3.3 Deploying servlets and JavaBeansServlets 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

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 VisualAge Cruise Lines sample application.

13.4 Runtime testingWhen 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.

Description File extensions Directory paths

Servlets, JavaBeans, and other Java classes

.class, .jar, .ser The application class path or the 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


Part 2 VisualAge Pacbase Cruise Lines sample application


Part 2


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


14.1 VisualAge Cruise Lines backgroundVisualAge 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 requirementsVisualAge 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 considerationsThis 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 ObjectsThe 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:

� Cruise Line ID, the system assigned number to uniquely identify the cruise 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

� Cruise Line ID, the system assigned number to uniquely identify the cruise 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 RelationshipsIn 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 implementationIn 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.

Figure 14-5 Data implementation structure

14.4 Processing considerations and implementationOur 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.

(folder)

Arrival

Departure

CRUISE

Reference nodes

fordestination

(Dependent node)

(Dependent node)SHIP

CRUISE LINE

RESERVATIONS

(folder, single node)

DESTINATION

CRUISE (Reference node)


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 reservationIn 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 managementIn 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


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


15.1 OverviewThe 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 ApproachThe 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 RoseDeveloping 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 bridgeOnce 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 PacbaseAfter 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 ConstraintsAlthough 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 folderVisualAge 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 diagramsClass 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 attributesRegarding 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 OperationsThere are no constraints for operations except those imposed by the UML implementation in Rational Rose.


15.3.5 InheritanceDuring 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 RelationsIn 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.

Figure 15-1 Orienting relations

15.3.7 Aggregation and referencesAggregation 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.

CRUISE LINE SHIP

NO

CRUISE LINE SHIPYES

1..* 1..1


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.

Figure 15-3 Cardinality constraints for references

15.3.8 AssociativesAssociatives 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.

A B

A

B1..* 1..1

0..* 0..1

A B

A

B1..* 1..1

0..* 0..1


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.

Figure 15-4 Resolving many-to-many relations

A B

A

B

1..1 1..1

0..* 0..*

C


15.3.9 Installed bridgeThe 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 bridgeIn 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 modelThe 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 entitiesRun 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 entitiesReview and complete the created application components in the following order:

1. Data elements2. Logical views3. Elementary components4. Folders5. 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.


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


16.1 Logical viewsWe 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 CruiseCruises are actually blocks of tickets for resale by VisualAge Cruise Lines.

DefinitionWe defined our logical view as follows:

� Code: Cruise� Label: Cruise� Short Code: BT05

CompositionOur composition is shown in Figure 16-1.

Figure 16-1 Composition of Cruise


16.1.2 CruiseLineCruise lines are the companies that provide blocks of tickets to VisualAge Cruise Lines for resale.


� Code: CruiseLine� Label: Cruise Line� Short code: BT01


Figure 16-2 Composition of CruiseLine

16.1.3 ReservationReservation represents the purchase of one or more tickets for a cruise by the customer.


� Code: Reservation� Label: Reservation� Short Code: BT03


Chapter 16. Completing server development 327

Figure 16-3 Composition of Reservation

16.1.4 ShipShips are the vessels used to carry passengers.

DefinitionWe defined our logical view as follows.

� Code: Ship� Label: Ship� Short Code: BT04


Figure 16-4 Composition of Ship


16.2 Elementary componentsWe have built an elementary component for every logical view.

16.2.1 CruiseHere we supplement the logical view Cruise.

DefinitionWe defined our elementary component as follows:

� Code: Cruise� Label: Cruise� Short Code: EC1400� Component Type: Hierarchical� COBOL program ID: PGMCRU� Type of code to generate: VisualAge COBOL


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

Our other fields (non-key) were filled in as shown in Table 16-2.

Table 16-2 Field transfer Cruise

16.2.2 CruiseLineHere we supplement the logical view CruiseLine.

DefinitionWe defined our elementary component as follows:

� Code: CruiseLine� Label: CruiseLine� Short Code: EC1200� Component Type: Hierarchical� COBOL program ID: PGMLIN� Type of code to generate: VisualAge COBOL


Source Target

LINEID LINEID

REGIST REGIST

CRUSID CRUSID

LINEID LINEID

CRUSNM CRUSNM

DPPRID DPPRID

ARPRID ARPRID

NBAVTK NBAVTK

NBRES NBRES

FRETXT FRETXT


Figure 16-6 Composition for Reservation

Our figure does not show the data element transfer. Our key filed transfers were filled as shown in Table 16-3.

Table 16-3 Key transfer CruiseLIne


Table 16-4 Field transfer CruiseLine

Source Key

LINEID LINEID

Source Key

LINENM LINENM

CTRYNM CTRYNM


16.2.3 ReservationHere we supplement the logical view Reservation.

DefinitionWe defined the elementary component Reservation as follows:

� Code: Reservation� Label: Reservation� Short Code: EC1100� Component Type: Hierarchical� COBOL program ID: PGMRES� Type of code to generate: VisualAge COBOL

CompositionOur 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


Table 16-6 Field transfer Reservation

16.2.4 ShipHere we supplement the logical view Ship.

DefinitionWe defined our elementary component Ship as follows:

Code: ShipLabel: ShipShort Code: EC1300Component Type: HierarchicalCOBOL program ID: PGMSHPType of code to generate: VisualAge COBOL


Source Target

RESID RESID

Source Target

CRUSID CRUSID

NBTIK NBTIK


Figure 16-8 Composition for Ship

Our figure does not show the data element transfer. Our key field transfers were filled as shown in Table 16-7.

Table 16-7 Key transfer Ship


Table 16-8 Field transfer Ship

Source Target

REGIST REGIST

Source Target

SHIPNM SHIPNM

FRETXT FRETXT


16.3 FoldersWe 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 ReservationThe Reservation folder only contains the Reservation node.

DefinitionWe have defined the Reservation folder as follows:

� Code: Reservation� Label: Reservation� Short Code: RESERV� e-business application short code: CruiseApplication� COBOL program ID: RESERV� Type of code to generate: VisualAge COBOL� Package code: com.cruise.reservation.proxies

Our node definition looks like Figure 16-9.

Figure 16-9 Properties for Reservation


16.3.2 CruiseLineWe 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 shown in Figure 16-10.

Figure 16-10 Folder composition for CruiseLine

We defined CruiseLine as follows:

� Code: CruiseLine� 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 GeneratingThere 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 generationThe 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.


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


17.1 Preparing the VisualAge environmentThis 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 projectsWe 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 packagesIn 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 setupThere 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 classpathTo 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 versionVisualAge 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.webappwhere <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 proxiesDuring 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 objectsThis 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 objectsIn 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 objectThe 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 destinationThe 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 destinationdetail().setPortid(getIdentifier(destinationPortName)); detail().setPortnm(destinationPortName); detail().setCtrynm(destinationCountry);//create the instancecreateInstance();//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 destinationThe 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 destinationPortIdselectionCriteria().setPortid(destinationPortId);readInstance();//modify the instancedetail().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 destinationsThe method getDestinations provides a service to retrieve all destinations, sorted by name is as follows:

public DataDescriptionVector getDestinations() throws LocalException, ServerException {

//for local sortsetDataComparator(new DestinationDataComparator());//select allselectInstances();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 classThe 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 keyThe 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 destinationPortIdselectionCriteria().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 selectionCriteria() method.

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 CruiseLineBusinessObjectThe CruiseLineBusinessObject class is shown in Figure 17-5.

Figure 17-5 CruiseLineBusinessObject class

This class extends the generated CruiseLineProxy class and implements the BusinessObject interface.


Getting all cruise linesThe 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 sortsetDataComparator(new CruiseLineDataComparator());//select allselectInstances();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 usedsetLocalSort(false);//use the appropriate Extract methodsetExtractMethodCode("SORTBYNAME");//select allselectInstances();return getRows();

}

Getting all cruises for a cruise lineThe 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 childrenselectionCriteria().setLineid(cruiseLineId);readInstanceWithAllChildren();//loop on depending ships to get all depending cruisesEnumeration 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 selectionCriteria() method.

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 cruiseThe 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 ReservationBusinessObjectThe ReservationBusinessObject class is shown in Figure 17-6.

Figure 17-6 ReservationBusinessObject class

This class extends the generated ReservationProxy class and implements the BusinessObject interface.

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 reservationdetail().setCrusid(cruiseIdentifier);//cruise identifier


detail().setNbtik(numberOfTickets);//number of reserved ticketsdetail().setResid(reservationIdentifier);//reservation identifier//create the instancecreateInstance();//Update the folder (COMMIT)updateFolder();

}

17.3 Developing commandsThis 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 commandsThe 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 commandsThis section focuses on commands related to employee tasks when managing destinations.

GetDestinationsCommandThe 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.DestinationBusinessObject");

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;

}

GetUniqueDestinationCommandThe GetUniqueDestinationCommand class is shown in Figure 17-8.


Figure 17-8 GetUniqueDestinationCommand class

The execute() method creates a new instance of DestinationBusinessObject, calls the getDestination service, and sets the destination property:

public void execute() throws CommandException {DestinationBusinessObject destinationBO = null;DestinationData dd = null;try {


dd = destinationBO.getDestination(getDestinationPortId());} catch (Throwable t) {


throw new CommandException(t);}setDestination(dd);

}

ModifyDestinationCommandThe ModifyDestinationCommand class is shown in Figure 17-9.

Figure 17-9 ModifyDestinationCommand class


The execute() method creates a new instance of DestinationBusinessObject, and calls the modifyDestination service:

public void execute() throws CommandException {DestinationBusinessObject destinationBO = null;try {


destinationBO.modifyDestination(getDestinationPortId(), getDestinationPortName(), getDestinationCountry());

} catch (Throwable t) {throw new CommandException(t);

}}

AddDestinationCommandThe 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:

public void execute() throws CommandException {if (getPhase().equals("one")) {

//do nothing} else {

//create and save the new destinationDestinationBusinessObject destinationBO = null;try {


destinationBO.addDestination(getDestinationPortName(), getDestinationCountry());


}}

}

17.3.3 Cruise line commandsThis section focuses on commands related to customer tasks when selecting a cruise.

GetCruiseLinesCommandThe GetCruiseLinesCommand class is shown in Figure 17-11.

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.


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:

public void execute() throws CommandException {CruiseLineBusinessObject cruiseLineBO = null;DataDescriptionVector ddv = null;try {

cruiseLineBO = (CruiseLineBusinessObject) BusinessObjectFactory.createInstance("com.ibm.redbooks.sg246201.cruiselines.CruiseLineBusinessObject");

ddv = cruiseLineBO.getCruiseLines();} catch (Throwable t) {

throw new CommandException(t);


}setCruiseLines(toArray(ddv));

}

GetCruisesCommandThe GetCruisesCommand class is shown in Figure 17-12.

Figure 17-12 GetCruisesCommand class


The execute() method creates a new instance of CruiseLineBusinessObject, calls the getCruises service, and sets the cruises property in an array:

public void execute() throws CommandException {CruiseLineBusinessObject cruiseLineBO = null;Vector v = null;try {


v = cruiseLineBO.getCruises(getCruiseLineId());} catch (Throwable t) {

throw new CommandException(t);}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 arrayDataDescription[] 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 itCruiseDataDeliveryBean cddb = new CruiseDataDeliveryBean();//cruise line informationcddb.setCruiseLineCountry(cruiseLineData.getCtrynm());...//ship informationcddb.setShipRegistry(shipData.getRegist());...//cruise informationcddb.setId(cruiseData.getCrusid());...cdba[index] = cddb;index++;

}return cdba;

}


GetCruiseDetailCommandThe GetCruiseDetailCommand class is shown in Figure 17-13.

Figure 17-13 GetCruiseDetailCommand class


The execute() method creates a new instance of CruiseLineBusinessObject, calls the getCruise service, and sets the returned cruiseData, shipData, cruiseLineData, arrivalData, and departureData properties:

public void execute() throws CommandException {CruiseLineBusinessObject cruiseLineBO = null;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 commandsThis section focuses on commands related to customer tasks when booking a cruise.

BookCruiseCommandThe 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:

public void execute() throws CommandException {//create and save the new reservationReservationBusinessObject reservationBO = null;int reservationId = 0;try {

reservationBO = (ReservationBusinessObject) BusinessObjectFactory.createInstance("com.ibm.redbooks.sg246201.reservation.ReservationBusinessObject");

reservationId = reservationBO.computeIdentifier(getCruiseIdentifier());reservationBO.addReservation(getCruiseIdentifier(),

getNumberOfTickets(), reservationId);} catch (Throwable t) {

throw new CommandException(t);}setReservationId(reservationId);

}


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


18.1 Preparing the WebSphere Studio environmentThis 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 projectWe 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 serverWebSphere 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 foldersTo 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 stagesWebSphere 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_app\web

servlet d:\IBMVJava\ide\project_resources\IBM WebSphere Test Environment\hosts\default_host\default_app\servlets


Figure 18-3 shows the resulting publishing stage, WebSphere Test Environment.

Figure 18-3 WebSphere Test Environment publishing page

18.2 Implementing HTML pagesThis 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 pagesThis 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 JSPsThis section provides information on the following JSPs we developed for the employee activities:

� DestinationsCatalog.jsp� DestinationAdding.jsp� DestinationDetail.jsp

DestinationsCatalog.jspThe 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.GetUniqueDestinationServlet?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.jspThe 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.jspThe 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" value="<jsp:getProperty name="destinationDataDeliveryBean" property="destinationCountry"/>"><BR><INPUT type="hidden" name="code" value="<jsp:getProperty name="destinationDataDeliveryBean" property="destinationPortId"/>"><BR>

18.3.2 Customer JSPsThis section provides information on the JSPs we developed for the customer activities:

� CustomerHomePage.jsp


� CruisesList.jsp� CruiseDetail.jsp� Confirmation.jsp

CustomerHomePage.JSPThe 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.JSPThe 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.JSPThe 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.JSPThe 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" class="com.ibm.redbooks.sg246201.cruiselines.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.JSPCommandException.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 DataDeliveryBeansThis section provides information on how we developed the DataDeliveryBeans for the VisualAge Cruise Lines sample application.

18.4.1 Identifying the DataDeliveryBeansDataDeliveryBeans 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 instanceArray 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 DataDeliveryBeansThis section focuses on DataDeliveryBeans related to employee tasks when managing destinations.

DestinationArrayDataDeliveryBeanThe 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.

DestinationDataDeliveryBeanThe 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

In our VisualAge Cruise Lines sample application, the DestinationDataDeliveryBean class is populated by the GetUniqueDestinationServlet class and is used by the DestinationDetail.jsp page.

18.4.3 Cruise line DataDeliveryBeansThis section focuses on DataDeliveryBeans related to customer tasks when selecting a cruise.

CruiseArrayDataDeliveryBeanThe 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();}

In our VisualAge Cruise Lines sample application, the CruiseArrayDataDeliveryBean class is populated by the GetCruisesServlet class and is used by the CruisesList.jsp page.

CruiseDataDeliveryBeanThe 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.

CruiseLineArrayDataDeliveryBeanThe 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)

In our VisualAge Cruise Lines sample application, the CruiseLineArrayDataDeliveryBean class is populated by the GetCruiseLinesServlet class and is used by the CustomerHomePage.jsp page.

18.4.4 Reservation DataDeliveryBeansThis section focuses on DataDeliveryBeans related to customer tasks when booking a cruise.

ReservationDataDeliveryBeanThe 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

In our VisualAge Cruise Lines sample application, the ReservationDataDeliveryBean class is populated by the BookCruiseServlet class and is used by the Confirmation.jsp page.


18.5 Developing the servletsThis section provides information on how we developed the controller servlets for the VisualAge Cruise Lines sample application.

18.5.1 Identifying the servletsA 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 servletsThis section focuses on servlets related to employee tasks when managing destinations.

GetDestinationsServletThe 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 commandexecuteCommand();//populates the dataDeliveryBeanDestinationArrayDataDeliveryBean dadd = new

DestinationArrayDataDeliveryBean();dadd.setDestinationDataArray(((GetDestinationsCommand)

getCommand()).getDestinations());//put this DataDeliveryBean in the scope of the requestreq.setAttribute("destinationArrayDataDeliveryBean", dadd);//forward the request to the next JSPtry {

getServletContext().getRequestDispatcher("/jsp/DestinationsCatalog.jsp").forward(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.


AddDestinationServletThe AddDestinationServlet class is shown in Figure 18-21.

Figure 18-21 AddDestinationServlet class


protected String getCommandClassName() {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:


public void performTask(HttpServletRequest req, HttpServletResponse res) {//get the request parametersString phase = (String) req.getParameter("phase");//reset the commandgetCommand().reset();((AddDestinationCommand) getCommand()).setPhase(phase);//perform the appropriate taskif (phase.equals("one")) {

//create a new empty destinationexecuteCommand();DestinationDataDeliveryBean ddd = new DestinationDataDeliveryBean();//put this DataDeliveryBean in the scope of the requestreq.setAttribute("destinationDataDeliveryBean", ddd);//forward the request to the next JSPtry {

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 parametersString destinationPortName = (String)

req.getParameter("DestinationCodeTextField");String destinationCountry = (String)

req.getParameter("DestinationLabelTextField");//populates the command

((AddDestinationCommand) getCommand()).setDestinationPortName(destinationPortName);

((AddDestinationCommand) getCommand()).setDestinationCountry(destinationCountry);

//execute the commandexecuteCommand();//forward to the GetDestinationsServlettry {

getServletContext().getRequestDispatcher("/servlet/com.ibm.redbooks.sg246201.destination.GetDestinationsServlet").forward(req, res);




}}

}

18.5.3 GetUniqueDestinationServletThe GetUniqueDestinationServlet class is shown in Figure 18-22.

Figure 18-22 GetUniqueDestinationServlet class


protected String getCommandClassName() {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:

public void performTask(HttpServletRequest req, HttpServletResponse res) {//retrieve the code parameter if anyString code = (String) req.getParameter("code");int identifier = Integer.parseInt(code);//reset and populate the commandgetCommand().reset();

((GetUniqueDestinationCommand) getCommand()).setDestinationPortId(identifier);

//execute the commandexecuteCommand();//populates the dataDeliveryBeanDestinationData 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 sessionreq.setAttribute("destinationDataDeliveryBean", ddd);//forward the request to the next JSPtry {

getServletContext().getRequestDispatcher("/jsp/DestinationDetail.jsp").forward(req, res);



}

}

ModifyDestinationServletThe ModifyDestinationServlet classis shown in Figure 18-23.


Figure 18-23 ModifyDestinationServlet class


protected String getCommandClassName() {return "com.ibm.redbooks.sg246201.destination.ModifyDestinationCommand";

}

The performTask method populates the command, executes it, populates the 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 servletsThis section focuses on servlets related to customer tasks when selecting a cruise.

GetCruiseLinesServletThe GetCruiseLinesServlet class is shown in Figure 18-24.

Figure 18-24 GetCruiseLinesServlet class


protected String getCommandClassName() {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.

Figure 18-25 Putting it all together: GetCruiseLinesServlet

GetCruisesServletThe GetCruisesServlet class is shown in Figure 18-26.

HTMLMain Menu

JSPCustomer

Home Page

GetCruiseLinesServlet

GetCruiseLines Command

CruiseLinesBusinessObject

CruiseLinesArrayDataDeliveryBean


Figure 18-26 GetCruisesServlet class


protected String getCommandClassName() {return "com.ibm.redbooks.sg246201.cruiselines.GetCruisesCommand";

}

The performTask method populates the command, executes it, populates the appropriate DataDeliveryBean, puts it in the request, and forwards the request to the CruisesList JSP.


Figure 18-27 describes the flow for this second step of the customer activity.

Figure 18-27 Putting it all together: GetCruiseServlet

JSPCruise Detail

JSPConfirmation

BookCruiseServlet

BookCruise Command

ReservationBusinessObject

ReservationDataDeliveryBean

CruiseDataDeliveryBean


GetCruiseDetailServletThe GetCruiseDetailServlet class is shown in Figure 18-28.

Figure 18-28 GetCruiseDetailServlet class


protected String getCommandClassName() {return "com.ibm.redbooks.sg246201.cruiselines.GetCruiseDetailCommand";

}

The performTask method populates the command, executes it, populates the 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.

Figure 18-29 Putting it all together: GetCruiseDetailServlet

JSPCruise Detail

JSPConfirmation

BookCruiseServlet

BookCruise Command





18.5.5 Reservation servletsThis section focuses on servlets related to customer tasks when booking a cruise.

BookCruiseServletThe BookCruiseServlet class is shown in Figure 18-30.

Figure 18-30 BookCruiseServlet class


protected String getCommandClassName() {return "com.ibm.redbooks.sg246201.reservation.BookCruiseCommand";

}


The performTask method populates the command, executes it, populates the appropriate DataDeliveryBean, puts it in the request, and forwards the request to the Confirmation JSP as follows:

public void performTask(HttpServletRequest req, HttpServletResponse res) {//reset the commandgetCommand().reset();//create and save the new reservation//get the request and session parametersHttpSession session = req.getSession(false);int cruiseIdentifier = ((CruiseDataDeliveryBean)

session.getValue("cruiseDataDeliveryBean")).getId();int numberOfTickets =

Integer.parseInt(req.getParameter("NumberTicketsToPurchaseDDL"));//populates the command

((BookCruiseCommand) getCommand()).setCruiseIdentifier(cruiseIdentifier);((BookCruiseCommand) getCommand()).setNumberOfTickets(numberOfTickets);//execute the commandexecuteCommand();//populates the dataDeliveryBeanReservationDataDeliveryBean rddb = new ReservationDataDeliveryBean();rddb.setReservationId(((BookCruiseCommand)

getCommand()).getReservationId());rddb.setNumberOfTickets(((BookCruiseCommand)

getCommand()).getNumberOfTickets());//put this DataDeliveryBean in the scope of the request//and remember that the CruiseDataDeliveryBean is already in the sessionrequest.setAttribute("reservationDataDeliveryBean", rddb);//forward to the Confirmation JSPtry {

getServletContext().getRequestDispatcher("/jsp/Confirmation.jsp").forward(req, res);



}}


Figure 18-31 summarizes the flow for this fourth step of the customer activity.

Figure 18-31 Putting it all together: BookCruiseServlet

18.6 Introducing the WAP applicationWAP 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

JSPCruise Detail

JSPConfirmation

BookCruiseServlet

BookCruise Command





18.6.1 Adapting the presentation to the WAPAdapting 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 JSPsThis 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.jspThe following code was used to produce the customer 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><%@ page language="Java" contentType="text/vnd.wap.wml" %><jsp:useBean id="cruiseLineArrayDataDeliveryBean"

class="com.ibm.redbooks.sg246201.cruiselines.CruiseLineArrayDataDeliveryBean" scope="request" />

<card id="CustomerArea" title="Customer Area"><do type="prev" label="Back"><prev/></do><p>Only our discount cruises are available from the WAP site.<br/>

For more cruises, please refer to the Web site.<br/></p><tsx:repeat index="i">

<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.jspThe code for the display of the cruises list 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><%@ page language="Java" contentType="text/vnd.wap.wml" %><jsp:useBean id="cruiseArrayDataDeliveryBean"

class="com.ibm.redbooks.sg246201.cruiselines.CruiseArrayDataDeliveryBean"


scope="request" /><card id="CruisesList" title="Cruises List">

<do type="prev" label="Back"><prev/></do><p>Here are the current discounts:<br/>

</p><tsx:repeat index="i">

<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.jspDetailed information about the cruise is built and presented with the following code 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><%@ page language="Java" contentType="text/vnd.wap.wml" %><jsp:useBean id="cruiseDataDeliveryBean"

class="com.ibm.redbooks.sg246201.cruiselines.CruiseDataDeliveryBean" scope="session" />

<card id="CruiseDetail" title="Cruise Detail"><do type="prev" label="Back"><prev/></do>


<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.jspDetailed information about the confirmation is built and presented with the following code 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><%@ page language="Java" contentType="text/vnd.wap.wml" %><jsp:useBean id="reservationDataDeliveryBean"

class="com.ibm.redbooks.sg246201.reservation.ReservationDataDeliveryBean" scope="request" />

<card id="ReservationOK" title="Reservation is done"><do type="prev" label="Back"><prev/></do><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 servletsWhen 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:

public void performTask(HttpServletRequest req, HttpServletResponse res) {//reset the commandgetCommand().reset();//create and save the new reservation//get the request and session parametersHttpSession session = req.getSession(false);int cruiseIdentifier = ((CruiseDataDeliveryBean)

session.getValue("cruiseDataDeliveryBean")).getId();int numberOfTickets = 1; //hard-coded in WAP version//populates the command

((BookCruiseCommand) getCommand()).setCruiseIdentifier(cruiseIdentifier);((BookCruiseCommand) getCommand()).setNumberOfTickets(numberOfTickets);//execute the commandexecuteCommand();//populates the dataDeliveryBeanReservationDataDeliveryBean rddb = new ReservationDataDeliveryBean();rddb.setReservationId(((BookCruiseCommand)

getCommand()).getReservationId());rddb.setNumberOfTickets(((BookCruiseCommand)

getCommand()).getNumberOfTickets());//put this DataDeliveryBean in the scope of the requestreq.setAttribute("reservationDataDeliveryBean", rddb);//formard to the Confirmation JSPtry {

getServletContext().getRequestDispatcher("/wml/WapConfirmation.jsp").forward(req, res);



}}


18.6.4 Testing with the WAP applicationThe 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 Environmentwhere <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:

<%@ page language="Java" contentType="text/vnd.wap.wml" %>

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.


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


19.1 Deploying the VisualAge Cruise Lines ApplicationDeploying 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 applicationCreating 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 ConsoleTo 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 WizardTasks 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 directoriesBeneath 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 WASThis 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 layerDeploying 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 layersDeploying 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 classpathThe 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 classpathSince 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 applicationIf 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 servletsWe 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

19.2 Additional deployment considerationsThis 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 applicationThe e-business application originates in VisualAge Pacbase and is defined using the e-business Workbench. The e-business application groups a set of technical

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.


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 monitorThe 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 fileWorking 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 serverThe 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 Appendixes

In this section, we provide the supplentary coding examples that go along with this book.

Part 3


Appendix A. Additional material

This redbook refers to additional material that can be downloaded from the Internet as described below.

Locating the Web materialThe 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 materialThe additional Web material that accompanies this redbook includes the following files:

File name DescriptionVAJRepositoryData.zip Zipped VisualAge for Java repository data

A


ftp://www.redbooks.ibm.com/redbooks/




WStudioWAR.zip Zipped WebSphere Studio archive file

System requirements for downloading the Web materialThe following system configuration is recommended:

Hard disk space: 2 MB minimumOperating System: Windows NT 4.0 SP5Processor: Pentium II or higherMemory: 128 MB minimum

How to use the Web materialCreate 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 dataThe 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 fileThe 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 RedbooksFor 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 resourcesThese 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 sitesThese Web sites are also relevant as further information sources:

� VisualAge Pacbase


� 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


436 VisualAge Pacbase for e-business Applications436 VisualAge Pacbase for e-business Applications

How to get IBM RedbooksYou 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 collectionsRedbooks 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




438 VisualAge Pacbase for e-business Applications438 VisualAge Pacbase for e-business Applications

Index

Aadapting the presentation to the WAP 409add persistence object button 174add relational database button 174AddDestinationCommand 364AddDestinationCommand class 365AddDestinationServlet 395AddDestinationServlet class 395adding a destination 351adding a feature to the VisualAge for Java work-bench 92adding the Programs tab 88additional communications information 76additional deployment considerations 426additonal directory locations 58administration database directory structure 65administrative library layer 189administrator sign on 132administrator Workbench menu bar 104aggregation and references 313analysis and design 202–203application architecture overview 17arrival reference 340associatives 314available cross-references 197

Bbackward development path 203batch programming workbench 30batch programs and macros 195beginning the administration database installation 47BookCruiseCommand 371BookCruiseCommand class 372BookCruiseServlet 406BookCruiseServlet class 406bridging from Rational Rose 309building a proxy 219building a services node 206building a services system 207building folder views 226building JSPs and servlets 375building services and data access 213

© Copyright IBM Corp. 2002. All rights reserved.

building the model layer 245business object framework 252business object programming process 255business pattern

application integration 18business-to-business 18user-to-business 18user-to-data 18user-to-online buying 18user-to-user 18

BusinessObject interface 253BusinessObjectFactory class 253

Ccall one or more data elements button 162cardinality constraints for aggregations 314cardinality constraints for references 314changing a directory location 52changing the application server classpath 424changing the error message text using the parame-ters browser 110changing the Web application classpath 424choose data elements to call screen 163choosing a business pattern 18choosing a runtime topology 19choosing an application topology 19choosing the administration database location 49class

ShipData 233ShipDataBeanInfo 234ShipDataUpdate 233ShipDataUpdateBeanInfo 234ShipProxyBeanInfo 234ShipProxyTableModel 233ShipProxyUpdateTableModel 233–234ShipSelectionCriteria 233ShipSelectionCriteriaBeanInfo 234

Class and method comments 26class diagrams 312classes and attributes 312Client/Server Facility-Generator 341client-side implementation 208client-side test tools 283

439

code in the macro 170command bean design pattern 21command framework 249command interface 249command line processing 115command Lines 115command pattern 248command programming process 252command state diagram 250CommandException class 250CommandException JSP 387CommandException.JSP 387CommandFactory class 252comments 261commonly encountered Web problems 13communication monitor 216, 219communication/middleware 13communications monitor 27, 427complete product environment 37completing server development 325completing the imported entities 323completing the system installation 46completion of the installation of Workbench 82components 5components of JavaServer pages 258composition for Cruise 329composition for Reservation 331–332composition for Ship 334composition of Cruise 326composition of CruiseLine 327composition of Reservation 328composition of Ship 328configuration file manager 85configuring the Web application - document root and class path 421Configuring the Web application - name, servlets, JSP support 420configuring the Web application - servlet engine 420configuring the Web application - virtual host and Web path 421Confirmation JSP 386Confirmation.JSP 386confirming the development database installation 60confirming the system installation 44connecting additional databases 78construction

client-side components 204

client-side, presentation, navigation 203presentation and navigation 203refinement 204server-side 202server-side components 203

content of the Input folder 66content of the Journal folder 66content of the Nls folder 62content of the Pgm folder 63content of the Proc folder 63content of the Save folder 66content of the Setbases folder 63content of the Tmp folder 67contents of Base folder 65contents of Skel folder 64control mechanism and navigation 272control mechanism servlet/command/JSP 273controller

servlet 23controller and model layers directory structure 423cookies 269create a function/sub-function button 170create a macro structure button 169create a segment button 161create data element button 158create generation command line SmartGuide 154create new command line button 153create new communication monitor button 182create new composition button 175create new e-business application button 179create new elementary component (EC) button 173create new folder (FO) button 180create new logical view button 171create property button 160create value button 160creating nodes 222creating presentation with JSPs 257creating the folders 378creating the Java packages 345creating the required Web application directories 422creating the VisualAge Cruise Lines Web applica-tion 418creating the VisualAge projects 344creating the WebSphere Studio project 376cross-reference considerations 197cross-references 197cruise detail through WAP 412Cruise line commands 366


Cruise line DataDeliveryBeans 389cruise line selection through WAP 411Cruise line servlets 400CruiseArrayDataDeliveryBean 389CruiseDataDeliveryBean 390CruiseDataDeliveryBean properties 390CruiseDetail JSP 386CruiseDetail.JSP 386CruiseLineArrayDataDeliveryBean 391CruiseLineBusinessObject 354CruiseLineBusinessOpbject class 354CruisesList JSP 385CruisesList.JSP 385customer JSPs 384CustomerHomePage JSP 385CustomerHomePage.JSP 385customizing the stages 379

Ddata elements workbench 159data entities 191data integrity 14data structure create button 161data structures and segments 192database blocks 192databases 114DB2 Universal Database 34DB2 Universal Database (UDB) 32dcoumenting text pages 111declarations 260default location for the development database 57defining servlets 426defining servlets for vcl Web application 426defining the application architecture 20definition window 174definitions 4departure reference 339DependentProxyLv 233deploying an e-business application 283deploying files to WAS 423deploying HTML pages and JSPs 284deploying server side components 284deploying servlets and JavaBeans 286deploying the application 417deploying the view layer 423deploying the VisualAge Cruise Lines Application 418deployment 212

describing the folder 221design techniques used 20designing a VisualAge Pacbase application 204destination business object 350destination DataDeliveryBeans 388destination servlets 393DestinationAdding JSP 384DestinationAdding.jsp 383DestinationArrayDataDeliveryBean 388DestinationBusinessObject class 350DestinationDataComparator class 353DestinationDataDeliveryBean 389DestinationDeliveryBean properties 389DestinationDetail JSP 384DestinationDetail.jsp 384DestinationsCatalog JSP 383DestinationsCatalog.jsp 382details of data elements 149developing commands 359developing JavaBeans 343developing navigation 209developing presentation 209developing services components 208developing the business objects 349developing the DataDeliveryBeans 388developing the JavaServer pages 382developing the servlets 392developing the WML-based JSPs 409development approach 22development database directory structure 68development libraries 190development paths 202development process summary 210development products 20

DB2 Universal Database (database develop-ment) 20VisualAge for COBOL (Compiling COBOL serv-ers) 20VisualAge for Java (Java development) 20VisualAge Pacbase (Servers) 20WebSphere Studio (HTML and JSPs develop-ment) 20

development standards 24development with the e-business Workbench 158diagrams 311directory structure for the workstation 83directory structure from Workbench installation 83discard all changes button 151discard button 145

Index 441

distributing the work among development teams 211documentation entities 193dynamic part of the tool bar 145

Ee-business application 215, 219, 426e-business application from the bridging process 323edit host options 80editing the workspace class path 95editing the workspace resources (options window) 94element detail to complete 324elementary component 177, 214, 222elementary components 329

Cruise 329CruiseLine 330Reservation 332Ship 333

elementary components from the bridging process 322employee JSPs 382EmployeeActions HTML page 382EmployeeHomePage HTML page 381Empty HTML page 381empty Workbench 140environment

administration 39installation 39setup 39

error file 219error handling 23error server 216, 428example using the DataDeliveryBean 264expressions 261external controls 130extract method 220

Ffactory pattern 247file menu 141finishing the folder 226Folder 233folder 216, 311

CruiseLine 336Reservation 335

folder composition for CruiseLine 336

folder resulting from the bridging process 322folder structure for SG246201 Redbook project 378folder view 217folders 335forward development path 202framework overview 22Function 60 157

Ggateway considerations 98generate button 341generated applications 199generated methods 239generating 340generating the VisualAge Pacbase entities 320generation manager 152–153generation options 342generic controller servlet 275GetCruiseDetailCommand 370GetCruiseDetailCommand class 370GetCruiseDetailServlet 404GetCruiseDetailServlet class 404GetCruiseLinesCommand 366GetCruiseLinesCommand class 367GetCruiseLinesServlet 400GetCruiseLinesServlet class 400GetCruisesCommand 368GetCruisesCommand class 368GetCruisesServlet 401GetCruisesServlet class 402GetDestinationsCommand 360GetDestinationsCommand class 360GetDestinationsServlet 393GetDestinationsServlet class 393getting a specific cruise 357getting a specific destination using its unique key 353getting all cruise lines 355getting all cruises for a cruise line 355getting all destinations 352GetUniqueDestinationCommand 361GetUniqueDestinationCommand class 362GetUniqueDestinationServlet 397GetUniqueDestinationServlet class 397granularity 272

Hhelp menu 143


HierarchicalProxyLv 232hierarchy of generated proxies 232hierarchy overview 232HTML pages 15

Iidentifying the business objects 349identifying the commands 359identifying the DataDeliveryBeans 388identifying the servlets 392implementing HTML pages 380implementing navigation with servlets 267implementing the navigation 271implementing the presentation 263implementing the singleton pattern in Java 246implementing wireless presentation using JSP 265implicit objects 261import from repository button 146import/create by code button 148imported data elements 320imported packages for generated proxies 348importing jar file options 96importing jar files into the class path 94importing jar files into VisualAge for Java projects 95importing the Rose model 318importing the VisualAge Pacbase proxies 348include directive 260indicating the destination folder 73inheritance 313initialization controls 131installation/setup of VisualAge Pacbase 3.0 respos-itory 40installed bridge 316installing a development database 55installing the administration database 46installing the communication DLLs 98installing the software 43installing the VisualAge Pacbase Java environment 93installing the VisualAge Pacbase middleware 98installing the VisualAge Pacbase system 43installing the VisualAge Pacbase Workbench 69installing the WebSphere test environment feature 92integration of Rational Rose with VisualAge for Java 35integration of Rational Rose with VisualAge Pac-

base 35integration of VisualAge for Java with WebSphere Application Server 36integration of VisualAge for Java with WebSphere Studio 35integration of WebSphere Application Server with DB2 36integration of WebSphere Studio with WebSphere Application Server 36interfaces to legacy applications 14introducing the WAP application 408introduction to Java servlets 268introduction to JavaServer pages 258introduction to patterns 18

JJava class standards 25Java license acceptance 71Java method standards 25Java package standards 25Java proxy classes hierarchy 232Java Servlet API 268Java variables standards 25JavaBeans 15JavaServer Pages (JSPs) 16JSP actions 262JSP directives 259JSP getProperty tag 262JSP scripting 260JSP setProperty tag 263JSP tags guidelines 264JSP useBean tag 262JSP/servlet architecture main components 14

Llevelling 156libraries 188library to support the Rose Bridge 317listener 27logical view 214, 220

Cruise 326CruiseLine 327Reservation 327Ship 328

logical views 326logical views from the bridging process 321lower half of the import SmartGuide 147

Index 443

Mmain local services for a dependent or reference proxy 235main local services for a folder proxy 234MainMenu HTML page 381maintenance considerations 197making VisualAge Pacbase Java environment a fea-ture 97managing libraries 134mapping between dependent proxy and server 238mapping between folder proxy and server 236mapping between reference proxy and server 238menu bar 140method

detail() 235–236getDetailFromDataDescription(aData) 235–236getTableModel() 235–236getUpdatedFoldersTableModel() 235getUpdatedInstancesTableModel() 235–236getXxx() (for example, getCabinProxy()) 235selectionCriteria() 235–236undoLocalFolderUpdates(aDataUpdate) 235undoLocalUpdate(aDataUpdate) 235

methodology support 5middleware 27middleware communications type 79model

command bean and business objects 22model layer summary 255–256Model-View-Controller (MVC) framework 21ModifyDestinationCommand 363ModifyDestinationCommand class 363ModifyDestinationServlet 398ModifyDestinationServlet class 399modifying a destination 351MQSeries 34MQSeries messaging environment 32

Nnode by node retrieval, option 1 241node by node retrieval, option 2 242nodes 221non JSP resulting servlets 273

Oone-layer architecture 8opening default.cfg for the Workbench 86

opening the Rose model file 318operating the bridge 317operations 312options for the administration database 48organizing the repository for reusability 187orienting relations 313

PPac/Transfer 120Pac/Transfer database selection 122Pac/Transfer selection criteria tabs 123Pac/Transfer SmartGuide 121packages 311page directive 259parameterized input aid 194parameters added by default 119partial listing of files for workstation 84patterns design process

choose application topology 18choose business pattern 18choose runtime topology 18defining application architecture 18defining products 18defining the runtime context 18development framework 18development standards 18within the development context 18within the runtime context 18

performance 13persistence management 14persistency management 269PO cinemtics window 175portability 199positioning the repository 191preparing the VisualAge environment 344preparing the WebSphere Studio environment 376proceeding to install the administration database 53proceeding with the Workbench installation 81processing entities 194product mapping 20profiles 116programming bar 164programming concepts 155programming process 263, 271Programs tab added to the workbench 89progress of the system installation 45properties for Cruise 338


properties for CruiseLine 337properties for Reservation 335properties for Ship 337properties window 181providing a user and organization 42proxy 16proxy dynamics 240

node by node retrieval, open 2 242node by node retrieval, option 1 242retrieving all dependent nodes at once 243retrieving root instances 241

proxy features 231proxy generation 340proxy generation process 230proxy object 4proxy related generated classes 233proxy service

checkExistenceOfDependentInstances() 236, 238executeUserService() 237–238readAllChildren(RacineData) 237readAllChildrenFromCurrentInstance() 237readFirstChildren(DependantData) 238readFirstChildren(RacineData) 237readFirstChildrenFromCurrentInstance() 237–238readInstance() 237–239readInstanceWithAllChildren() 237readInstanceWithFirstChildren() 237–238readNextPage() 237–239selectInstances() 237–239setExtractMethodCode(String) 237–239setGlobalSelection(boolean) 237–239setMaximumNumberOfRequestedInstanc-es(int) 237–239setUserServiceCode(String) 237–238updateFolder() 237

ProxyLv 232public services of generated proxies 234publishing facility 194purchase confirmation through WAP 413Putting it all together - BookCruiseServlet 408Putting it all together - GetCruiseDetailServlet 405Putting it all together - GetCruiseLinesServlet 401Putting it all together - GetCruiseServlet 403

QqQuick tour of the Workbench 139

quick start window 139

RRational Rose 5, 32Rational Rose modeling environment 32Redbooks Web site 437

Contact us xviiReferenceProxyLv 233refresh all button 151refresh button 144refresh invalid entities button 152refresh updated entities list button 151relation to the Rational Rose toolkit 206relation to Unified Modeling Language (UML) 204relations 313removing a tab 91reports 196repositioning a tab 90repositiry

users 31repository 31

batch programs 31data elements 31data structures 31database blocks 31documentation 31e-business programs 31libraries 31methodology 31reports 31segments 31

repository content 199required components 204Reservation commands 371Reservation DataDeliveryBeans 391reservation servlets 406ReservationBusinessObject 358ReservationBusinessObject class 358ReservationDataDeliveryBean 391ReservationDataDeliveryBean properties 391resolving many-to-many relations 315retrieving all dependent instances at once 243retrieving dependent instances 241retrieving root instances 241reusability 186reusable components 186runtime products 20

DB2 Universal Database 5.0 (database man-

Index 445

agement) 20IBM HTTP Server (HTTP server) 20JDK1.1.7 (Java Virtual Machine) 20WebSphere Application Server Advanced Edi-tion (Java application server) 20Windows NT 4.0 (operating system) 20

runtime testing 286runtime topology

communications 19database management system 19operating system 19

Ssample proxy hierarchy 240save all button 151save button 145scriptlets 260search button 144security 14select identifier window 182selecting the WebSphere Test Environment feature 93selecting the Workbench modules 74server-side implementation 206services manager 217serving dynamic WML content using servlets and JSPs 265servlet process flow 268ServletContext group 269servlets 15servlets - Include and Forward 274session 270setting a technical context 207setting the Java classpath 347setting the JSP version 347setting the JSP version in WebSphere Studio 377setting versions for the JSP and the application serv-er 376settings for the Rose Bridge import 319show details button 148signing on to the VisualAge Pacbase administrator workbench 102signon library view 198singleton pattern 246SmartGuide for adding a profile 117SmartGuide for Workbench installation 70specifying a development database 56specifying additional locations 50

specifying Pac/Transfer change numbers (DSMS only) 127specifying sessions for Pac/Transfer 124specifying source and target libraries 125specifying the communications type 75specifying the external controls 130specifying the gateway IP address and port 77specifying user codes for Pac/Transfer 126standard tool bar icons 144starting the Administrative Console 418starting the administrator workbench 101starting the installation 41starting the Web application 425starting WebSphere Application Server as a service 419subclassing the servlets 413submit and save button 155successful installation of development database 61successful installation of the administration data-base 54summary of development environment 37summary of runtime environment 38support for e-business 6system directories 62

Ttabs for the VisualAge Pacbase administrator work-bench 106tabs for the workbench 87team considerations 211technical environment 218terminology 4testing 210testing and deployment 203–204, 277testing the e-business application 227testing with the WAP application 415three-layer architecture with applet/servlet 11three-layer architecture with JSP/servlet 12top half of the import SmartGuide 146traffic loads 13two-layer architecture 9two-layer architecture with applets and JDBC 10

UUnified Modeling Language (UML) 5updating the application server classpath 425updating the Web application classpath 424useful patterns 246


user options for the Workbench 72user REDBOOK 129users 128user-to-business application topology 19using Rational Rose 310using the administrator Workbench 113using the Profiles tab 116using the Rational Rose bridge 311using the Task Wizard 419using VisualAge Pacbase 311

Vvalidity controls 131VAP Test Tool folders browser 281VAP Test Tool folders hierarchal view 282VAP Test Tool launching menu 279VapGateway.exe parameters 99verifying the administration database install 64verifying the development database install 67verifying the installation 61verifying the system installation 62view

JSPs 23view layer directory structure 423VisualAge Cruise Lines

adding a destination 307application specifications 289background 290country attibute 291cruise ID attirbute 291cruise line detail 301cruise line ID attirbute 291cruise line ID attribute 291–292cruise line selection 300cruise lines object 291cruise name attribute 291cruises object 291customer concerns 290customer reservation 299customer reservation confirmation 303data considerations 291data elements supporting the sample application 293data implementation 293data implementation structure 297description attribute 291destination ID attribute 292destinations already established 306

destinations object 291elementary components for the sample applica-tion 298employee concerns 290employee intranet choices 305employee sign on for cruise management 304first relationship 292folder content for sample application 296fourth relationship 293homepage for the sample application 299logical views for the sample application 295management 304name attribute 291number of available tickets attribute 292number of reservations attribute 292number of tickets attribute 292objects 291port country attribute 292port name attribute 292price attribute 292processing considerations and implementation 297registry attirbute 291relationships 292requirements 290reservation ID attribute 292reservations object 291second relationship 292segments supporting the sample application 294ships object 291specific cruise detail 302third relationship 293total price attribute 292

VisualAge Cruise Lines packages 346VisualAge Cruise Lines WAP homepage 410VisualAge for Java 33VisualAge for Java development environment 32VisualAge for Java ready-to-use workbench 345VisualAge Pacbase

administrator icons 129administrator Workbench tabs 113advantages 4architecture 27base administration 131development 137development process 201overview 3Parameters browser 109

Index 447

products overview 29proxy 16, 229proxy as an interface for the server 17proxy components 16proxy is generated 17repository 30reuse and portability 185runtime project 97Security Browser 107server 30site administration 100targeted application architecture 7Test Tool 278utilities 135workbench 30

VisualAge project standards 24VisualAge version names standards 26VisualAgeCruiseLine HTML page 380

WWAP in the architecture 266WAP relative to our e-business architecture 266WapConfirmation.jsp 412WapCruiseDetail.jsp 411WapCruisesList.jsp 410WapCustomerHomePage.jsp 409Web application director structure 422Web applications 8Web architectures 8WebSphere Application Server 34WebSphere Application Server execution environ-ment 32WebSphere Application Server topology 285WebSphere specific tags 263WebSphere Studio 33WebSphere Studio development environment 32WebSphere Test Environment publishing page 380WebSphere Test Environment setup 346what is a VAP proxy 230window menu 142Wireless Application Protocol (WAP) 265Workbench in general 138workbench with Rose Bridge 316working file 428workspace manager 149–150workspace menu 142


(1.0” spine)0.875”<

->1.498”460 <

-> 788 pages

VisualAge Pacbasefor e-business Applications

®

SG24-6201-00 ISBN 0738421200

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICALINFORMATION BASED ONPRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information:ibm.com/redbooks

VisualAge Pacbasefor e-businessApplicationsAn overview of VisualAge Pacbase V3

Step-by-by guide to develop an e-business application

Develop JSPs and EJBs

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 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.


Back cover

visual age pacbase

Documents