Front cover

WebSphere
Application
cation Server V66
Migration Guide
de
Application developer migration tasks

System administrator migration

tasks
Migration examples

Rudy Chukran
Tom Alcott
Wayne Beaton
David Dhuyvetter
Dana Duffield
Tushar Patel
Jack Snyder

ibm.com/redbooks

International Technical Support Organization

WebSphere Application Server V6 Migration Guide
April 2005

SG24-6369-00

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

First Edition (April 2005)

This edition applies to Version 6 of IBM WebSphere Application Server.
Copyright International Business Machines Corporation 2005. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.

Contents
Chapter 1. Development tools overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1 Overview of WebSphere development tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 IBM Rational Web Developer for WebSphere Software . . . . . . . . . . . . . . . . . . . . .
1.1.2 IBM Rational Application Developer for WebSphere Software . . . . . . . . . . . . . . . .
1.1.3 WebSphere Application Server Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.4 Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.5 Embedded WebSphere Application Server test environment . . . . . . . . . . . . . . . . .
1.2 Important user interface changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 How to obtain more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3
4
4
4
5
5
5
5
9

Chapter 2. Application migration to developer tools. . . . . . . . . . . . . . . . . . . . . . . . . . .

2.1 General application upgrade issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Importing source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Migrating workspaces from previous versions . . . . . . . . . . . . . . . . . . . . . . . . . . .

13
14
14
14

Chapter 3. Changing application code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.1 J2EE compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Incremental migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 When to redesign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Code incompatibilities and deprecations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 J2EE 1.3 versus J2EE 1.4 differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 J2SE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 WebSphere API incompatibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4 WebSphere API deprecations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5 Programming Model Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.6 Third-party libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17
18
18
19
19
20
30
31
31
36
37

Chapter 4. Development migration scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.1 Migrating from WebSphere Studio Application Developer Version 5.1 to IBM Rational
Application Developer for WebSphere Software Version 6 . . . . . . . . . . . . . . . . . . . . .
4.1.1 Example: Migrating Plants By WebSphere using the Export/Import method . . . .
4.1.2 Example: Migrating PlantsByWebSphere using the CVS method . . . . . . . . . . . .

39

Chapter 5. Product overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1 The new product: Version 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 Product offerings for V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 New features for V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1 New installation and operating model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2 New programming model extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.3 Development and assembly tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3 Version 6 package descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1 WebSphere Application Server Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2 WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.3 IBM WebSphere Application Server Network Deployment . . . . . . . . . . . . . . . . . .

71
72
72
73
73
74
74
74
75
76
77

Chapter 6. Runtime migration strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1 Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.1 Development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.2 Development integration runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

79
80
81
82

Copyright IBM Corp. 2005. All rights reserved.

40
40
63

iii

6.1.3 System test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1.4 Performance test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.5 Pre-production environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.6 Production environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Interoperability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.1 Mixed version cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.2 HTTP servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 Migration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.1 Fully automated migration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.2 Partially automated migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.3 Manual migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

82
83
84
84
85
85
86
89
89
90
90

Chapter 7. Runtime administration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

7.1 Significant concept changes from previous versions . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.1.1 Significant changes from V4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.1.2 Significant changes from V5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.1.3 Concepts preserved from V5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.2.1 Launchpad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.2.2 Individual component installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.2.3 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
7.2.4 Silent installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
7.3 Administrative console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7.3.1 Console address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7.3.2 Messaging components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7.3.3 Data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
7.3.4 Plugin-Cfg generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
7.4 How to perform basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
7.5 Changes in default settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
7.5.1 Class loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
7.5.2 Transaction isolation level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
7.5.3 getResource path syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
7.6 Automatic migration utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
7.6.1 Command line utilities introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
7.6.2 Configuration migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
7.6.3 Graphical wizard for configuration migration. . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
7.6.4 Script compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
7.6.5 J2EE application clients conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Chapter 8. Migration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1 Migration utilities supported versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2 Migrating single stand-alone nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3 Version 4: multiple servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4 V5 Network Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.5 Web servers and plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.5.1 IBM HTTP Server Version 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.5.2 Other Web server brands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.5.3 Web Server Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.6 Messaging migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.7 Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.7.1 Migration of Web Services Gateway configuration . . . . . . . . . . . . . . . . . . . . . . .
8.7.2 Migration of Web Services Gateway applications using WS-Security . . . . . . . .
8.7.3 Migration to UDDI V3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

iv

WebSphere Application Server V6 Migration Guide

135
136
136
138
140
143
143
143
143
144
144
144
145
146

8.8 Multi-broker migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Chapter 9. Script compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.2 Compatibility of data location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.2.1 Transaction logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3 Compatibility with new object types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3.1 HTTP transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3.2 Process definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.4 Migrating from version 5 embedded messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.4.1 Migration of scripts to SIB JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.4.2 Wildcard syntax conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.4.3 Replacing MDB listener ports with JMS activation specifications . . . . . . . . . . . .
9.5 Jacl 1.2.6 and Jacl 1.3.1 differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.6 Version 4 wscp migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.6.1 Migration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.6.2 Migration from V4.0 to V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

149
150
150
150
151
151
151
152
153
154
154
154
155
155
156

Chapter 10. Runtime application migration examples. . . . . . . . . . . . . . . . . . . . . . . . . 169

10.1 Overview of migration examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
10.2 Automatic migration: V4 AE Single Server to V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
10.3 Automatic migration: Application Server V5 to Express V6. . . . . . . . . . . . . . . . . . . . 175
10.3.1 Preparing your existing environment for migration . . . . . . . . . . . . . . . . . . . . . . 175
10.3.2 Reviewing application and resources on your existing environment. . . . . . . . . 175
10.3.3 Preparing the V6 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
10.3.4 Running automigration utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
10.3.5 Reviewing application and resources on V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
10.3.6 Migrating Web server and WebSphere plug-ins . . . . . . . . . . . . . . . . . . . . . . . . 185
10.3.7 Confirming that the application is functioning correctly . . . . . . . . . . . . . . . . . . . 189
10.4 Automatic migration: V4 AE Server Group to a V6 Network Deployment Cluster. . . 189
10.4.1 Preparing your existing environment for migration . . . . . . . . . . . . . . . . . . . . . . 189
10.4.2 Preparing for a V6 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
10.4.3 Reviewing the V4 configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
10.4.4 Migrating nodes using automatic migration utilities. . . . . . . . . . . . . . . . . . . . . . 192
10.4.5 Migrating the deployment manager using automatic migration utilities. . . . . . . 195
10.4.6 Migrating Web Server and plug-ins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
10.5 Automatic migration: V5 Network Deployment Cluster to V6 Network Deployment Cluster
198
10.5.1 Preparing your existing environment for migration . . . . . . . . . . . . . . . . . . . . . . 198
10.5.2 Starting the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
10.5.3 V6 installation preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
10.5.4 Deployment manager migration using the migration wizard . . . . . . . . . . . . . . . 203
10.5.5 Managed node migration using the migration wizard . . . . . . . . . . . . . . . . . . . . 207
10.6 Manual migration: installation of J2EE 1.3 Enterprise Application on V6 Application
Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
10.6.1 Preparing the V6 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
10.6.2 Configuring JMS resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
10.6.3 Configuring JDBC resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
10.6.4 Installing the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
10.6.5 Verifying the application operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Contents

vi

WebSphere Application Server V6 Migration Guide

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. 2005. All rights reserved.

vii

Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Eserver
Eserver
Redbooks (logo)
developerWorks
ibm.com
iSeries
pSeries
z/OS
zSeries
AIX 5L
AIX

ClearCase
Cloudscape
Domino
DB2 Connect
DB2 Universal Database
DB2
Informix
IBM
Lotus
MQSeries
Notes

OS/400
PowerPC
Rational Unified Process
Rational
Redbooks
SAA
Tivoli
TXSeries
VisualAge
WebSphere

The following terms are trademarks of other companies:

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.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States, other
countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks of others.

viii

WebSphere Application Server V6 Migration Guide

Preface
The creation of this Migration Guide is the result of tremendous input from customers
requesting guidance on migrating their WebSphere development environment, including
applications, integration, and test and production environments. This guide has been
compiled using the collective experience of many experts who have supported thousands of
installations and migrations.
Betsy Matthew
Vice President, AIM Technical Support and Customer Service

What is in this redbook?

This IBM Redbook has been written to assist in the migration of your WebSphere
Application Server installation. The end-to-end migration path includes the migration of the
development environment, the test/integration environment, and the production environment
using software engineering methodologies. This guide presents best practices in migration
strategy and planning, migration tools, and practical migration examples.
This guide was written specifically to address this set of products.
Version 6 IBM Rational Application Developer for WebSphere Software and IBM Rational
Web Developer for WebSphere Software for the Windows and Intel Linux 32 bit
operating system platforms
Version 6 of the WebSphere Application Server, WebSphere Application Server Express,
and WebSphere Application Server Network Deployment products. These products
specifically target these operating system platforms:

Microsoft Windows for Intel 32 bit architecture

Linux for Intel 32 bit architecture
IBM AIX for PowerPC architecture
Sun Solaris for Sparc architecture
Hewlet Packard HP-UX PA-Risc architecture

This redbook includes the following sections:

Part 1, For application developers on page 1
This part is of most interest to developers who create and modify applications. Developers
who develop for any of the WebSphere platforms can find pertinent material here.
Chapter 1, Development tools overview on page 3
This chapter describes the new Rational Developer products and the key differences
with the previous versions of the WebSphere Studio product line. Key user interface
differences from past versions are discussed.
Chapter 2, Application migration to developer tools on page 13
This chapter discusses workspace migration, project migration and limitations of
compatibility between versions of the development tools.
Chapter 3, Changing application code on page 17
This chapter describes application coding issues for both Java applications and
wsadmin scripts.

Copyright IBM Corp. 2005. All rights reserved.

ix

 Chapter 4, Development migration scenarios on page 39

This chapter describes specific steps showing how to migrate application projects from
previous versions of WebSphere Studio to the current Rational Developer product
line.
Part 2, For system administrators on page 69
This part is of most interest to administrators whose must manage configurations of
application servers and deploy applications to those servers.
Chapter 5, Product overview on page 71
This chapter reviews the new content of the WebSphere product line that is important
to migrating existing applications.
Chapter 6, Runtime migration strategy on page 79
This chapter discusses global migration strategies and the planning that must occur
before an application migration is executed.
Chapter 7, Runtime administration overview on page 93
This chapter discusses the major differences in how system administration is done for
the new Version 6 WebSphere products.
Chapter 8, Migration tasks on page 135
This chapter discusses the high-level tasks that an administrator must be aware of for
various system configurations.
Chapter 9, Script compatibility on page 149
This chapter discusses the compatibility issues with administrative scripts and the
resources you need to rework scripts that are no longer compatible.
Chapter 10, Runtime application migration examples on page 169
This chapter gives you concrete examples of how a simple application is migrated in
various server configurations.

The team that wrote this redbook

The following people were members of the team that authored the book. They all work for
IBM in the United States in various roles involving the WebSphere product line.
Rudy Chukran acted as project leader for this redbook. He is an Advisory Software Engineer
with over 30 years of experience in the computer industry. His most recent role has been
supporting customers for WebSphere early access programs. Prior to that, he has worked as
a software developer on several products, earned two IBM Patent awards, written several
articles for technical publications, and authored the book Accelerating AIX. He holds a
Bachelor of Science degree in Electrical Engineering from Carnegie-Mellon University.
Tom Alcott is consulting I/T specialist in the United States. He has been a member of the
World Wide WebSphere Technical Sales Support team since its inception in 1998. In this role,
he spends most of his time trying to stay one page ahead of customers in the manual. Before
working with WebSphere, he was a systems engineer for IBMs Transarc Lab, supporting
TXSeries. His background includes over 20 years of application design and development on
both mainframe-based and distributed systems. He has written and presented extensively on
a number of WebSphere runtime issues. Among his publications are Migrating to WebSphere
V5.0: An End-to-End Migration Guide, WebSphere Scalability: WLM and Clustering,
WebSphere V3 Performance Tuning Guide and, most recently, IBM WebSphere: Deployment
and Advanced Configuration.
x

WebSphere Application Server V6 Migration Guide

Wayne Beaton is a Senior Software Consultant with Software Services for WebSphere, part
of the IBM Software Group. His main focus is helping customers to migrate from previous
versions and competitive products (including Visual Basic) to WebSphere Application Server
5.x. He has co-authored two other IBM Redbooks on the topic of migration. Waynes
diverse role involves him in many other interesting areas including the WebSphere Skills
Transfer programs and general consulting.
David Dhuyveter is a Senior Software Engineer with the WebSphere Enablement Team.
With IBM since 2000, he has over 10 years of experience in distributed transactional
systems. David has focused on application development and migration, and is co-author of
the redbook Migrating to WebSphere V5.0: An End-to-End Migration Guide. David received
his MS in Computer Science from California State Polytechnic University, Pomona in 1993.
Dana Duffield is a Senior Software Engineer and is the Migration and Interoperability
Architect for WebSphere Application Server in IBM Rochester. He is a software engineer who
has worked at the IBM Rochester Lab for over 22 years on various development projects. He
holds a Bachelor of Science degree in Computer Science from the University of Illinois,
Champagne-Urbana. He has significant experience in object-oriented and distributed system
development in architecture, development and leadership positions. Prior to working at IBM,
he worked at Bell Laboratories in Naperville, Illinois.
Tushar Patel is a WebSphere Lab Advocate in the United States, a software advisory role to
help support WebSphere customers in large complex deployments. He has over 12 years of
technical experience in Information Technology in various capacities. He holds a BS degree
in Software Engineering from University of Birmingham, England and an MBA from the
University of Cambridge, England.
Jack Snyder is a Senior I/T Architect in IBM Pittsburgh. He has over 30 years of experience
in computer systems and the engineering field of mining and computer systems. Jack holds
B.S., M.S., and Ph.D. degrees in engineering. His areas of expertise include WebSphere
Application Server, Java, and process control.
The following people assisted in providing information for the book.
Vijay Bhadriraju is an Advisory Software Engineer with over six years of experience in IBM.
He is currently a developer of J2EE tools and the team lead for migration topics for the
WebSphere Studio and Rational Developer line of products.
The following people assisted by providing review commentary for the book.
Vijay Bhadriraju also reviewed this book.
Diane Chalmers is a Staff Software Engineer located in Rochester, Minnesota. She is the
Migration focal point for WebSphere Application Server System Verification Test team. Diane
has over five years of test experience.

Preface

xi

Become a published author

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

Comments welcome
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Send us your comments about this or
other Redbooks in one of the following ways:
Use the online Contact us review redbook form found at:
ibm.com/redbooks

Send your comments in an email to:

[email protected]

Mail your comments to:

IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 662
P.O. Box 12195
Research Triangle Park, NC 27709-2195

xii

WebSphere Application Server V6 Migration Guide

Part 1

Part

For application
developers
The chapters in this part are of interest to application developers who need to know about
development environment and application programming issues.

Copyright IBM Corp. 2005. All rights reserved.

WebSphere Application Server V6 Migration Guide

Chapter 1.

Development tools overview

This chapter is an overview of IBM Rational Developer products that support J2EE
development for the IBM WebSphere Application Server. We discuss the minimum set of new
functions that a developer must be aware of in order to migrate from previous versions to
Version 6.

Copyright IBM Corp. 2005. All rights reserved.

1.1 Overview of WebSphere development tools

The suite of IBM products related to developing J2EE applications on the market during the
time frame 2001 through 2004 was marketed using the brand name WebSphere Studio. For
V6, the brand name changes to Rational Developer. This suite of products is based on the
Eclipse open source project. The foundation uses the Eclipse workbench as a framework and
adds IBM unique tools and functions. Table 1-1 shows a summary of the products that we
discuss.
Table 1-1 WebSphere development tools products
Version 4

Version 5

Version 6

Targeted to

WebSphere Studio
Application Developer

WebSphere Studio
Application Developer

IBM Rational
Application Developer
for WebSphere
Software

Full J2EE 1.4

development

WebSphere Studio
Site Developer

WebSphere Studio
Site Developer

IBM Rational Web

Developer for
WebSphere Software

J2EE Web module

development subset

The development tools have evolved from Version 4 to Version 6 with enhanced function so
that each product can do more than the previous version.

1.1.1 IBM Rational Web Developer for WebSphere Software

IBM Rational Web Developer for WebSphere Software has evolved from its predecessor
products of WebSphere Studio Site Developer V4 and WebSphere Studio Site Developer V5.
It is primarily aimed at Web developers and supports J2EE 1.4 standards with the exception
that no EJB development tools are provided. The following significant features are contained
in V6:

WebSphere Application Server test environments

Visual Java GUI builder
Web Diagram Editor
Site designer
Page templates
XML tools
Web services tools
Database tools
Portal and portlet development
Enterprise Generation Language development

1.1.2 IBM Rational Application Developer for WebSphere Software

IBM Rational Application Developer for WebSphere Software has evolved from its
predecessor products of WebSphere Studio Application Developer Version 4 and WebSphere
Studio Application Developer Version 5. IBM Rational Application Developer for WebSphere
Software has broadened its appeal by adding more functions. IBM Rational Application
Developer for WebSphere Software has all the functions of IBM Rational Web Developer for
WebSphere Software with these additional features:

J2EE EJB development

UML visual editors
Static and runtime analysis
Extended debugging and profiling

WebSphere Application Server V6 Migration Guide

 Component test automation

ClearCase LT for team integration
Rational Unified Processing integration

1.1.3 WebSphere Application Server Toolkit

WebSphere Application Server Toolkit is a limited purpose tool that is used to assembling and
repackaging existing applications. It is not a full function development environment.
WebSphere Application Server Toolkit has a subset of the functionality of IBM Rational
Application Developer for WebSphere Software. This means that the user interfaces
controlling those subset functions are identical to those in IBM Rational Application Developer
for WebSphere Software. The following functions are included:
Assembly operations
Import wizards to import jar and class files
Module validators
Deployment operations
J2EE deployment descriptor editors
Editors for IBM deployment extensions and binding files
EJBdeploy invocation for generating EJB deployment artifacts
Debug operations
Remote and local testing on WebSphere Application Server Version 6 servers
Profiling on WebSphere Application Server Version 6 servers
See the InfoCenter documentation for an overview of WebSphere Application Server Toolkit:
http://publib.boulder.ibm.com/infocenter/ws60help/topic/com.ibm.welcome.ast.doc/topics/asto
verview.html

1.1.4 Supported operating systems

Please see Appendix A, Prerequisite software on page 225 for a complete list of supported
operating systems.

1.1.5 Embedded WebSphere Application Server test environment

IBM Rational Application Developer for WebSphere Software and IBM Rational Web
Developer for WebSphere Software deliver optionally installed embedded WebSphere test
server environments. The following servers are delivered with Rational Developer products.
Please note that WebSphere Application Server V4 is no longer offered as an embedded test
environment.

WebSphere Application Server V6.0

WebSphere Application Server V5.1
WebSphere Application Server V5.0
WebSphere Application Server Express V5.1
WebSphere Application Server Express V5.0

1.2 Important user interface changes

You should be aware of some of the user interface changes that may prevent you from finding
the functions that you may already be familiar with in previous versions.

Chapter 1. Development tools overview

New welcome page

When you first launch IBM Rational Application Developer for WebSphere Software, you may
see an unfamiliar welcome screen, as in Figure 1-1.

Figure 1-1 Rational Developer initial window

You can select any of the icons in the welcome page, and you can see other documentation
that gives you more information about the new features. If you are eager to get to work with
IBM Rational Application Developer for WebSphere Software, then simply select the x symbol
in the page tab next to the word Welcome in order to dismiss the page and see the product
workbench desktop.

Perspective switcher location

The icon to open new perspectives and switch between open perspectives has changed its
default location to the upper right corner of the workbench. Figure 1-2 on page 7 shows
where the perspective switcher is found.

WebSphere Application Server V6 Migration Guide

Figure 1-2 Perspective switcher

If you prefer the perspective switcher location of the previous versions, you can change the
location with a preference as shown in the workbench appearance preference settings.
Figure 1-3 shows an example of how to change the preferences for the perspective switcher.

Figure 1-3 Rational Developer preferences for perspective switcher

Enabling and disabling workbench capabilities

When you first launch IBM Rational Application Developer for WebSphere Software, you may
not see all the capabilities available that you are expecting to see. V6 has adopted the
concept of easy feature disabling and enabling. The default is to enable J2EE development,
but to disable many of the other development features you are used to seeing. Disabling
unneeded features can improve IBM Rational Application Developer for WebSphere Software
startup time. Figure 1-4 on page 8 shows an example of the window that configures enabling
features. Select Window -> Preferences, and expand the workbench preferences to see
what you can enable and disable. Before any customization, J2EE Enterprise Java and J2EE
Web Development are enabled by default, but Web services development is disabled.
Customize the capabilities preferences to enable those capabilities that you frequently use,
and disable those capabilities that you seldom use.

Chapter 1. Development tools overview

Figure 1-4 Rational Developer capabilities

Enhanced WebSphere Application Server Test Environment

The most significant change to the user interface that affects how you use the product is in
the area of the WebSphere Application Server test environment.
Version 4 and Version 5 of WebSphere Studio include the concept of a server configuration
editor. This editor changes the server settings and those settings are saved into the server
configuration project. The V5 server configuration editor supersedes almost all the server
settings that are changeable in the application server administrative console. However, there
are certain settings that could only be changed from the administrative console. This means
that inconsistencies with the user interface arose, and these inconsistencies are confusing.
The confusion arises from the fact that some settings are changed with the configuration
editor, while some settings are changed using the administrative console.
For V6, IBM Rational Application Developer for WebSphere Software relies on the
administrative console for the great majority of its configuration. A server configuration as part
of the server project still exists, but in greatly reduced form. When you open the Server
configuration, you see a basic overview which contains basic server launch information only.
See an example of the server overview in Figure 1-5.

Figure 1-5 Rational Developer Server overview

WebSphere Application Server V6 Migration Guide

You launch the administrative console in exactly the same way as in previous versions. You
right-click the server and select Run Administrative Console as shown in Figure 1-6. This
operation launches a browser window in which the administrative console for WebSphere
Application Server is running.

Figure 1-6 Rational Developer: run administrative console

In previous versions, you are required to install and configure a Remote Agent Controller
(RAC) in order to test on external application servers, even if the application server is
installed on the same system. V6 simplifies testing with locally installed servers by including
the RAC functionality such that you can test on a local server without installing a RAC.

1.3 How to obtain more information

Following are some source of further help and information.

Built-in help
Both IBM Rational Developer products have an built-in help facility. You access the help via
the Help menu as shown in Figure 1-7 on page 10.
The Help browser looks like that shown in Figure 1-8 on page 10. You can perform keyword
searches by typing in the search area. You can also browse articles in the navigation box on
the left.

Chapter 1. Development tools overview

Figure 1-7 Rational Developer Help

Figure 1-8 Rational Developer Help browser

Web Resources
You can access help on the World Wide Web by locating the Web Resources page and
selecting links that interest you. Figure 1-9 and Figure 1-10 on page 11 show the process of
accessing this page via the Help menu. Selecting the icons on this page opens a browser
window to the corresponding information page on the Web.

Figure 1-9 Rational Developer: starting Web Resources

10

WebSphere Application Server V6 Migration Guide

Figure 1-10 Rational Developer Web Resources links

Chapter 1. Development tools overview

11

12

WebSphere Application Server V6 Migration Guide

Chapter 2.

Application migration to
developer tools
This chapter discusses methods for developers to migrate their application source code into
the latest development tools.

Copyright IBM Corp. 2005. All rights reserved.

13

2.1 General application upgrade issues

There are general issues that a developer must take into account when migrating an
application to a new version of a development platform.
Adapting a general development process to a new product user interface
Changing source code due to mandatory programming interface changes
Moving source code from an archive into a development tool
User interface changes are discussed in 1.2, Important user interface changes on page 5
and Chapter 4, Development migration scenarios on page 39.
Source code changes are discussed in detail in Chapter 3, Changing application code on
page 17.
Moving source code into IBM Rational Application Developer for WebSphere Software and
IBM Rational Web Developer for WebSphere Software is discussed further in 4.1.1,
Example: Migrating Plants By WebSphere using the Export/Import method on page 40.

2.2 Importing source code

Source code can be contained in these types of locations:
A set of projects contained in a workspace from a previous version of WebSphere Studio
A source code repository product
CVS
ClearCase LT
An J2EE EAR file

2.2.1 Migrating workspaces from previous versions

A V5.1.x (any of 5.1.0, 5.1.1, or 5.1.2) workspace from WebSphere Studio Application
Developer opened in IBM Rational Application Developer for WebSphere Software can be
automatically migrated. You can open a Version 5.1.x workspace at initial startup time, or you
can open a workspace by selecting Switch Workspace from the File menu. The 5.1.x
workspace is converted in place transparently by an hidden conversion process. Upon
conversion, the workspace can no longer be opened by WebSphere Studio Application
Developer.

Server targeting
Server targeting is a feature introduced in WebSphere Studio Application Developer V5.1.1.
Server targeting is an optional feature in the J2EE preferences in V5.1.1 and V5.1.2 and can
be enabled or disabled by the user. In IBM Rational Application Developer for WebSphere
Software, this feature is not optional and server targeting is therefore enabled by default.
For more details about the server targeting feature, refer to the online help.

Sharing projects with earlier versions

V5.1.x workspaces migrated to IBM Rational Application Developer for WebSphere Software
cannot be shared with earlier versions of WebSphere Studio Application Developer. That is,
no version, 5.0 or earlier, is able to understand the workspace contents and therefore none
can open the workspace.

14

WebSphere Application Server V6 Migration Guide

However, V5.1.x projects that are imported from a source code repository or another
developer into V6.0 are compatible for sharing with V5.1.x so long as no new features in V6.0
are used in the project. Sharing projects between V5 and V6 requires that you export the
project with the Project Interchange option. The output of the export operation is a ZIP file that
contains the project and the project metadata. You then import the same ZIP file into
WebSphere Studio Application Developer using the Project Interchange option. For more
information, see the online help facility and look for the article Sharing Projects using Project
Interchange. For information about how to launch the online help facility, see 1.3, How to
obtain more information on page 9.

Known problem when migrating a workspace

You may see error messages displayed and logged when a V5.1.x workspace is opened in
Rational Application Developer V6.0, stating that the V6.0 workbench is unable to restore the
perspectives and views that existed in the V5.1.x workspace. This is a known problem with
workspace migration.
An example of the errors messages is shown below:
Problems occurred restoring workbench.
Unable to restore perspective: Workspace - Resource.
Unable to create editor: Web Browser.
Could not create view: com.ibm.etools.j2ee.ui.view.J2EENavigator
Could not create view: com.ibm.etools.webtools.WebView
Could not create view: com.ibm.sed.library.libraryView
Could not create view: com.ibm.etools.server.ui.ServersView
Could not create view: org.eclipse.debug.ui.ConsoleView

The error messages have no impact on the migration of the workspace. After closing the
errors dialogs, all the projects in the workspace are fully operational.

Removing backward compatibility

Compatibility with earlier versions of WebSphere Studio Application Developer can be totally
removed from a project created in IBM Rational Application Developer for WebSphere
Software or a project migrated from an earlier version of WebSphere Studio. This is done only
if the user determines the project should no longer be either interoperable or backward
compatible with WebSphere Studio Application Developer V5.1.x.
When a V5.1.x project is opened in the Rational Application Developer V6.0 workspace, or
new J2EE 1.2 or 1.3 specification projects are created in V6.0, a .compatibility file is
automatically created in the project directory. The .compatibility file is used to track the
timestamps of project resources when these resources are migrated. The .compatibility file
should therefore not be edited or deleted by users.
Backward compatibility can be removed if it is no longer required by the user. To remove
backward compatibility:
1. Right-click an Enterprise Application project; select the Remove Compatibility menu
option from the pop-up.
A dialog launches, asking for confirmation to remove the backward compatibility of the
Enterprise Project and all the modules and utility projects nested under the project.
2. Click Yes to continue with the Remove Compatibility operation.
Once the Remove Compatibility operation is run, the Enterprise Application and all the
Module and Utility projects nested under the Enterprise Applications project are no longer
backward compatible with WebSphere Studio Application Developer 5.1.x.

Chapter 2. Application migration to developer tools

15

JavaServer Faces
Projects developed on WebSphere Studio Application Developer V5.1 which use JavaServer
Faces (JSF) either in Web projects or client applications should migrate the JSF components
to the most current levels found in IBM Rational Application Developer for WebSphere
Software. For more details, see the online help articles Migrating JavaServer Faces
resources in a Web project and Migrating JavaServer Faces resources with Faces Client
Components.

Debugger changes
The debugging facilities in IBM Rational Application Developer for WebSphere Software have
changed from V5. You may need to change settings manually. For more details, see the
online help article Debugger changes.

WebSphere Data Objects

The WebSphere Data Objects (WDO) APIs introduced in WebSphere Studio Application
Developer V5.1 have been replace by Service Data Objects (SDO). Projects developed in
WebSphere Studio Application Developer V5.1 which use WDO are automatically migrated to
use SDO when the server is retargeted to V6. For more details, see the online help article
WDO to SDO migration.
For more information, see the IBM Rational Application Developer for WebSphere Software
Migration Guide. The Migration Guide is found in these locations:
First installation media disk as the file migrate.html in the IBM Rational Application
Developer for WebSphere Software installation directory
Installing and Migrating book in the IBM Rational Application Developer for WebSphere
Software online help. See 1.3, How to obtain more information on page 9 for information
about launching the online help.

16

WebSphere Application Server V6 Migration Guide

Chapter 3.

Changing application code

This chapter discusses application programming interfaces that have become obsolete.

Copyright IBM Corp. 2005. All rights reserved.

17

3.1 J2EE compatibility

WebSphere Application Server Version 6 implements the J2EE 1.4 specification. Each
succeeding specification level supports the preceding levels. As long as your application
complies with these J2EE specifications, your applications should continue to work on
WebSphere Application Server Version 6 unmodified. This makes the process of migration of
applications written for J2EE 1.3 and J2EE 1.2 easier because it allows you to postpone the
application code migration. You can run existing J2EE 1.3 and 1.2 applications in WebSphere
Application Server Version 6 alongside J2EE 1.4 applications until it becomes necessary to
move up to the next level. When migration is required, the process of migration to J2EE 1.4
can be achieved incrementally. In addition to forward compatibility of J2EE specifications,
WebSphere programming extensions are also forward compatible.
We discuss both inconsistencies and deprecations. Inconsistencies require changes in the
code to ensure proper functioning of the migrated code. Deprecations imply that the API or
model change will not be supported in future products; this is an optional but highly
recommended change. Deprecations occur both for the J2EE specifications and the
WebSphere extensions.
If an application does not use any of the deprecated or inconsistent APIs, then the application
usually only needs to be redeployed. Redeployment is accomplished either by using
automatic migration utilities or by manual installation. See Chapter 7, Runtime administration
overview on page 93 for an overview of automatic migration utilities. See Chapter 10,
Runtime application migration examples on page 169 for examples of how to use the
automatic migration utilities and how to perform manual installation.

3.1.1 Incremental migration

Application code migration is not an all or nothing proposition. Forward J2EE compatibility
allows you to migrate to a newer WebSphere runtime without any code changes. Changing
applications requirements may force migrating the code to higher version levels of J2EE at
some later date. Once it becomes clear that migration of the code is required, it is possible to
migrate only those applications or application components that need to use the newer
features. The rest of the application components can remain unchanged. Figure 3-1 shows a
conceptual example of migrating applications incrementally.

Figure 3-1 Incremental migration from J2EE 1.3 to J2EE 1.4

18

WebSphere Application Server V6 Migration Guide

Incremental migration is also possible within an application. A J2EE 1.4 Enterprise

Application Archive (EAR) file can contain J2EE 1.2 or J2EE 1.3 modules, as shown. J2EE is
so flexible that EJB 2.1 modules can define EJB 2.0 or EJB 1.1 beans. If necessary, you can
upgrade a selected set of your beans to take advantage of specific features. You can also
leave the Web module at the J2EE 1.3 level, but migrate the EJB module to J2EE 1.4. This is
an incremental way of migrating applications until it conforms entirely to the new J2EE
standard. Figure 3-2 shows a conceptual example of incrementally migrating modules with an
application.

Figure 3-2 Incremental migration mixing modules of different levels

3.1.2 When to redesign

Application that conform to J2EE specifications remains forward compatible; therefore they
can be redeployed on the newer version of the WebSphere Application Server without any
code changes. However, there are cases when the application needs to be recompiled on a
newer JDK, or needs to be repackaged with a new structure. In some cases, where the code
does not strictly conform to the specification or latest best practice paradigms, the code may
need to be redesigned as part of the migration effort to make use of these newer functions
and paradigms. Please see the article Top 10 J2EE Best Practices at this address:
http://www.ibm.com/developerworks/websphere/techjournal/0405_brown/0405_brown.html

3.2 Code incompatibilities and deprecations

When migrating an application from one version of WebSphere Application Server to the
next, one needs to be aware of these issues.
Deprecated models and API
Incompatibilities
New features and enhancements
Deprecation is the classification of a function or interface as obsolete. The function is still
functional, but it is intended to become an incompatibility in the future. A deprecated class or
interface is supported for two full product releases or three full years, whichever is longer. The
removal window is measured from the point at which the deprecation is announced.
For the purpose of this chapter, we do not discuss the migration of code to exploit the new
features with the exception of areas where there has been a significant model change, such
as Web Services Integration and the new messaging bus. Instead, we concentrate on making
existing J2EE code compatible with both J2EE 1.4 and WebSphere Application Server
Version 6 runtimes and look for areas of incompatibility and deprecation that one must
examine as part of the migration process. In most cases, even if the application code is
compatible with J2EE 1.4 (source code compatibility), it is advisable to recompile the code
using the JDK from WebSphere Application Server Version 6 and using the deployment tools
Chapter 3. Changing application code

19

provided to package and redeploy the code to the WebSphere Application Server Version 6
runtime environment to ensure any packaging, deployment or compile issues are ruled out.
In the Java environment, incompatibilities could be at the binary level or the source level. It is
rare to see binary level incompatibility in applications that are being migrated and thus it is not
generally expected that they would require recompilation using the newer JDK that is
supplied with WebSphere Application Server Version 6 or with the IBM Rational Application
Developer for WebSphere Software. Source code level incompatibility is one area that one
would definitely need to remedy; however, deprecated functions would still run.
For a complete list of all the incompatibilities, including binary incompatibilities, please refer to
the Sun J2EE documentation:
http://java.sun.com/j2se/1.4/compatibility.html

In considering the incompatibilities and deprecations, we look at these major areas:

J2EE differences
J2SE/JDK differences
Application Server runtime differences
Programming Model Extension differences
Third Party Library differences

3.2.1 J2EE 1.3 versus J2EE 1.4 differences

There two main areas of model change in J2EE 1.4. The first and most important area is Web
Services integration, with the introduction of JAX-RPC and SAAJ APIs. This provides the
basic and standards-based Web services support that is both portable and interoperable.
This new specification also describes the packaging and deployment requirements for J2EE
applications that provide and use these Web services. The second important area of change
is a new messaging bus architecture supported by MDBs in EJB 1.1, JMS 1.1. This change
affects both application APIs and how JMS providers are configured. WebSphere Application
Server also provides a new embedded JMS messaging engine as an alternative to the
WebSphere MQ that is included in WebSphere Application Server Version 5.
These changes, taken together, represent model change in a J2EE world that requires an
architectural change in the applications being migrated. In this chapter, we discuss in detail
how applications can be redesigned for Web services and new message bus architecture in
WebSphere Application Server Version 6. For full details about what has changed in J2EE
1.4, please refer to the Sun documentation:
http://java.sun.com/j2ee/j2ee-1_4-fr-spec.pdf

Table 3-1 compares the J2EE application prerequisites for WebSphere Application Server
versions: V3.5, V4.0, V5.0 and V6.0 and their respective J2EE levels.
Table 3-1 J2EE specification levels supported by the WebSphere versions
WAS V3.5
(Pre-J2EE)
J2EE

WAS V5.0
J2EE 1.3

WAS V6.0
J2EE 1.4

1.2

1.3

1.4

EJB

1.0

1.1

1.1/2.0

2.1(2)

Servlet

2.1/2.2(1)

2.2

2.3(2)

2.4(2)

JSP

.91/1.0/1.1(1)

1.1

1.2(2)

2.0

1.0

1.02

1.1

JMS

20

WAS V4.0
J2EE 1.2

WebSphere Application Server V6 Migration Guide

WAS V3.5
(Pre-J2EE)

WAS V4.0
J2EE 1.2

WAS V5.0
J2EE 1.3

WAS V6.0
J2EE 1.4

JTA

1.01

1.01

1.01

1.01

JDBC

1.1/2.0

2.0(4)

2.0(4)

3.0

1.0

1.0

1.0

1.0

1.0

1.0

1.1

1.2

1.3

1.2

1.2

1.2

1.1

1.2

1.0

1.5

1.0

1.0

JAF
RMI/IIOP

1.0

Java Mail
JNDI

1.2

JAXP
Connector

1.03

JAAS
Web Services

1.1

JAX-RPC

1.1

SAAJ

1.2

JAXR

1.0

J2EE
management

1.0

JMX

1.2

J2EE
Deployment

1.1

JACC

1.0

Notes:
1
2
3
4

Servlet 2.2/ JSP 1.1 Introduced in V3.5.2

Superset of Preceding API
Support in AE, JCA Adopted after J2EE 1.2
plus Extension

Most of the changes from J2EE 1.3 to J2EE 1.4 are additive, and hence most code, including
deprecated code, continues to work properly. However, it is always a good programming
practice to deal with all the deprecations in the code at the particular specification level in
order to avoid possible future problems. Deprecated code is sometimes necessary in cases
where the same application needs to continue to run on the previous J2EE specification
levels as well as on the newer J2EE level.
We have intentionally narrowed the discussions here to J2EE 1.3 to limit scope. Migrations
from previous versions of WebSphere runtime have been discussed in a previously released
migration redbook, Migration to WebSphere V5.0 An End-to-End Migration Guide,
SG24-6910-01. This allows developers to migrate their applications to J2EE 1.3 as a stepping
stone to the J2EE 1.4 level discussed here.

J2EE 1.4 deprecation

Applications written to J2EE APIs that are deprecated in J2EE 1.4 do work and may continue
to work in future versions of J2EE. Our recommendation is to remove deprecated APIs when
it is either strictly required due to obsolescence or when it is convenient to do so. It is

Chapter 3. Changing application code

21

important to check in each release to see what has actually been deprecated rather than
assume the default deprecation policy.
For full details of all the J2EE 1.4 deprecations can be found in the Sun Documentation
http://java.sun.com/j2ee/1.4/docs/api/deprecated-list.html

Web services migration

The biggest change in the J2EE 1.4 platform is the strong integration of Web services. J2EE
components can now interact with Web services and implement them in a standard, portable
fashion. For example, a standard way to look up, invoke Web services, and implement Web
services is to use either stateless session beans or plain Java classes mapped to a servlet.
In versions prior to Version 5.0.2, WebSphere Application Server uses an Apache SOAP
engine based Web services. Apache SOAP is not compliant with the Web services
interoperability standards and completely lacks Web services security.
WebSphere Application Server V5.0.2 and WebSphere Application Server V5.1 improve on
the earlier versions to give us an early preview of the standards-based Web services in J2EE
1.4. Key to these are JAX-RPC 1.0 (JSR-101) which is a new standard API for programming
Web services in Java, as well as the accompanying JSR 109, the new deployment model for
Java Web services. These versions include an enhanced engine supporting Web services
over both HTTP and JMS. Web services security and extensions have also been added to
these releases. However, this functionality is based on Draft 13 April 2003 of the Web
services security specification and there may be areas of functionality that differ from the final
draft that was the basis for J2EE 1.4 Web services in WebSphere Application Server Version
6.
Table 3-2 WebSphere Web services standards support
WebSphere Version

Apache SOAP Supported?

JSR 101 - JSR 109

Supported?

V4

Yes

No

V5

Yes

No

V5.0.2, V5.1

Yes

Yes

V6

Yes

Yes

Note that Apache SOAP API and its deployment model have been deprecated in WebSphere
Application Server Version 6. You should re-implement with J2EE 1.4 Web services which
was introduced in WebSphere Application Server V5.0.2. Applications developers can use
the migration wizard in IBM Rational Application Developer for WebSphere Software to
migrate these earlier Web services components to the new J2EE 1.4 specification.

Using the Migration Wizard for Web Services

The Web services artifacts migrated using the J2EE Migration Wizard are:
Web services descriptor
Web services client descriptor
JAX-RPC mapping descriptor

Migrating Web service deployment descriptors

Any Web services deployment descriptors contained in J2EE 1.3 projects migrated to J2EE
1.4 specification level are migrated from JSR-109 V1.0 for J2EE 1.3 to J2EE 1.4. Users
should note the change in the representation of qualified names of Web services deployment
descriptors in J2EE 1.4.
22

WebSphere Application Server V6 Migration Guide

Web service deployment descriptors, as defined by JSR-109 V1.0, consist of

webservices.xml, webservicesclient.xml, and all JAX-RPC mapping deployment descriptors
that are referenced by webservices.xml and webservicesclient.xml.
As with other J2EE deployment descriptors, migration modifies the structure of the
information contained in the descriptors to be J2EE 1.4 compliant. One structural change
which is particular to the Web service deployment descriptors is the change to the way
qualified names are represented. In JSR-109 V1.0, qualified names are represented using a
sequence of two elements, <namespaceURI> and <localpart>, which contain the namespace
URI and the local part of the name, respectively. Qualified names in J2EE 1.4 are based on
the XMLSchema QName type, which uses XML namespaces.

Web services descriptor (webservices.xml)

The webservices.xml deployment descriptor is present in Web projects and EJB projects that
contain J2EE Web services. Both the <wsdl-port> element and the <soap-header> element
contain qualified names and their contents is migrated to the J2EE 1.4 format.
For example, if <wsdl-port> is represented as follows before migration:
<wsdl-port>
<namespaceURI>http://addressbook.webservice</namespaceURI>
<localpart>AddressBook</localpart>
</wsdl-port>

after migration, <wsdl-port> appears as:

<wsdl-port xmlns:pfx="http://addressbook.webservice">pfx:AddressBook</wsdl-port>

pfx is used as the namespace prefix for all migrated qualified names.

Web services client descriptor (webservicesclient.xml)

The webservicesclient.xml deployment descriptor is present in J2EE 1.3 Web projects, EJB
projects and Application Client projects that contain J2EE Web service clients. During
migration from J2EE 1.3 to 1.4, the contents of webservicesclient.xml are migrated and
moved to the deployment descriptor for the project. The process that occurs is as follows:
For Web projects, all <service-ref> elements in webserivcesclient.xml are moved under
the <web-app> element in web.xml.
For Application Client projects, all <service-ref> elements in webservicesclient.xml are
moved under the <application-client> element in application-client.xml.
For EJB projects, all <service-ref> elements within a <component-scoped-refs> in the
webserviceclient.xml are moved under the corresponding <enterprise-bean> in
ejb-jar.xml.
Webservicesclient.xml is then deleted.
Both the <service-qname> element and the <soap-header> element contain qualified names
and their contents are migrated to the J2EE 1.4 format. For example, if <service-qname> is
represented as follows before migration:
<service-qname>
<namespaceURI>http://addressbook.webservice</namespaceURI>
<localpart>AddressBookService</localpart>
</service-qname>

after migration, <service-qname> appears as:

<service-qname
xmlns:pfx="http://addressbook.webservice">pfx:AddressBookService</service-qname>

Chapter 3. Changing application code

23

pfx is used as the namespace prefix for all migrated qualified names.

JAX-RPC mapping descriptor

Both webservices.xml and webservicesclient.xml can reference one or more JAX-RPC
mapping deployment descriptors. In webservices.xml, these references are contained in the
<jaxrpc-mapping-file> element under each <webservice-description>. In
webservicesclient.xml, these references are contained in the <jaxrpc-mapping-file> element
under each <service-ref>. During migration from J2EE 1.3 to 1.4, all the JAX-RPC mapping
deployment descriptors referenced in webservices.xml and webservicesclient.xml are
migrated. Migration includes migrating all qualified names to the J2EE 1.4 format.

Migrating Web services security

Secure Web services are not migrated by the J2EE Migration Wizard when Web services are
migrated from WebSphere Studio Application Developer Version 5.1 to IBM Rational
Application Developer for WebSphere Software Version 6. The migration of Secure Web
Services requires manual steps.
After the J2EE migration, the secure binding and extension files must be migrated manually
to V6.0 as follows:
1. Double-click the webservices.xml to bring up the Web services editor.
2. Select the Binding Configurations tab to edit the binding file.
3. Add all the necessary binding configurations under the new sections "Request Consumer
Binding Configuration Details" and "Response Generator Binding Configuration Details."
4. Select the Extension tab to edit the extension file.
5. Add all the necessary extension configurations under the new sections "Request
Consumer Service Configuration Details" and "Response Generator Service Configuration
Details."
6. Save and exit the editor.

Migrating to Servlet 2.4

In J2EE 1.3, Servlet 2.3 specification, the method HttpSessionListener sessionDestroyed
was defined as notification that a session was invalidated. As of Servlet 2.4, this method is
changed to notification that a session is about to be invalidated so that it notifies before the
session invalidation. If the code assumed the previous behavior, it must be modified to match
the new behavior.
The following methods are added in the ServletRequest interface in this version of the
specification:
public int getRemotePort() returns the Internet Protocol (IP) source port of the client or last
proxy that sent the request.
public java.lang.String getLocalName() returns the host name of the Internet Protocol (IP)
interface on which the request was received.
public java.lang.String getLocalAddr() returns the Internet Protocol (IP) address of the
interface on which the request was received.
public int getLocalPort() returns the Internet Protocol (IP) port number of the interface on
which the request was received.
Be aware that this addition causes source incompatibility in some cases, such as when a
developer implements the ServletRequest interface. In this case, ensure that all the new
methods are implemented correctly.

24

WebSphere Application Server V6 Migration Guide

In Servlet 2.4, SingleThreadModel Interface is deprecated due to its use in a way that is
potentially not thread safe. The best programming practice is to avoid the use of instance
variables, session attributes, and static variables. If it is still necessary, we recommend that
you use synchronized code blocks.
For further details about the J2EE Servlet specifications, download the specifications here:
http://java.sun.com/j2ee/1.4/download.html#platformspec

Migrating Web application artifacts

It is important to migrate the Web module artifacts along with the application code to ensure
proper functioning. Artifacts of a Web deployment descriptor are migrated by the J2EE
Migration Wizard when a J2EE 1.3 specification level Web project is migrated to the J2EE 1.4
specification level.
The following Web application artifacts are migrated.

Authentication constraints
The Description object did not exist in J2EE 1.3; the description was an attribute on the
Authentication Constraint. J2EE 1.4 includes a Description object that has two attributes:
language and value. So, the description is set to value in the Description object.

Security constraints
As above, the description was an attribute of SecurityConstraint. In 1.4, there is a new
Description object with the attributes language and value. So, the description is set to value in
the Description object.

Web application
The ContextParam object in J2EE 1.3 does not exist in J2EE 1.4. In 1.4, there is a common
object called ParamValue. The Web root object in 1.4 contains a list of ParamValue objects
which are like the list of ContextParams on a Web 1.3 root object. So, to get to the
contectParams in 1.4, you need to go through the ParamValue object.
The description string attribute of the ContextParam object in the J2EE 1.3 specification level
has been moved to a Description object in ParamValue in J2EE 1.4.
The TagLib object in J2EE 1.3 has been moved to the JSPConfig object in J2EE 1.4. The
JSPConfig object belonged to the Web root object in 1.3.
The InitParam object in J2EE 1.3 also does not exist in 1.4. In 1.4, there is a common object
called ParamValue. The Servlet and Filter objects in 1.4 contain a list of ParamValue objects
like the list of InitParam on a Web 1.3 root object. To get to the InitParam in 1.4, you need to
go through the ParamValue objects associated with Servlet and Filter objects.

Migrating to JSP 2.0

JSP Specification 1.2 shipped with the J2EE 1.3 SDK. Where possible, the JSP 2.0
specification attempts to be fully backward compatible with the JSP 1.2 specification. In some
cases, there are ambiguities in the JSP 1.2 specification that have been clarified in the JSP
2.0 specification. Because some JSP 1.2 containers behave differently, some applications
that rely on container-specific behavior may need to be adjusted to work correctly in a JSP
2.0 environment.
The following is a list of known backward compatibility issues of which developers who use
JSP technology should be aware:
Tag Library validators that are not namespace-aware and that rely solely on the prefix
parameter might not correctly validate some JSP 2.0 pages. This is because the XML
Chapter 3. Changing application code

25

view might contain tag library declarations in elements other than jsp:root, and might
contain the same tag library declaration more than once, using different prefixes.
The uri parameter should always be used by tag library validators instead. Existing JSP
pages with existing tag libraries do not create any problems.
In JSP specification versions previous to JSP 2.0, JSP pages in XML syntax and those in
standard syntax determined their page encoding in the same fashion, by examining the
pageEncoding or contentType attributes of their page directive, defaulting to ISO-8859-1 if
neither is present. As of JSP Specification V2.0, the page encoding for JSP documents is
determined as described in section 4.3.3 and appendix F.1 of the J2EE 1.4 XML
specification, and the pageEncoding attribute of those pages is only checked to make sure
it is consistent with the page encoding determined as per the XML specification. As a
result of this change, JSP documents that rely on their page encoding to be determined
from their pageEncoding attribute can no longer be decoded correctly.
These JSP documents must be changed to include an appropriate XML encoding
declaration. Additionally, in the JSP 1.2 Specification, page encodings are determined on
a per translation unit basis, whereas in the JSP 2.0 Specification, page encodings are
determined on a per-file basis. For example, consider a JSP page A that specifies a page
encoding. It statically includes JSP page B which does not specify an encoding. Under
JSP 1.2, B inherits the encoding from A. Under JSP 2.0, B picks up the default encoding
and does not inherit the encoding from A.
The JSP container uses the version of web.xml to determine the default behavior of
various container features. The following is a list of items of which JSP developers should
be aware when upgrading their web.xml from Servlet Version 2.3 Specification to Servlet
Version 2.4 Specification.
EL expressions are ignored by default in applications created with JSP 1.2 technology.
When upgrading a Web application to the JSP 2.0 Specification, EL expressions are
interpreted by default. The escape sequence \$ can be used to escape EL expressions
that should not be interpreted by the container. Alternatively, the isELIgnored page
directive attribute or the el-ignored configuration element can deactivate EL for entire
translation units. Users of JSTL 1.0 need to either upgrade their taglib/ imports to the JSTL
1.1 URIs, or they need to use the _rt versions of the tags (for example, c_rt instead of c, or
fmt_rt instead of fmt).

Migrating to EJB 2.1

The EJB 2.1 specification includes important enhancements to EJB-QL, a new timer service,
and the extension of message-driven beans (MDBs) to support any type of messaging
system, not just JMS.
A major change in EJB 2.1 is that MDBs have been extended to support any message type,
not just JMS. This allows configuration of any proprietary messaging provider and incoming
asynchronous messages handling by business logic written to the MDB programming model.
This is done by adding a J2EE Connector resource adapter, provided by the vendor, that
translates incoming messages into calls to the MDB. See Migrating to JMS 1.1 on page 29
for more information about JMS 1.1.

Migrating EJBs
The J2EE Migration Wizard supports the migration of Enterprise Bean deployment
descriptors from J2EE 1.3 specification level EJB resource to J2EE 1.4 specification level.
Stateless Session Beans and Message Driven Beans are migrated to J2EE 1.4.
The J2EE Migration Wizard migrates Stateless Session Beans that are defined as Service
End Point interfaces (SEI) in an EJB project to the J2EE 1.4 specification level by creating
new Service End Point interfaces on the stateless session bean.
26

WebSphere Application Server V6 Migration Guide

The J2EE 1.4 specification requires a SEI be defined on a Stateless Session Bean if the
session bean is to be used as a Web Services endpoint. During the migration of an EJB JAR,
all session beans in the EJB project get a new SEI that uses the name used in the
webservices.xml descriptor of the EJB project.
Example 3-1 shows how the metadata of an EJB project looks at the J2EE 1.3 specification
level. The <service-endpoint-interface> and <service-impl-bean> tags define Stateless
Session Bean "EchoEJB" as a Service Endpoint in the Web services descriptor at the J2EE
1.3 specification level prior to migration.
Example 3-1 J2EE 1.3 Web services project
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE webservices PUBLIC "-//IBM Corporation, Inc.//DTD J2EE Web services 1.0//EN"
"http://www.ibm.com/webservices/dtd/j2ee_web_services_1_0.dtd">
<webservices id="WebServices_1084831328093">
<webservice-description id="WebServiceDescription_1084831328093">
<webservice-description-name>EchoEJBService</webservice-description-name>
<wsdl-file>META-INF/wsdl/EchoEJB.wsdl</wsdl-file>
<jaxrpc-mapping-file>META-INF/EchoEJB_mapping.xml</jaxrpc-mapping-file>
<port-component id="PortComponent_1084831328103">
<port-component-name>EchoEJB</port-component-name>
<wsdl-port id="WSDLPort_1084831328103">
<namespaceURI>http://test</namespaceURI>
<localpart>EchoEJB</localpart>
</wsdl-port>
<service-endpoint-interface>test.EchoEJB</service-endpoint-interface>
<service-impl-bean id="ServiceImplBean_1084831328103">
<ejb-link>EchoEJB</ejb-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>

Example 3-2 shows a J2EE 1.4 EJB Deployment Descriptor for the stateless session bean
"EchoEJB" with service endpoint interface created by the migration wizard. The
<service-endpoint> tag defines "EchoEJB" as a Service Endpoint in J2EE 1.4 specification
level.
Example 3-2 J2EE 1.4 Web services project
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar>
<ejb-jar id="ejb-jar_ID" version="2.1" xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">
<display-name>
EchoEJBProject</display-name>
<enterprise-beans>
<session id="EchoEJB">
<ejb-name>EchoEJB</ejb-name>
<home>test.EchoEJBHome</home>
<remote>test.EchoEJB</remote>
<service-endpoint>test.EchoEJB</service-endpoint>
<ejb-class>test.EchoEJBBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
</session>
</enterprise-beans>
Chapter 3. Changing application code

27

</ejb-jar>

Migrating Message Driven Beans

The J2EE Migration Wizard supports the migration of EJB 2.0 Message Driven Beans to EJB
2.1 Java Message Service (JMS) type Message Driven Beans.
Message Driven Beans were introduced in EJB 2.0 to support the processing of
asynchronous messages from a Java Message Service (JMS). The EJB 2.1 specification
expands the definition of the Message Driven Bean so that it can support any messaging
system, not just JMS.
The EJB 2.0 Message Driven Bean artifacts migrated are:

acknowledgeMode
messageSelector
destinationType
subscriptionDurablity

Some of the EJB 2.0 Message Driven Bean elements are replaced with activation-config
properties. The property names and values used in the activation-config to describe the
messaging service vary depending on the type of message service used. However, EJB 2.1
defines a set of fixed properties for JMS-based message-driven beans.
Example 3-3 shows the elements of a sample bean in EJB 2.0. Contrast this with
Example 3-4 which shows how the elements appear in EJB 2.1.
Example 3-3 EJB 2.0 descriptor for Message Driven Bean
<message-driven id="Mdb20">
<ejb-name>Mdb</ejb-name>
<ejb-class>ejbs.MdbBean</ejb-class>
<transaction-type>Bean</transaction-type>
<message-selector>mdbMessage</message-selector>
<acknowledge-mode>Auto-acknowledge</acknowledge-mode>
<message-driven-destination>
<destination-type>javax.jms.Topic</destination-type>
<subscription-durability>Durable</subscription-durability>
</message-driven-destination>
</message-driven>
Example 3-4 EJB 2.1 descriptor for Message Driven Bean
<message-driven id="Mdb21">
<ejb-name>Foo/ejb-name>
<ejb-class>ejbs.FooBean</ejb-class>
<messaging-type>javax.jms.MessageListener</messaging-type>
<transaction-type>Bean/transaction-type>
<message-destination-type>javax.jms.Topic</message-destination-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>destinationType</activation-config-property-name>
<activation-config-property-value>javax.jms.Topic</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>subscriptionDurability</activation-config-property-name>
<activation-config-property-value>Durable</activation-config-property-value>
</activation-config-property>
<activation-config-property>

28

WebSphere Application Server V6 Migration Guide

<activation-config-property-name>acknowledgeMode</activation-config-property-name>
<activation-config-property-value>AutoAcknowledge</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>messageSelector</activation-config-property-name>
<activation-config-property-value>fooSelector</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>

Migrating to JCA 1.5

The J2EE Migration Wizard migrates the artifacts of a JCA 1.0 descriptor to JCA 1.5. These
are changed:
The following elements are moved from ResourceAdaptor object to
OutboundResourceAdaptor object:
reauthenticationSupport
transactionSupport
The following elements are moved from ResourceAdaptor object to the
ConnectionDefinition object:

managedConnectionFactoryClass
connectionFactoryInterface
connectionFactoryImplClass
connectionInterface
connectionImplClass

The outboundResourceAdaptor holds a list of ConnectionDefinitions. Therefore, the

ConnectionDefinition is added to the ConnectionDefinitions held by
OutboundResourceAdaptor.
The OutboundResourceAdaptor is held by the ResourceAdaptor object.
The AuthenticationMechanism has undergone some changes in JCA 1.5 where
customAuthMechType is replaced by authenticationMechanism and authenticationType is
replaced by authenticationMechanism.
The description attribute is replaced with a Description object where the description string
is set to a value element in the Description Object for the following objects:
SecurityPermission
AuthenticationMechanism
ConfigurationProperties

Migrating to JMS 1.1

Although JMS 1.0 applications would continue to run in J2EE, there are some new features,
requirements and restrictions that come with JMS 1.1 and Message Driven Beans in J2EE
1.4 of which application developers have to be aware.
For a more in-depth look at the issues, the reader is referred to an article by David Currie on
the IBM DeveloperWorks site at:
http://www-106.ibm.com/developerworks/java/library/j-getmess/

Chapter 3. Changing application code

29

3.2.2 J2SE
The J2EE runtime consists of the Web container, the EJB container, the applet container and
the application client container. The containers are J2EE runtime environments that provide
required services to the application components. For example, the application client container
provides application clients with direct access to the J2EE required database through the
Java API for connectivity with database systems, the JDBC API. Similar access to databases
is provided to JSP pages and servlets by the Web container, and to enterprise beans by the
EJB container.
WebSphere Application Server V5.1 is the first version to adopt J2SE 1.4. A number of
changes to the Java language have taken place in J2SE 1.4. These changes may impact
your application (For example, JDK 1.4 includes an XML implementation that may potentially
conflict with XML libraries your application uses.). In most cases, the changes have no
impact.

Compatibility
For full details about all the J2SE 1.4 incompatibilities, please refer to this Sun Java article:
http://java.sun.com/j2se/1.4/compatibility.html

Deprecation
For a full list of deprecated APIs for J2SE 1.4 platform, please refer to this Sun Java article:
http://java.sun.com/j2se/1.4.2/docs/api/deprecated-list.html

JDBC 3.0
The JDBC 3.0 API, included as part of the J2SE 1.4 platform, introduces two new interfaces
and adds several new methods to existing interfaces. Drivers and applications that use earlier
versions of the JDBC API are binary compatible with the J2SE 1.4 platform and run without
any problems. However, the changes made in the JDBC 3.0 API are not source-compatible.
Drivers and applications that implement the JDBC interfaces must be updated to reflect the
changes in order to build successfully. Chapter 6 of the JDBC 3.0 Specification gives a
complete list of what must be done to be compliant with the JDBC 3.0 API, and therefore
source-compatible with the J2SE 1.4 platform. You can find the JDBC 3.0 Specification at this
location:
http://java.sun.com/products/jdbc/download.html

For applications using JDBC APIs prior to JDBC 2.0, these are some significant deprecations
that should be noted:

30

java.sql.CallableStatement.getBigDecimal(int, int)
java.sql.Date(int, int, int)
java.sql.Date.getHours()
java.sql.Date.getMinutes()
java.sql.Date.getSeconds()
java.sql.Date.setHours(int)
java.sql.Date.setMinutes(int)
java.sql.Date.setSeconds(int)
java.sql.DriverManager.getLogStream()
java.sql.DriverManager.setLogStream(PrintStream)
java.sql.PreparedStatement.setUnicodeStream(int, InputStream,int)
java.sql.ResultSet.getBigDecimal(int, int)
java.sql.ResultSet.getBigDecimal(String, int)
java.sql.ResultSet.getUnicodeStream(int)
java.sql.ResultSet.getUnicodeStream(String)

WebSphere Application Server V6 Migration Guide

java.sql.Time(int, int, int)

java.sql.Time.getDate()
java.sql.Time.getDay()
java.sql.Time.getMonth()
java.sql.Time.getYear()
java.sql.Time.setDate(int)
java.sql.Time.setMonth(int)
java.sql.Time.setYear(int)
java.sql.Timestamp(int, int, int, int, int, int, int)

3.2.3 WebSphere API incompatibilities

There is one incompatibility that may affect your applications.

Slash character on the getResource path

WebSphere Application Server Version 6 changed its behavior relative to how it treats the
path on the getResource and getResourceAsStream methods when called from a servlet
context.
The J2EE Servlet 2.3 specification defines these methods such that the resource path is
required to begin with a slash character. The specification is summarized for you here:
getResource(String)
public java.net.URL getResource(java.lang.String path)
throws MalformedURLException

This returns a URL to the resource that is mapped to a specified path. The path must begin
with a / and is interpreted as relative to the current context root.
getResourceAsStream(String)
public java.io.InputStream getResourceAsStream(java.lang.String path)

This returns the resource located at the named path as an InputStream object. The data in
the InputStream can be of any type or length. The path must be specified according to the
rules given in getResource.
WebSphere Application Server Version 5 does not enforce the specification requirement that
the path begin with slash. It accepts a path regardless of whether the path begins with slash.
However, WebSphere Application Server Version 6 is more stringent and requires that the
path begin with slash. Failure to do so results in a MalformedURLException exception.
Even if your code does not use getResource or getResourceAsStream, your application may
encounter this incompatibility because your application uses a third-party library which then
uses one of these methods. One third-party library that is known to have this problem is the
Apache Struts framework.
You can eliminate this problem without changing any code. WebSphere Application Server
Version 6 allows you to establish a compatibility mode such that the behavior is identical to
that of V5. You need to set the custom property prependSlashToResource for the Web
container of the application server running the application. This setting is global to the entire
server and affects every application on that server. See 7.5.3, getResource path syntax on
page 120 for information about how to set the prependSlashToResource property.

3.2.4 WebSphere API deprecations

There are several WebSphere specific APIs that have been deprecated over various
releases. Table 3-3 on page 32 shows a summary of those deprecations.
Chapter 3. Changing application code

31

Table 3-3 WebSphere specific deprecations

Function

Release
when
deprecated

UDDI Registry V2 EJB interface

6.0

UDDI4J V2

6.0

UDDI Utility Tools APIs

6.0

Apache SOAP implementation

6.0

Web Service Security Draft 13 specification-level

6.0

Package com.ibm.websphere.servlet.filter

6.0

MIME filtering

6.0

WebSphere JRAS Extensions API

6.0

Package com.ibm.websphere.product.product

6.0

Data Access Beans

6.0

PMI Client

6.0

J2EE Connector Architecture

6.0

Method Level Access Intent

6.0

getStackTrace

5.1

JSP tsx tags

5.1

Common Connector Framework

5.1

Security API

5.1

For more information about deprecations, see this InfoCenter article: Deprecated features in
Version 6.0, found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.expres
s.doc/info/exp/ae/rmig_deprecationlist.html

UDDI Registry V2 EJB interface

This interface is included in WebSphere Application Server Version 6 for compatibility with
V5. There is no replacement API.

UDDI4J V2
A client library is provided to simplify constructing and sending UDDI V3 requests from Java.
This is the IBM UDDI V3 Client for Java, provided in uddiv3client.jar. The UDDI4J APIs
(uddi4jv2.jar) may still be used. Migrate to V3 UDDI APIs.

UDDI Utility Tools APIs

All of the low-level APIs such as BusinessStub and ServiceStub are deprecated. Migrate to
the PromoterAPI in place of these low-level APIs. The PromoterAPI provides the same
functionality at a higher level of abstraction.

Apache SOAP Security

Apache SOAP Security, which uses a XML digital signature, is deprecated. Migrate to the
JSR-109 implementation of Web services and Web Service Security 1.0.
32

WebSphere Application Server V6 Migration Guide

Web Services Security Draft 13 Specification Support

Applications should be migrated to the supported WSS 1.0 standard. The draft-level support
does not provide interoperability with some third-party vendors, since the message level has
been changed between the draft and the WSS 1.0 implementation.
WSS 1.0 is only supported in J2EE 1.4 applications, therefore you need to migrate
applications to J2EE 1.4 first. Migration is a manual step.

Package com.ibm.websphere.servlet.filter
These classes are included in this package:

ChainedRequest
ChainedResponse
ChainerServlet
ServletChain

Redesign your application to use javax.servlet.filter classes. Starting from the Servlet 2.3
specification, javax.servlet.filter classes give you the capability to intercept requests and
examine responses. They also allow you to achieve chaining functionality, as well as
embellishing or truncating responses.

MIME filtering
MIME filtering is deprecated. MIME filters were first introduced in WebSphere Application
Server V3.5 as a way for servlets to embellish, truncate, and/or modify the responses
generated by other servlets, based on the MIME types of the output content. Migrate to
javax.servlet.filter classes.

WebSphere JRAS Extensions API

The WebSphere JRAS Extensions API is deprecated in this release. No further
enhancements are planned for JRAS support. Migrate to java.util.logging package (JSR47).

Package com.ibm.websphere.product.product
All the methods and fields in com.ibm.websphere.product.product and
com.ibm.websphere.product.buildInfo classes are deprecated. Hence, the following methods
from com.ibm.websphere.product.WASProduct class (which involves
com.ibm.websphere.product.product and com.ibm.websphere.product.buildInfo objects) are
deprecated:
public
public
public
public
public
public
public
public
public
public

product getProductByFilename(String basename)

product getProductById(String id)
boolean productPresent(String id)
boolean addProduct(product aProduct)
boolean removeProduct(product aProduct)
Iterator getProducts()
Iterator getProductNames()
String loadVersionInfoAsXMLString(String filename)
String getProductDirName()
static String computeProductDirName()

Use the following supported methods from com.ibm.websphere.product.WASDirectory:

public
public
public
public

WASProductInfo getWASProductInfo(String id)

boolean isThisProductInstalled(String id)
WASProductInfo getWASProductInfoInstances()
String getWasLocation()

Chapter 3. Changing application code

33

Also, instead of getting product information (name, version, build level, build date) from the
old WASProduct API (com.ibm.websphere.product.WASProduct), you should now use the
following methods in the WASDirectory class to get that information:
com.ibm.webpshere.product.WASDirectory.getName(String)
com.ibm.webpshere.product.WASDirectory.getVersion(String)
com.ibm.webpshere.product.WASDirectory.getBuildLevel(String)
com.ibm.webpshere.product.WASDirectory.getBuildDate(String)

Data Access Beans

Data Access Beans APIs, which are in databeans.jar, are deprecated. Migrate to Service
Data Objects (SDO). See this InfoCenter article for more information about SDO: Data
access with Service DataObjects, found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.expres
s.doc/info/exp/ae/cdat_datsdo.html

PMI Client
The PMI Client API, which was introduced in V4.0 to programmatically gather performance
data from WebSphere Application Server, is deprecated.
The Java Management Extension (JMX) interface, which is part of the J2EE specification, is
the recommended way to gather WebSphere Application Server performance data. PMI data
can be gathered from the J2EE-managed object MBeans, or from the WebSphere PMI Perf
MBean. While the J2EE MBeans provide performance data about a specific component, the
Perf MBean acts as a gateway to the WebSphere Application Server PMI service, and
provides access to the performance data for all the components.

J2EE Connector Architecture

The following in the J2EE Connector Architecture runtime are deprecated:
com.ibm.ws.management.descriptor.xml.ConnectionFactory.xml. getPoolContents
method is replaced by showPoolContents. getAllPoolContents method is replaced by
whoAllPoolContents.
com.ibm.websphere.j2c.ConnectionManager interface is replaced by J2EE Connector
Architecture 1.5 LazyAssociatableConnectionManager interface
com.ibm.websphere.j2c.ConnectionEventListener interface is replaced by J2EE
Connector Architecture 1.5 LazyEnlistableConnectionManager interface

Method level access intent

Container-managed persistence (CMP) entity beans configured with method level access
intent may run into data access problems, such as a deadlock. Therefore, the method level
access intent is deprecated. Reconfigure CMP entity beans to use bean level access intent.

com.ibm.websphere.servlet.error.ServletErrorReport.getStackTrace
This is not really a deprecation. It is really an incompatibility cause by a method signature
collision with a method defined in J2SE 1.4. The changed class is
com.ibm.websphere.servlet.error.ServletErrorReport. The return signature for getStackTrace
is changed because java.lang.Throwable now defines the same method with a different return
signature.
Old method signature:
public String getStackTrace();
// returns a String representation of the
exception stack

34

WebSphere Application Server V6 Migration Guide

New method signature (JDK 1.4, WebSphere Application Server Version 5.1)
public StackTraceElement[] getStackTrace();
// returns an array of stack trace
elements

A replacement method that has the same signature as the old method is provided:
public String getStackTraceAsString();
// returns a String representation
of the Exception Stack

JSP tsx tags

Support for the following tsx tags in the JSP engine is deprecated:

repeat
dbconnect
dbquery
getProperty
userid
passwd
dbmodify

Instead of using the tsx tags, you should use equivalent tags from the Java Server Pages
Standard Tag Library (JSTL). JSTL is supported in WebSphere Application Server Version 6,
and the tag library is shipped with the product. Use Table 3-4 as a guideline for converting tsx
tags to JSTL tags.
Table 3-4 JSP tsx tags:
tsx tag

JSTL tag

tsx:repeat

c:forEach

tsx:dbconnect

sql:setDataSource

tsx:dbquery

sql:query

tsx:getProperty

use standard EL syntax, for example, c:out value="${book.title}",

where book is the current index in the result set

tsx:userid

use the user attribute of the setDataSource tag

tsx:passwd

use the password attribute of the setDataSource tag

tsx:dbmodify

sql:update

Common Connector Framework

The following jar files are deprecated:

ccf.jar
ccf2.jar
recjava.jar
eablib.jar

The J2EE Connector Architecture APIs should be used instead of the Common Connector
Framework.

Security APIs
These APIs have been deprecated:

Chapter 3. Changing application code

35

 com.ibm.websphere.security.auth.WSPrincipal.getCredential should be replaced by either

com.ibm.websphere.security.auth.WSSubject.getRunAsSubject or
com.ibm.websphere.security.auth.WSSubject.getCallerSubject.
com.ibm.websphere.security.auth.WSSecurityContext should be replaced by JAAS APIs.
com.ibm.websphere.security.auth.WSSecurityContextException should be replaced by
JAAS APIs.
com.ibm.websphere.security.auth.WSSecurityContextResult should be replaced by JAAS
APIs.

3.2.5 Programming Model Extensions

WebSphere Application Server Version 6 makes the WebSphere Programming Model
Extensions available at more basic levels of the product line. The strategy for V4 and V5
makes these extensions available only in upper tier products such as WebSphere Application
Server Enterprise and WebSphere Business Integration Server Foundation. The strategy for
Version 6 makes most available in the most basic product tier, namely in WebSphere
Application Server Express. The migration tools in IBM Rational Application Developer for
WebSphere Software copy and migrate applications using extension features supported in
Version 6. If the extension is not supported, the application is not copied over to Version 6.
Table 3-5 shows that the WebSphere products that contain the Programming Model
Extensions have changed over time.
Table 3-5 IBM Programming Extensions mapped to containing products

36

Extension

WebSphere
V4

WebSphere
V5

WebSphere
V5.1

WebSphere V6

Business Rule
Beans

Enterprise

Enterprise

WBISF

WBISF

Process
Choreography

Enterprise

Enterprise

WBISF

WBISF

Extended
Messaging

Enterprise

Enterprise

WBISF

WBISF

CORBA C++ SDK

Enterprise

Enterprise

WBISF

Not Supported

Application Profiling

Enterprise

Enterprise

WBISF

Express / Base / ND

Work Area

Enterprise

Enterprise

WBISF

Express / Base / ND

Distributed Map

Enterprise

WBISF

Express / Base / ND

Startup Beans

Enterprise

WBISF

Express / Base / ND

Activity Session

Enterprise

WBISF

Express / Base / ND

Internationalization

Enterprise

WBISF

Express / Base / ND

Asynchronous
Beans

Enterprise

WBISF

Express / Base / ND

Object Pool

Enterprise

WBISF

Express / Base / ND

Dynamic Query

Enterprise

WBISF

Express / Base / ND

Last Participant

Enterprise

WBISF

Express / Base / ND

Extended JTA

Enterprise

WBISF

Express / Base / ND

WebSphere Application Server V6 Migration Guide

Extension

WebSphere
V4

WebSphere
V5

WebSphere
V5.1

WebSphere V6

Backup Clusters

Enterprise

WBISF

ND

WSWG Filters

Enterprise

WBISF

ND

Extensions no longer supported

C++ CORBA applications are no longer supported in WebSphere Application Server Version
6. Reimplement with JAVA ORB API.

3.2.6 Third-party libraries

WebSphere Application Server treats third-party libraries the same as your application code.
Libraries composed of Java code should continue to work with little modification on
WebSphere Application Server Version 6. However, many libraries do have dependencies on
particular versions of the application server. To complicate matters, most library vendors do
not provide source code or permission to change their code, which can sometimes leave you
at their mercy for support.

Parser compatibilities
Inclusion of the JAXP 1.2 specification means that J2EE 1.4 application servers now have
XSLT engines, SAX 2.0, and DOM level 2 parsers included. You can write your XML
processing code once and swap in third-party parsers or XSLT engines as necessary, without
changes to the source code. This is a step forward from J2EE 1.3, which included only JAXP
1.0, which did not support XSLT or the latest DOM/SAX technologies. If your code relies on
inclusion of your own parsers, you may need to change the application code as well as the
class loader settings to take advantage of system parsers in WebSphere Application Server
Version 6.
There are really two cases to consider when migrating from previous versions of WebSphere
Application Server. The first case is where an application has an intentional dependency on
the system XML parsing classes (org.apache.xerces and org.apache.xalan). You need to be
aware that Xerces classes and version levels that were included with previous WebSphere
Application Server versions cannot be relied upon. Previous versions of WebSphere
Application Server included these for convenience, since they were not specified in J2SE,
J2EE or IBM programming extensions API.
In WebSphere Application Server Version 5.1 and Version 6, all classes became part of J2SE
1.4 standard, therefore the lib/xerces.jar no longer exists. WebSphere Application Server
Version 5.1 and Version 6 components rely on the J2SE XML classes supplied with the
runtime. Make sure that your migrated applications code and classpath conform to these
newer version levels of the parser API.
The second case is where the application developer has packaged their own XML classes in
the EAR, and due to class loader settings, ends up picking up the system classes. In this
case, you may need to change the class loader settings to ensure you pick up the parser
classes in the EAR. The class loader settings and defaults are the same between V5.x and
V6.x, so if the settings were correctly set, they would remain correctly set, assuming that the
default setting was also moved across during migration of the runtime configuration.
See 7.5.1, Class loader on page 114 for more information about the class loader settings
changes.

Chapter 3. Changing application code

37

38

WebSphere Application Server V6 Migration Guide

Chapter 4.

Development migration
scenarios
This chapter provides real examples of migrating an application to IBM Rational Application
Developer for WebSphere Software with step-by-step instructions.

Copyright IBM Corp. 2005. All rights reserved.

39

4.1 Migrating from WebSphere Studio Application Developer

Version 5.1 to IBM Rational Application Developer for
WebSphere Software Version 6
The migration examples in this section all start with the Plants By WebSphere application
installed in WebSphere Studio Application Developer Version 5.1. This is a sample
application that can be downloaded from the DeveloperWorks Web site at this location:
http://www-106.ibm.com/developerworks/websphere/library/samples/WASV501/plantsby.html

In addition to the import and configuration of the Plants By WebSphere application into the
WebSphere Studio Application Developer workspace, the required tables have been created
in a Cloudscape database called PLANTSDB. See the documentation that comes with the
sample for instructions on creating the database.
For all the examples in this section, IBM Rational Application Developer for WebSphere
Software Version 6 can be installed on the same system as WebSphere Studio Application
Developer, or on a different system.

4.1.1 Example: Migrating Plants By WebSphere using the Export/Import

method
This example shows you how to migrate a project by exporting your existing project into an
EAR file and then importing that same EAR file into a new workspace.

Preparing the Enterprise Applications for export from WebSphere

Studio Application Developer
Before exporting the Enterprise Applications from WebSphere Studio Application Developer,
it is a good idea to delete the artifacts that were generated by that tool during EJB
deployment.
1. Start WebSphere Studio Application Developer and open the workspace containing the
PlantsByWebSphere application.
2. Switch to the J2EE Hierarchy. Expand EJB Modules -> PlantsByWebSphereEJB and
expand both Session Beans and Entity Beans.
3. Highlight the six session beans and six entity beans.
4. Right-click the selection and choose Delete....

Figure 4-1 Deleting existing EJBs

40

WebSphere Application Server V6 Migration Guide

5. Deselect Delete Bean Only, Delete Bean classes and Delete Access Bean. This should
leave just Delete Deployed code checked.
6. Click OK.
7. Expand the SupplierEJB project and expand Session Beans.
8. Highlight the one session bean and delete the deployed code as with the previous project.
9. Switch to the J2EE Navigator view and expand PlantsByWebSphereEJB -> ejbModule.
10.Delete all packages except com.ibm.websphere.samples.plantsbywebsphereejb.
11.Expand SupplierEJB -> ejbModule.
12.Delete all packages except com.ibm.websphere.samples.supplierejb.

Exporting the Enterprise Applications from WebSphere Studio

Application Developer
1. In the J2EE Navigator view, right-click the Plants project and select Export.
2. Select EAR file and click Next>.
3. Type C:\Plants.ear for the Destination.
4. Check the box next to Export source files.
5. Click Advanced... and check the box to Include project build paths and meta-data
files. Click OK.
6. Click Finish.
7. Export the PlantsSupplier project into C:\PlantsSupplier.ear using the same procedure as
used to export the previous project.
8. Close WebSphere Studio Application Developer.

Importing the Enterprise Applications into IBM Rational Application

Developer for WebSphere Software
1. Start IBM Rational Application Developer for WebSphere Software and open a new
workspace.

Chapter 4. Development migration scenarios

41

Figure 4-2 Initial screen for IBM Rational Application Developer for WebSphere Software

2. Close the Welcome view to access the Workbench.

3. Select File -> Import. Select EAR file for the import source and click Next>.
4. Browse to the Plants EAR that you exported from WebSphere Studio Application
Developer.
5. Confirm that the EAR project is set to Plants, Import EAR Project is checked and the
Target Server is set to WebSphere Application Server Version 6.
6. Click Finish.
7. If prompted to switch to the J2EE Perspective, click Yes.
8. Select File -> Import. Select EAR file for the import source and click Next>.
9. Browse to the PlantsSupplier EAR that you exported from WebSphere Studio Application
Developer.
10.Confirm that the EAR project is set to PlantsSupplier, Import EAR Project is checked
and the Target Server is set to WebSphere Application Server V6.0.

42

WebSphere Application Server V6 Migration Guide

11.Click Finish.

Figure 4-3 Importing an EAR project

12.After the import completes, watch the lower right corner of IBM Rational Application
Developer for WebSphere Software. Wait for all background tasks to complete. At this
point, there are two errors (problems with dds.xml) and a significant number of warnings in
the Problems view.
The code validators in IBM Rational Application Developer for WebSphere Software have
been enhanced to provide warnings on many that were not in WebSphere Studio Application
Developer. A close examination of the warnings shows that they address code maintenance
issues, but do not represent problems with the code. They can safely be ignored.
The errors in dds.xml are due to name space issues in XML files. These errors can also be
ignored.

Migrating the Enterprise applications

1. In the Project Explorer view, expand Enterprise Applications.
2. Right-click Plants and select Migrate->J2EE Migration Wizard....

Chapter 4. Development migration scenarios

43

3. On the J2EE Migration Wizard Welcome Page click Next>.

Figure 4-4 J2EE Migration Wizard

4. On the Enterprise Application page, click Finish to migrate the entire application.
5. When the Migration Complete dialog appears, click OK.
6. Use the same steps to migrate the PlantsSupplier application.

Adding the Data Source definition to the Plants application

It is possible to define the Data Source that is used by the Plants application directly on the
server that we deploy to, as is done in WebSphere 5. By putting the Data Source definition in
the extended application deployment descriptor instead, we ensure that the data source is
created on any application server to which we deploy the application.
1. In the Project Explorer view, expand Enterprise Applications -> Plants and double-click
Deployment Descriptor.
2. Click the Deployment tab of the Deployment Descriptor editor.
3. Select Cloudscape JDBC Provider(XA) in the JDBC Provider list.

44

WebSphere Application Server V6 Migration Guide

4. Click Add... next to Data source defined in the JDBC provider to define the data source.

Figure 4-5 Creating a data source

Chapter 4. Development migration scenarios

45

5. Select Cloudscape JDBC Provider (XA) and Version 5.0 data source. Click Next>.

Figure 4-6 Data source attributes

6. Type the Name: PLANTSDB.

7. Type the JDBC name: jdbc/PlantsByWebSphereDataSource.
8. Ensure that the Data source helper class name is
com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper.
9. Ensure that Use this data source in container managed persistence is checked.

46

WebSphere Application Server V6 Migration Guide

10.Click Next>.

Figure 4-7 Data source custom properties

11.Type the appropriate value for the databaseName. This should be the same value as was
used to run the application under WebSphere Studio Application Developer. For
Cloudscape, the databaseName is the name of a directory that contains the Cloudscape
database. If the PLANTSDB is not present on the IBM Rational Application Developer for
WebSphere Software system, it should be copied from the WebSphere Studio Application
Developer system at this time.
12.Click Finish.
13.Close the Application Deployment Descriptor editor and save the deployment descriptor.

Updating the PurchaseOrders MDB To use a JCA Adapter

The PurchaseOrders MDB was configured in WebSphere Studio Application Developer to
use a ListenerPort. We are using WebSphere 6 default messaging, so this must be changed
to the new option for MDBs: JCA adapter.
1. In the Project Explorer View, expand EJB Projects -> SupplierEJB and double-click
Deployment Descriptor.

Chapter 4. Development migration scenarios

47

2. Click the Beans tab of the EJB Deployment Descriptor editor and select the
PurchaseOrders MDB EJB.

Figure 4-8 EJB bindings

3. Under WebSphere Bindings, click the JCA Adapter radio button.

4. For ActivationSpec JNDI name, type jms/PurchaseOrdersActivation.
5. For Destination JNDI name, type jms/PurchaseOrdersQueue.
6. Close the EJB Deployment Descriptor editor and save the deployment descriptor.

Generating deploy code for EJB applications

1. In the Project Explorer view, expand EJB Projects and select both
PlantsByWebSphereEJB and SupplierEJB.
2. Right-click the selected projects and select Deploy. A progress dialog appears and
indicates when the deployment is complete.

Figure 4-9 Generating deploy code for EJB

3. If you click Run in Background, you can monitor the progress by watching the lower right
corner of the workbench.

Starting the test server

The test environment in IBM Rational Application Developer for WebSphere Software is
significantly different from the test environment in WebSphere Studio Application Developer
5. Most configuration is done using the standard WebSphere administrative console, and
most actions (such as adding and removing applications) are performed with the server
running.
1. Click the Servers view.

48

WebSphere Application Server V6 Migration Guide

2. Double-click WebSphere Application Server 6.0 to launch the server configuration

editor.

Figure 4-10 Server configuration editor

Notice that the editor has been simplified. Most of the configuration that was managed by
the WebSphere Studio Application Developer 5 Server Editor is managed in the
administrative console.
3. Close the WebSphere Application Server editor.
4. In the Servers view, right-click WebSphere Application Server 6.0 and select Start.
5. When the server status changes to Started, right-click the server and select Run
administrative console. This launches the standard WebSphere 6.0 administrative
console.
6. Type migration for the User ID (the User ID is only used for tracking changes to the
configuration.) and click Log in.

Configuring the Mail Provider

This task is optional and is virtually identical to the Mail Provider configuration in WebSphere
5.
1. Open Resources in the left panel of the administration console. Select Mail Providers.
2. Ensure that a scope of Node is selected.
3. Click the Built-in Mail Provider provider to modify it.
4. In the Additional Properties section, click Mail Sessions.
5. Click New. Enter a Name of PlantsByWebSphere Mail Session. Also enter a JNDI name of
mail/PlantsByWebSphere.
6. Configure the mail provider for outgoing mail by entering a Mail transport host and a Mail
from address.
7. To save the mail provider settings, click OK.
8. Click the Save link (found at the top of the administrative console). You will see a window
prompting you to save to the master configuration. Click the Save button on this page to
save the settings to disk.

Chapter 4. Development migration scenarios

49

Configuring the JMS resources

Because this example uses WebSphere 6.0 default messaging, this configuration is
significantly different from the configuration required for WebSphere Application Server
Version 5.

Figure 4-11 Selecting service integration bus

1. Expand Service integration in the left panel of the administration console. Click Buses.

Figure 4-12 Creating new service integration bus

50

WebSphere Application Server V6 Migration Guide

2. Under Buses, click New.

Figure 4-13 Specifying bus properties

Chapter 4. Development migration scenarios

51

3. Enter the name PlantsByWebSphere and click Apply.

Figure 4-14 Specifying new bus members

4. Under Additional Properties for the PlantsByWebSphere bus, click Bus members.
5. On the Bus Members page, click Add.

Figure 4-15 Selecting type of bus member

52

WebSphere Application Server V6 Migration Guide

6. Leave the default values on the Select server or cluster pane and click Next.

Figure 4-16 Confirmation of bus member creation

7. On the confirmation page, click Finish.

8. Click Buses and then PlantsByWebsphere to return to the bus definition.

Figure 4-17 Creating bus destinations

9. Under Additional Properties, click Destinations.

Chapter 4. Development migration scenarios

53

10.There are some destinations already defined. Click New to create a new JMS destination.

Figure 4-18 Creating new bus destination

11.Select Queue for the destination type and click Next.

Figure 4-19 Specifying queue attributes

54

WebSphere Application Server V6 Migration Guide

12.Enter PurchaseOrdersQueue for the Identifier and click Next.

Figure 4-20 Creating a new bus member queue

13.Leave the Bus member set to the member you defined and click Next.

Figure 4-21 Confirming queue creation

14.On the confirmation page, click Finish.

Chapter 4. Development migration scenarios

55

15.Click the Save link (found at the top of the administrative console). You will see a window
prompting you to save to the master configuration. Click the Save button on this page to
save the settings to disk.

Figure 4-22 Selecting default messaging resources

16.Expand Resources in the left panel of the administration console. Expand JMS
Providers and select Default messaging.
17.Ensure that a scope of Node is selected.

Figure 4-23 Selecting JMS queue connection factory

18.Under Connection Factories, click JMS queue connection factory.

56

WebSphere Application Server V6 Migration Guide

19.Click New to define a new queue connection factory.

Figure 4-24 Queue connection factory properties

20.Enter the name PurchaseOrdersQCF and the JNDI name: jms/PurchaseOrdersQCF.

21.Under Bus name, select PlantsByWebSphere.
22.Click OK to create the QueueConnectionFactory.
23.Click Default messaging provider to return to the provider page.

Figure 4-25 Selecting JMS queue

24.Under Destinations, click JMS queue.

Chapter 4. Development migration scenarios

57

25.Click New to create a new JMS queue definition.

Figure 4-26 Specifying JMS queue properties

26.Type PurchaseOrdersQueue for the Name and jms/PurchaseOrdersQueue for the JNDI
name.
27.Select PlantsByWebSphere for the Bus name and click the >> button.
28.Select PurchaseOrdersQueue for the Queue Name.
29.Click OK.
30.Click Default messaging provider to return to the provider page.

Figure 4-27 Selecting JMS activation specification

31.Under Activation Specifications, click JMS Activation Specification.

58

WebSphere Application Server V6 Migration Guide

32.Click New to create a new JMS activation specification.

Figure 4-28 Specifying JMS queue properties

33.Enter PurchaseOrdersActivation for the Name and jms/PurchaseOrdersActivation for

the JNDI name.
34.Make sure that the Destination type is set to Queue, and enter jms/PurchaseOrdersQueue
for the destination JNDI name.
35.For the Bus name, select PlantsByWebSphere.
36.Click OK.
37.Click the Save link (found at the top of the administrative console). You will see a window
prompting you to save to the master configuration. Click the Save button on this page to
save the settings to disk.
38.Click Logout at the top of the page to log out of the WebSphere Administrative Console.
39.Close the Admin Console window

Deploying and testing the applications

1. In the Servers view, right-click WebSphere Application Server V6 and select Restart ->
Start.
2. When the restart is complete, right-click the application server and select Add and
Remove Project.

Chapter 4. Development migration scenarios

59

3. Click Add All to add both applications to the server and click Finish.

Figure 4-29 Publishing to test server

4. Watch the status in the lower right corner of IBM Rational Application Developer for
WebSphere Software. When all tasks complete, the applications are installed and running
in the test environment.
5. Launch a Web Browser and enter the URL: http://localhost:9080/PlantsByWebSphere.

Figure 4-30 Plants by WebSphere application initial Web page

6. Click Fruits & Vegetables. Click Ornamental Gourd. Enter 150 in the Quantity field and
click Add to cart.
7. Click the Checkout Now button at the bottom of the page.

60

WebSphere Application Server V6 Migration Guide

8. At the Login page, click the register for your own account here link.

Figure 4-31 Plants by WebSphere application login registration

Chapter 4. Development migration scenarios

61

9. Provide simulated login information and click Register.

Figure 4-32 Plants by WebSphere application shipping information

10.Select the checkbox next to Check here if the shipping address is the same as the
billing address. Enter a dummy value for the Credit Card Number (such as 123456). and
a Cardholder Name. Click the Continue button.
11.You are presented with a page where you can review your order. Click Submit Order at
the bottom of the page.
12.The order is submitted. In the Console view, you may see an error related to sending
e-mail. This occurs if you did not configure a mail provider. This error can be ignored.
13.A page is displayed confirming the order.
14.Visit the administration page to check for back orders:
http://localhost:9080/PlantsByWebSphere/admin.html

15.Click Manage BackOrders.

62

WebSphere Application Server V6 Migration Guide

16.Under Back Order Items, you should see a shortage of ornamental gourds. To replenish
the supply, enter 100 for the quantity to order and click the checkbox next to the
ornamental gourds. Click the Order Stock button.
17.Scroll down to the Ordered Items. Observe that 100 gourds have been ordered. (If no
gourds have been ordered, make sure that you selected the checkbox in the previous
step.) Click the Refresh button on the top of the page (not the browser refresh button) to
ensure that the items have been ordered.
18.After clicking the Refresh button, the gourds should appear under Received Items. This
indicates that the items have been received from the supplier. To put the items back in
stock, click the checkbox next to the item and click Update Stock.
The ornamental gourds no longer appear in the received items, indicating that they have
been integrated into the stock that people order from.
19.Testing of the application is complete. In the Servers view, right-click WebSphere
Application Server V6.0 and select Stop.

4.1.2 Example: Migrating PlantsByWebSphere using the CVS method

It is important to use a full-featured CVS server for this procedure. CVSNT in particular might
not be robust enough to support the steps described.
This example is an alternative to the example shown in 4.1.1, Example: Migrating Plants By
WebSphere using the Export/Import method on page 40. The result of this procedure should
be the same as for that example.

Adding the application into CVS

1. Start WebSphere Studio Application Developer and open the workspace containing the
Plants by WebSphere applications.
2. Switch to the CVS Repository Exploring perspective.
3. Right-click the CVS Repositories view and select New -> Repository Location.
4. Type in the appropriate Host, Repository path, user and password for your CVS server.
5. Leave the Connection type as pserver and click Finish.
6. Switch back to the J2EE Perspective.
7. In the Project Navigator view, select the Plants project. Right-click and select Team ->
Share Project....
8. In the Share Project dialog, verify that the correct repository is selected and click Finish.
9. In the Synchronize view, right-click the Plants project and select Commit.
10.When prompted to add the resources, click Yes.
11.Type in a release comment and click OK.
12.Repeat the process to check each of the projects into CVS.
13.In the Project Navigator view, select all the projects.
14.Click File -> Export. Select Team Project Set and click Next.
15.Type the File Name C:\PlantsTeamSet and click Finish.
16.Close WebSphere Studio Application Developer.

Chapter 4. Development migration scenarios

63

Importing the projects into IBM Rational Application Developer for

WebSphere Software
1. Launch IBM Rational Application Developer for WebSphere Software on a new
workspace.
2. Close the Welcome view to access the workbench
Before importing the projects, CVS must be configured to not prune empty directories. In
order to configure this, the CVS capability must be enabled.
3. Click Window -> Preferences.

Figure 4-33 Enabling CVS support

4. Expand Workbench and click Capabilities.

5. Under Capabilities, expand Team and check CVS Support.
6. Click OK.

64

WebSphere Application Server V6 Migration Guide

7. Click Window -> Preferences.

Figure 4-34 CVS preferences

8. Expand Team and click CVS.

9. Clear the check box next to Prune empty directories.
10.Click OK.
11.Click File -> Import. Select Team Project Set and click Next.
12.Type the File name C:\PlantsTeamSet.psf and click Finish.
13.Watch the status in the lower right corner of the Workbench. Wait until all tasks are
complete.

Fixing classpath problems

There is a problem with the classpath of one project that need to be fixed before all projects
can be built.
1. In the Project Explorer, expand Dynamic Web projects and select the PlantsGallery
project.
2. Right-click the project and select Properties.
3. Click Java Build Path and select the Libraries tab.
4. Select WAS_PLUGINDIR/lib/websphere.jar and click Remove.
5. Click OK.

Chapter 4. Development migration scenarios

65

Removing WebSphere Studio Application Developer Version 5.1

compatibility
This step is optional. As the projects were imported, new files were generated to allow the
projects to be updated either in WebSphere Studio Application Developer or IBM Rational
Application Developer for WebSphere Software. This allows J2EE 1.3 projects to be modified
in either environment. If the projects are going to be migrated to J2EE 1.4, or if there is no
need to maintain compatibility with WebSphere Studio Application Developer, the
compatibility can be removed.

Figure 4-35 Removing workspace backward compatibility

1. In the Project Explorer, expand Enterprise Applications.

66

WebSphere Application Server V6 Migration Guide

2. Right-click the Plants application and select Remove Compatibility.

Figure 4-36 Confirming removing compatibility

3. When prompted to continue, click Yes.

4. Right-click the PlantsSupplier application and select Remove Compatibility.
5. When prompted to continue, click Yes.
Migration and testing can proceed as with the previous example.

Chapter 4. Development migration scenarios

67

68

WebSphere Application Server V6 Migration Guide

Part 2

Part

For system
administrators
The chapters in this part are for system administrators who manage application server
systems on the Windows and UNIX architectures.

Copyright IBM Corp. 2005. All rights reserved.

69

70

WebSphere Application Server V6 Migration Guide

Chapter 5.

Product overview
This chapter provides a broad overview of WebSphere Application Server Version 6.

Copyright IBM Corp. 2005. All rights reserved.

71

5.1 The new product: Version 6

The WebSphere software platform for e-business is based on a foundation that is formed
from Web application serving and integration. IBM WebSphere Application Server Version 6
software provides the core software to deploy, integrate and manage e-business applications.
WebSphere Application Server software supports custom-built applications, based on
integrated WebSphere software platform products, or on other third-party products. Such
applications can range from dynamic Web presentations to sophisticated transaction
processing systems.
WebSphere Application Server Express, WebSphere Application Server, and WebSphere
Application Server Network Deployment are incrementally related. As you scale up your
e-business demand, you can also scale up your e-business capability by moving from one
product to the next.
The Express product is the entry point. With the base Application Server product, you can
host applications on more machines than Express. The Network Deployment product
includes all of the Application Server functionality of the other two products. However, you
can manage multiple machines and processes from a centralized Web application, which is
the administrative console of the deployment manager.

5.1.1 Product offerings for V6

IBM WebSphere Application Server products provide a next-generation Application Server on
an industry-standard foundation. Each product addresses a distinct set of scenarios and
needs. WebSphere Application Server Version 6 includes the following product offerings:
WebSphere Application Server Express
WebSphere Application Server
WebSphere Application Server Network Deployment

WebSphere Application Server Express

This offering addresses the basic programming and runtime needs of desktop developers and
single-server production scenarios. The runtime environment addresses standards-based
programming for Web and component-based programming, as well as Web services. The
administration model for this offering is a single-server environment without clustering, and
without centralized administration of multiple server instances.
The basic license for the Express product offering includes installation on two machines. The
package also includes a single-use license for the Rational Web Developer tool, which is a
fully integrated development environment (IDE).
Installing the Express product offering on the same machine as the Rational Web Developer
is not necessary. The IDE contains an exact replica of the V6 Application Server as a test
environment.

WebSphere Application Server

This offering is similar to the Express product but does not have the two-machine license
limitation. It addresses the basic programming and runtime needs of desktop developers and
single-server production scenarios. The runtime environment addresses standards-based
programming for Web and component-based programming, as well as Web services.
The administration model is a single-server environment without clustering, and without
centralized administration of multiple server instances. The development environment

72

WebSphere Application Server V6 Migration Guide

offering is an unlimited license of the Application Server Toolkit and a trial version of the IBM
Rational Application Developer for WebSphere Software.
See this article for diagrams of topologies that support the WebSphere Application Server
environment: Planning to install WebSphere Application Server, found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.base.d
oc/info/aes/ae/tins_scenario2.html

WebSphere Application Server Network Deployment

This offering addresses Application Servers that run in multiple-server production scenarios.
The WebSphere Application Server Network Deployment product offering can create:
Application Server profiles
An Application Server profile includes default applications and a default Application
Server. The Application Server in the Network Deployment product can run as a managed
node or as a stand-alone Application Server.
The stand-alone Application Server is the same one found in the Express product and in
the base WebSphere Application Server product with one important exception: you can
add Network Deployment stand-alone Application Server nodes to a cell under the
centralized management of the deployment manager.
Deployment manager profiles
The deployment manager profile includes the dmgr process. The deployment manager
provides centralized administration of multiple Application Server nodes and custom
nodes as a single cell. The deployment manager provides administration for basic
clustering and caching support, including failover support and workload balancing.
Custom profiles
A custom profile is an empty node that you must federate. Use the deployment manager
to customize the node by creating servers and clusters. The node does not include a
default Application Server or default applications.
See this article for examples of common topologies that you can create with the WebSphere
Application Server Network Deployment product: Planning to install Network Deployment,
found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.nd.doc
/info/ae/ae/tins_scenario3.html

5.2 New features for V6

IBM WebSphere Application Server products provide the following new and enhanced
features and tools:
New installation and operating model
New programming model extensions
New and improved developer tools bundled with V6 packages

5.2.1 New installation and operating model

V6 implements a new installation method compared to previous versions. Installation is
divided into two major steps:

Chapter 5. Product overview

73

1. Installation of read-only executable files.

2. Creation of one or more sets of writable configuration files, each of which corresponds to a
server instance.
The product executable files remain unchanged after installation until you install
maintenance. All server processes that share the binaries use the updated level of the
system files after installing the service.
See 7.2, Installation on page 96 for more details about how this new installation method is
organized.

5.2.2 New programming model extensions

Many programming model extensions that were formerly part of the Enterprise (V5.0.x)
product or the WebSphere Business Integration Server Foundation Version 5.1 product are
now integrated into WebSphere Application Server Version 6 and WebSphere Application
Server Network Deployment Version 6.
See 3.2.5, Programming Model Extensions on page 36 for more details about which
extensions are packaged in which products.
See these articles for more information about programming model extensions:
Migrating WebSphere programming model extensions (PMEs)
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.exp
ress.doc/info/exp/ae/rins_migratepme.html

Learn about WebSphere programming extensions

http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.exp
ress.doc/info/exp/ae/welc6tech_appsvcs.html

5.2.3 Development and assembly tools

These development and assembly tools are packaged in various combinations with the
WebSphere Application Server packages. See 5.3, Version 6 package descriptions on
page 74 for information about how these tools are packaged with the runtime products. These
tools are discussed in more depth in Part 1, For application developers on page 1.
IBM Rational Application Developer for WebSphere Software is intended for development
of all types of J2EE applications.
IBM Rational Web Developer for WebSphere Software is a simpler tool intended for
development of Web applications that do not incorporate J2EE EJB functionality.
WebSphere Application Server Toolkit is a limited purpose assembly tool intended for
those who must repackage and redeploy existing applications. It is not a full function
development environment.

5.3 Version 6 package descriptions

The following sections describe installable components within each product package:
WebSphere Application Server Express
WebSphere Application Server
WebSphere Application Server Network Deployment

74

WebSphere Application Server V6 Migration Guide

5.3.1 WebSphere Application Server Express

WebSphere Application Server Express contains these subproducts:
Application Server Express V6.0
These subcomponents can be installed:

Application server
IBM HTTP Server Version 6
Web server plug-ins
Application client environment

IBM Rational Web Developer for WebSphere Software

Application Server Toolkit (ASTK)
ASTK has no restrictions on its license. You may make unlimited copies.
DB2 UDB Database Express Edition V8.2
DB2 UDB Database Express Edition has a limited development-only license and is not to
be used for production purposes.
Data Direct JDBC Drivers
These are Java based drivers and supported on any of the Application Server platforms.
Business Solutions package
The Business Solutions package installs these integrated applications:
IBM Telephone Directory
IBM Welcome Page
Table 5-1 shows which subcomponents are available and which operating system platform is
supported for each. Note that ASTK is only supported in Linux and Windows operating
systems for Version 6. In previous versions, ASTK was supported on all the platforms that
supported the application server.
For more exact information about which operating system version and fix level is needed, see
this document:
http://www.ibm.com/software/webservers/appserv/doc/v60/prereqs/prereq60.html
Table 5-1 Supported platforms for WebSphere Application Server Express

Linux i p

Linux IA32

Solaris

Windows

application server

IBM HTTP Server

Web server plug-ins

application client environment

Linux z

HP-UX

Operating System Platforms

AIX

Product and subcomponents

Application Server Express V6.0

Rational Web Developer for WebSphere Software

Application Server Toolkit

Chapter 5. Product overview

75

DB2 UDB Database Express Edition V8.2

Windows

Solaris

Linux z

Linux IA32

Linux i p

HP-UX

Operating System Platforms

AIX

Product and subcomponents

Data Direct JDBC Drivers

Business Solutions Applications

Legend Linux i p = Linux for iSeries and pSeries

Linux z= Linux for zSeries
Linux IA32= Linux for Intel 32 bit architecture

5.3.2 WebSphere Application Server

The WebSphere Application Server contains these subproducts:
Application Server V6.0
These subcomponents can be installed:

Application Server
IBM HTTP Server V6.0
Web Server Plug-ins
Application client environment

Data Direct JDBC Drivers

These are Java based drivers and supported on any of the Application Server platforms.
Application Server Toolkit (ASTK)
ASTK has no restrictions on its license. You may make unlimited copies.
DB2 UDB Database Express Edition V8.2
DB2 UDB Database Express Edition has a limited development-only license and is not to
be used for production purposes.
Rational Application Developer Trial
This is a limited license for the purposes of evaluating the software. The license expires 60
days after installation.
Table 5-2 on page 77 shows which subcomponents are available and which operating system
platform is supported for each. Note that WebSphere Application Server adds an additional
platform for Linux on zSeries that is not supported for WebSphere Application Server
Express.
For more exact information about which operating system version and fix level is needed, see
this document:
http://www.ibm.com/software/webservers/appserv/doc/v60/prereqs/prereq60.html

76

WebSphere Application Server V6 Migration Guide

Table 5-2 Supported Platforms for WebSphere Application Server

HP-UX

Linux i p

Linux Intel

Linux z

Solaris

Windows

Operating System Platforms

AIX

Product and subcomponents

application server

IBM HTTP Server

Web server plug-ins

application client environment

Application Server V 6.0

Rational Application Developer for WebSphere

Software Trial version

Application Server Toolkit

DB2 UDB Database Express Edition V8.2

Data Direct JDBC Drivers

Legend Linux i p = Linux for iSeries and pSeries

Linux z= Linux for zSeries
Linux IA32= Linux for Intel 32 bit architecture

5.3.3 IBM WebSphere Application Server Network Deployment

These subcomponents can be installed:

Application server
IBM HTTP Server V6.0
Web server plug-ins
Application client environment

Data Direct JDBC Drivers

These are Java based drivers and supported on any of the Application Server platforms.
Application Server Toolkit (ASTK)
ASTK has no restrictions on its license. You may make unlimited copies.
Edge Components
Edge Components, formerly called WebSphere Edge Server, provide enhancements to
load balancing and request caching above that offered by the application server.
DB2 Universal Database for WebSphere Application Server V8.2
IBM Tivoli Directory Server 5.2
IBM Tivoli Access Manager 5.1
IBM Rational Application Developer for WebSphere Software Trial
This is a limited license for the purposes of evaluating the software. The license expires 60
days after installation.

Chapter 5. Product overview

77

Table 5-3 shows which subcomponents are available and which operating system platform is
supported for each. For more exact information about which operating system version and fix
level is needed, see this document:
http://www.ibm.com/software/webservers/appserv/doc/v60/prereqs/prereq60.html
Table 5-3 Supported Platforms for WebSphere Application Server Network Deployment

HP-UX

Linux i p

Linux Intel

Linux z

Solaris

Windows

Operating System Platforms

AIX

Product and subcomponents

application server

IBM HTTP Server

Web server plug-ins

application client environment

Application Server Network Deployment V 6.0

Rational Application Developer for WebSphere

Software Trial version

Application Server Toolkit

DB2 Universal Database for WebSphere

Application Server V8.2

Data Direct JDBC Drivers

Edge Components

IBM Tivoli Access Manager 5.1

IBM Tivoli Directory Server 5.2

Legend Linux i p = Linux for iSeries and pSeries

Linux z= Linux for zSeries
Linux IA32= Linux for Intel 32 bit architecture

78

WebSphere Application Server V6 Migration Guide

Chapter 6.

Runtime migration strategy

This chapter discusses the overall strategy of migration.

Copyright IBM Corp. 2005. All rights reserved.

79

6.1 Environments
The ideal corporate WebSphere environment is shown in Figure 6-1. This environment, which
is described with greater detail in The Ideal WebSphere Development Environment1,
represents (as established in the first sentence) the ideal; it is very likely that your
environment contains many similar elements.

Development Environment

Development Integration
Runtime Environment

Development
Development
Development
(Rational Application (Rational Application (Rational Application
Developer)
Developer)
Developer)

HTTP/WAS

Performance Test
Environment

HTTP/WAS
HTTP

System Test Environment

SCM

Integration Workstation
(Rational
Application Developer)

WAS

WAS

WAS

HTTP

WAS

Production Environment

Pre-Production Environment

Router

WAS

HTTP

HTTP

WAS

WAS

WAS

Router

WAS

WAS

HTTP

HTTP

WAS

WAS

WAS

Figure 6-1 The ideal WebSphere environment

This figure represents an ideal environment that includes all of the necessary stages for a
first-class rigorous environment. In this environment, each sub-environment is as complete as
it needs to be to serve the intended task. These environments all need to be migrated; it is
important that we understand why each of these sub-environments exists and the constraints
placed upon them so that we know what needs to be done during the migration.
Pragmatically speaking, very few organizations achieve the ideal described here. It is more
realistic to expect that parts of the ideal are represented in your corporate environment.
Figure 6-2 on page 81 shows a scale of the risk associated with each of the environments.

80

http://www-106.ibm.com/developerworks/websphere/techjournal/0312_beaton/beaton.html

WebSphere Application Server V6 Migration Guide

Development
Integration
Runtime

Development
Environment

System Test

Performance Test

Pre-production

Production

Increased Risk

Figure 6-2 Increasing scale of risk

As we move from left to right:

The risk to the businessshould the environment suffer extended downtimeincreases

The length of maintenance windows decreases
The amount of acceptable downtime decreases
The complexity of the environment increases

Ideally, additional hardware is available for operations staff to use to familiarize themselves
with the new version of WebSphere Application Server, but reality is that hardware is
expensive and it may well be the case that additional hardware is not available. In this case,
operations staff can gain familiarity with installation of WebSphere Application Server as they
move left to right through these environments starting, of course, with the development
integration runtime.
There are at least three different types of runtime migration, each with increasing adversity to
risk.
The development test and system test environments
Performance testing and pre-production environments
Production runtime environment.
Each of these environments is discussed below in detail.

6.1.1 Development environment

The development environment is where developers live and work every day; this is where
developers work hard and need to be productive. Thus, they need the best tools and the
fewest barriers to progress. This environment is composed of a number of development
workstations (one for each developer), a source code management (SCM) tool, and an
integration target system.
In general, the machines in a development environment do not run WebSphere Application
Server outside of the WebSphere Test Environment embedded within IBM Rational
Application Developer for WebSphere Software. Strictly speaking, from a runtime migration
point-of-view, there is no inherent risk in migrating this environment.
More pragmatically, the cost of this environment not working is the cost of stopped
development. A quick and orderly migration of this environment is critical and may require
updates to related components, including the SCM, database drivers, databases, connectors,
etc. Careful planning is key when migrating this (and every other) environment.
Timing of the migration of related resources introduces challenges, especially if it is difficult or
impossible to run different versions of those related resources. You may find yourself in a
situation where some developers have migrated their own personal workstations, but some
have not. In that case, you may have to run two separate versions of a database for a period
of time. This may require additional hardware in the midterm.

Chapter 6. Runtime migration strategy

81

6.1.2 Development integration runtime

The development integration runtime environment is used by developers to test their
application on hardware and software that resembles the target production environment.
Testing in this environment is concerned with uncovering issues related to subtle differences
between the development and production systems as well as testing the deployment
procedures. This may include such things as the use of various operating system services,
WebSphere Application Server security, backend systems and others.
Developers use this environment to perform integration tests among all system components.
This environment is also used to test installation and operational procedures which are often
operating system specific.The development integration runtime environment is configured to
mirror the production environment at the smallest possible scale and complexity. In general,
this environment does not include network devices such as load-balancers, routers, or
firewalls.
Systematic testing on this environment does not typically occur on a daily basis, but does
occur regularly, perhaps bi-weekly as significant change is introduced into the application.
This environment is controlled by the development team; it is used informally by developers
and updated as often as necessary by developers while performing their tests. Periodically,
this environment is refreshed using a formal build, deploy, and test procedure thereby
removing any inconsistency and testing the full build and install procedures. In general, this
environment does not include any development tools. As such, testing depends on the use of
test scripts and tracing to determine correctness and identify problems.
This environment has perhaps the lowest amount of risk of all the environments presented
here. If this environment is not available, developers cannot perform their integration tests on
production-like hardware and software. This environment tends to be used sporadically by
the development team and so it should be easy to schedule a few days of downtime for
migration. It is also expected that this environment is rebuilt periodically anyway, so
developers will be accustomed to the environment being unavailable.
This environment provides an opportunity for administrators to cut their teeth on WebSphere
Application Server Version 6.0. Since this environment tends to be rebuilt periodically, a
straight installation of the application server (rather than using the migration tools) is
recommended. This gives the administrators an environment to learn more about the new
version and experiment with configuration options. As part of the exercise, administrators
should work out a plan (possibly involving silent install scripts) to quickly and easily reinstall
and reconfigure the application server.

6.1.3 System test environment

The system test environment is a carefully controlled formal test environment. Development
teams run their applications on this environment on a relatively infrequent basis perhaps
every six to eight weeks. A system test environment mirrors the production environment more
closely than does a development integration environment, but it still does so at the smallest
possible scale.
A key aspect of the system test environment is formality. The purpose of this environment is
to ensure that the application truly deploys and runs as required in production. Thus, the
system test team is responsible for testing all aspects of the application, including both
functional and non-functional requirements. This is not a place to experiment. Development
experiments are executed informally in the development integration runtime environment.
A system test environment may serve multiple masters. In addition to being used formally by
testers, other groups may use it as well depending on what is appropriate to the environment.

82

WebSphere Application Server V6 Migration Guide

For example, the administration staff may use this environment to test new patches and
configuration changes before they are rolled into the pre-production and production
environments.
Extended downtime in this environment can have an impact on delivery schedules. This
environment is a key piece of the testing infrastructure and downtime means that important
testing done in this environment cannot be undertaken. Still, risk is relatively low and with
planning it should be possible to schedule several days to migrate this environment.
This is probably the first environment that administrators can use to gain experience with the
migration tools and start to develop a plan for migrating the downstream environments. It may
make sense to use one of the options outlined in 6.3, Migration options on page 89 to
migrate this environment.
Your administrators should be prepared to start over if problems arise. It is important that
issues be exposed and remediated during this migration. At the end of the day, you need to
have a functioning system test environment and a good start on a formal migration plan. To
this end, it may be necessary to reinstall the old environment to run through the migration
scenario a second (or third) time to ensure that key concepts are understood and that
outstanding issues are resolved. This is particularly true if your overall environment does not
match the ideal and does not include a dedicated performance test environment.

6.1.4 Performance test environment

Performance and load testing is performed to find load related problems in applications. This
testing requires highly specialized skills and equipment to perform optimally. Hence, this is a
dedicated environment and team.
Like the system test environment, the performance test environment is a carefully controlled
formal test environment. Development teams run their applications on this environment on an
even less frequent basis. A performance test environment mirrors the production environment
in complexity, but it does so at the smallest possible scale.
Ideally this environment is owned and operated by a dedicated performance testing group
whose members have specialized load testing skills. Each development team schedules time
with this group. Typically, an application is load tested less frequently than it is run on the
system test environment. As with a system test environment, one application is tested at a
time.
Migration of the performance test environment carries similar risk to that of the system test
environment. When this environment is unavailable, performance testing cannot be
undertaken which may impact delivery schedules. Much like for a system test environment,
however, it should be possible to schedule a period of extended downtime to migrate this
environment.
Your experience migrating the system test environment should have an impact on the
migration of this environment. Here, you take what worked with the system test environment
and apply it; you then modify what did not work. By this point, your migration process should
be getting more formal and your administration staff should be quite comfortable with the
migration process and the use of the migration tools (if applicable). The lessons learned while
migrating this and the system test environments should translate into a formal (and
documented) plan for migrating the pre-production environment.
You may consider running load testing scripts while you migrate this environment to confirm
that the system continues to be responsive to user requests during the migration process.

Chapter 6. Runtime migration strategy

83

6.1.5 Pre-production environment

The purpose of pre-production is to mimic production as much as possible (with exactly being
the norm). This is the final chance to ensure that things really work in production.
This environment serves three purposes:
1. It gives the operations team a final place to familiarize themselves with the application and
its procedures.
2. It provides the opportunity to test unrelated applications running together. This is crucial
with shared deployment environments. Prior to this point, the applications have been
tested and built independently.
3. It provides the operations team with a chance to test their operational procedures (backup,
failover, problem resolution, etc.).
The pre-production environment might also be used for user acceptance testing. In any case,
testing on a pre-production staging environment generally coincides with an applications
release schedule. Each external release of the application is tested on the pre-production
system before it is finally moved into production. This environment is generally used to prove
that the application works well with other applications.
For the purposes of migration, the pre-production environment should be treated as if it were
the production environment. This is not an environment for experimenting; it is an
environment for testing your formal migration plan. By the time you get to migrating this
environment, your administrators should be very familiar with WebSphere Application Server
V6.0 and should be confident in their plan for migration. Some tweaking of the plan is
inevitable, but it is important to at least try to start this migration with as many answered
questions as possible.
If possible, the pre-production environment should be migrated while under some test load to
confirm that the application continues to respond throughout the process.

6.1.6 Production environment

Production is where you really run your applications. The key point is that if you have carefully
followed procedures up to this point, the actual roll into production will be uneventful and
predictable, since you have tested everything already.
The risks inherent in this environment being out of service are obvious: this is the
environment that faces your customers and without this environment in service, it cannot
make you money.
Many organizations have service-level agreements (SLA) in place that dictate response
times, throughput, maintenance windows, and acceptable amounts of downtime.
Organizations that do not put formal SLAs in place tend to have informal ones that dictate (at
least) how much downtime is permitted. Most organizations permit a very small amount of
downtime, generally measured in minutes out of the year (these same organizations can tell
you how much money it costs when their systems are down for a second).
Several minutes of acceptable downtime combined with short maintenance windows can
typically be leveraged as part of runtime migration, but doing so requires careful planning,
testing and an effective backout strategy (what to do when something goes wrong). Honoring
SLAs can be a real challenge during a migration.

84

WebSphere Application Server V6 Migration Guide

6.2 Interoperability
Interoperability is part of almost every migration, at least for some short period of time as the
runtime environment is migrated. In some cases, there may be a need to retain some number
of servers running the older version. Use of features that are not supported by V6 might be
one possible reason (Continued use VisualAge for Javas Enterprise Access Builders or the
Common Connector Framework are examples). For organizations with large numbers of
applications, it may not be practical to prepare, test, and certify all of their applications for
V6.0 at the same time and so some extended period of interoperability may be required as
those applications are pushed through.
Even if all the applications can be moved forward to WebSphere Application Server V6.0 at
the same time, there is likely to be some short period of time when interoperability is required.
The bottom line is that some amount of interoperability is inevitable.

6.2.1 Mixed version cell

WebSphere Application Server Version 6 supports a mix of Version 5.x and 6.0 nodes in a
cell. There are, however, limitations to the support. With a Version 6.0 deployment manager,
you can:
Start and stop V5 server instances
Add and remove applications to V5 server instances
With a Version 6.0 deployment manager, you cannot:

Add V5.x nodes

Create new V5.x server instances
Create new V5.x cluster members
Add V5.x servers to existing clusters

Migrating a V5.x deployment manager to V6.0 is quite easy to do and works well. The
interoperability works well with the restrictions noted above. Migrating the existing
deployment manager can save significant time and money. Since migration conserves the
current cell configuration, you do not need to spend time rebuilding it (though you may want
to spend some time reviewing the settings to confirm that everything migrated as expected).
You save money because you do not need to acquire additional hardware to make the
migration work (see 6.3, Migration options on page 89).
Whether or not a mixed version cell is appropriate for your organization depends on a number
of factors. Perhaps the most important factor is the amount of time that the complete
migration takes. In every migration, there is some period of interoperability as a new
production runtime is rolled out. If all the applications have been migrated, tested, and
declared ready for Version 6.0, then the period of interoperability is relatively short (hours or
days). If only some applications are declared ready for Version 6.0, then your complete
migration to Version 6.0 may take weeks or months.
Why does the period of time required to migrate matter? For some organizations, the ability to
reconstruct an environment from scratch (perhaps in the event of hardware or catastrophic
failure) is important. It is time consuming to reconstruct a mixed version configuration from
scratch. A mixed version cell can be reconstructed using a configuration backup. Without a
backup, a mixed version cell must be reconstructed by first rebuilding the V5.x nodes and
then repeating the migration. This can be very time consuming.
Furthermore, it is difficult, or sometimes impossible, to make significant modifications to V5.x
nodes in a V6.0 cell. Specifically, since new V5.x server instances cannot be added, it is very
difficult to reprovision V5.x assets. You could not, for example, add additional V5.x nodes to
Chapter 6. Runtime migration strategy

85

handle an increase in traffic should the need arise. If your V5.x applications cannot be
migrated immediately, it may be better to retain your V5.x cell until those applications can be
migrated.
It is important to note that J2EE 1.3 applications deployed on WebSphere Application Server
V5.x should require little or no modification to run on V6.0 and, in general, testing should
amount to little more than running existing test scripts with the application deployed on the
new environment. While this is generally true, some organizations may choose to do more
extensive testsincluding, for example, performance testingprior to production
deployment. Such testing can take a considerable amount of time, especially when multiple
applications are involved.

6.2.2 HTTP servers

As part of your application server migration, it may be necessary to migrate your HTTP server
as well. Table 6-1 shows a support matrix for the HTTP servers that lists all the HTTP servers
supported by WebSphere Application Server V6.0 at the time of this writing2. It also shows
whether or not each of those HTTP server versions is supported by previous versions of
WebSphere Application Server.
Table 6-1 Support matrix for HTTP servers
6.0

5.1.1

5.1

5.02

4.07AE

Apache 2.0.49

yes

no

no

no

no

Covalent 1.4

no

yes

yes

no

no

Covalent 2.3.2

no

yes

yes

yes

yes

Covalent 2.4

no

yes

yes

no

no

IBM HTTP Server

2.0.47.1

yes

yes

yes

no

no

IBM HTTP Server 6.0

yes

no

no

no

no

Internet Information
System 5.0

yes

yes

yes

yes

yes

Internet Information
System 6.0

yes

yes

yes

yes

no

SunOne 6.0 SP7

yes

yes

no

no

no

SunOne 6.1 SP1

yes

yes

no

no

no

During a rolling migration, there is some period of interoperability where you have both the
existing and new versions of WebSphere Application Server running concurrently. During that
period of interoperability (depending on what version of the HTTP server you are currently
using), you may have to take care that the tiers are configured correctly.
If your current topology organizes your HTTP and application servers into silos (that is, each
application server node has a dedicated HTTP server) as shown in Figure 6-3 on page 87,
then the HTTP server version differences are irrelevant. You can update the HTTP server as
the application server is upgraded.

2
For up to date information, please see
http://www-306.ibm.com/software/webservers/appserv/doc/latest/prereq.html

86

WebSphere Application Server V6 Migration Guide

Load Balancer

HTTP Server X

HTTP Server X

HTTP Server X

V5.x plugin

V5.x plugin

V5.x plugin

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 5.x

Figure 6-3 A topology organized in silos

Since the HTTP server is effectively dedicated to a single instance of WebSphere Application
Server, it can easily co-exist with mixed HTTP server versions as shown in Figure 6-4.

Load Balancer

HTTP Server X

HTTP Server X

HTTP Server Y

V5.x plugin

V5.x plugin

V6.0 plugin

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 6.0

Figure 6-4 With a silo topology, mixed HTTP server versions can easily work together

This form of interoperability is relatively easy to maintain through a rolling migration (or even
for extended periods if required).
For more complex topologies, compatibility can have a significant impact on the migration
path. Figure 6-5 on page 88 shows a more complex configuration that employs workload
management from the HTTP servers to a collection of application server nodes.

Chapter 6. Runtime migration strategy

87

.
Load Balancer

HTTP Server X

HTTP Server X

HTTP Server X

V5.x plugin

V5.x plugin

V5.x plugin

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 5.x

Figure 6-5 A more complex topology that uses workload management

Version differences between HTTP servers impact the strategy for moving forward. In this
event, different versions of the HTTP servers need to be fitted into silos temporarily during the
rolling migration. Figure 6-6 shows an example where the first application server node is
upgraded to V6.0 along with one of the HTTP servers.

Load Balancer

HTTP Server X

HTTP Server X

HTTP Server Y

V5.x plugin

V5.x plugin

V6.0 plugin

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 6.0

Figure 6-6 Upgrading first server node

As the migration progresses, the new V6 silo is extended as shown in Figure 6-7.
Load Balancer

HTTP Server X

HTTP Server Y

HTTP Server Y

V5.x plugin

V6.0 plugin

V6.0 plugin

IBM WebSphere
Application
Server 5.x

IBM WebSphere
Application
Server 6.0

IBM WebSphere
Application
Server 6.0

Figure 6-7 Upgrading second server node

88

WebSphere Application Server V6 Migration Guide

By the end of the migration, all HTTP servers and application server nodes are migrated and
the original topology is again in place.
The previous two examples represent horizontal migrations. This means that the migration
must span tiers. If a common version of the HTTP server is in place at the start of the
migration, then the migration can be processed vertically. In this case, the entire HTTP server
tier might be completely migrated before a single application server node is migrated.

6.3 Migration options

There are three ways to migrate an existing WebSphere Application Server cell to Version
6.0. The path you choose depends on a number of factors, including:

Expected time to complete the migration

Amount of acceptable risk
Availability of hardware/resources
Trust in automated tools

The three runtime migration options are presented below.

6.3.1 Fully automated migration

The fully automated migration uses the WASPreUpgrade and WASPostUpgrade tools to perform
the migration. Strictly speaking, the migration is not fully automatic. It is more accurate to say
that the configuration of the migrated elements is automated. We refer to this approach as
fully automated because we use the migration tools on every node in the cell.
The migration tools are used as part of a four-step migration process:
1. Run WASPreUpgrade on the existing WebSphere Application Server configuration.
2. Uninstall the existing version of WebSphere Application Server.
3. Install the new version of WebSphere Application Server.
4. Run WASPostUpgrade on the new version.
In the second step, it is recommended that rather than uninstalling the existing version, it be
made dormant. By keeping the existing software installed on the machine, it will be much
easier to back out of the migration should unexpected problems arise.
See 8.4, V5 Network Deployment on page 140 for more details about the fully automated
approach to migration.
The fully automated migration includes the following steps:
1. Migrate the existing Version 5.x deployment manager to Version 6.0 using the migration
tools.
2. Migrate the HTTP servers and HTTP server plug-ins on all Web tier nodes.
3. Individually migrate the application server nodes using the migration tools.
If you must upgrade the HTTP server as part of your migration, the final two steps may need
to be interleaved with groups of HTTP servers and application servers being migrated in
steps.
This method has the benefit of not requiring any additional hardware to work. The existing
machine running the existing deployment manager can be upgraded while the application
server nodes continue to receive and process requests. The Version 5.x application server
Chapter 6. Runtime migration strategy

89

nodes continue to work even as the deployment manager is out of service for the upgrade.
Additionally, this method requires the least amount of time and manual intervention. The
WASPreUpgrade and WASPostUpgrade tools effectively move the existing configuration into
WebSphere Application Server Version 6.0.

6.3.2 Partially automated migration

Like the fully automated migration, this method uses the migration tools, but only to migrate
the deployment manager. You might use this method if you are not 100% confident in the
abilities of the migration tools and you need a mixed version cell (automated migration of the
deployment manager is the only way to include Version 5.x nodes in a Version 6.0 cell).
The steps for a partially automated migration include:
1. Migrate DM using Migration Wizard.
2. Migrate HTTP plug-in on all HTTP server nodes.
3. Migrate nodes manually.
Again, you may have to interleave the migration of the HTTP servers and application servers
if you must upgrade the HTTP server as part of this migration.
When migrating nodes, first remove them from the cell, install the new version of WebSphere
Application Server and then add them back into the cell. In our experiments with the early
version, the remove node functionality did not work when attempting to remove a Version
5.x node from a Version 6.0 cell. To remove the node, we had to do a force remove from the
console.

6.3.3 Manual migration

In a manual migration, a new Version 6.0 cell is created to first augment and then replace the
existing Version 5.x cell. You might use this method if you need to keep Version 5.x running
for an extended period (that is, you require an extended period of interoperability) and you
have adequate hardware to support a second deployment manager. As noted earlier, an
extended period of interoperability may be necessary if you have a large number of
applications and some, but not all, of them are ready for deployment on WebSphere
Application Server Version 6.0.
In this method, each node runs either Version 5.x or 6.0 and is a member of exactly one cell.
Since the migration process itself is completely manual, it is impossible to have a mixed
version cell (that is, it is not possible to add a Version 5.x node to a Version 6.0 cell). It may be
possible to install and run both versions of the application server on a single physical
machine; that is limited by available resources.
The steps for this method include:
1. Create a new (parallel) WebSphere Application Server Version 6.0 deployment manager.
2. Migrate the HTTP server plug-in on selected HTTP server nodes. Only migrate those
HTTP servers that will be handling traffic destined to Version 6.0.
3. Remove the node from the Version 5.x deployment manager, upgrade the node to Version
6.0, and add it to the V6 deployment manager.
Depending on available resources, it may be possible to install the deployment manager for
both versions on the same machine. Alternatively, if there is sufficient capacity in the existing
infrastructure, one of the existing nodes might be temporarily made the deployment manager

90

WebSphere Application Server V6 Migration Guide

for the new cell (this assumes that you have an homogeneous collection of machines running
your cell).

Chapter 6. Runtime migration strategy

91

92

WebSphere Application Server V6 Migration Guide

Chapter 7.

Runtime administration overview

This chapter discusses the most important aspects of how WebSphere Application Server
Version 6 is administered.

Copyright IBM Corp. 2005. All rights reserved.

93

7.1 Significant concept changes from previous versions

You should already be somewhat familiar with WebSphere Application Server and
specifically, how to administer V4 or V5. Given that, the quickest way to be productive on V6
is to understand the significant administration task changes.

7.1.1 Significant changes from V4

If you are familiar with administering V4, you should be aware of these changes.

XML file based administrative repository

WebSphere Application Server Version 4 Advanced Edition manages application servers with
a single administration server. The administration server accesses server configuration data
that is housed in a relational database. WebSphere Application Server Version 6 performs the
same server management function via an administration server that is called the deployment
manager. The deployment manager accesses configuration data that is implemented as files
in XML format. See 7.3, Administrative console on page 109 and 7.4, How to perform basic
functions on page 111 for details about how the deployment manager is administered.
The concept of a deployment manager was introduced in the WebSphere Application Server
Network Deployment Version 5 product. V6 continues this same concept, and therefore
readers familiar with V5 operation can apply this same knowledge to administering V6.

HTTP administrative console

The administrative console that is used to interact with the administration server for
WebSphere Application Server Version 4 Advanced Edition is a Java application client. Both
WebSphere Application Server Version 5 and Version 6 products use an HTTP-based
administrative console that is accessed via a Web browser. See 7.3, Administrative console
on page 109 for more details about how to access the administrative console.

Installation
WebSphere Application Server Version 4 installs the application server, the Web server, and
the Web server plug-ins with a single installer that installs all three in sequence. WebSphere
Application Server Version 6 uses independent installers to install these three components.
See 7.2, Installation on page 96 for details about how to perform installations.

7.1.2 Significant changes from V5

If you are familiar with administering V5, you should be aware of these changes.

Asynchronous messaging architecture

WebSphere Application Server Version 5 implements asynchronous messaging with a native
code implementation that is derived from the WebSphere MQ product line. This native
implementation is loosely integrated with the Java environment that comprises the application
server execution platform.
WebSphere Application Server Version 6 implements asynchronous messaging entirely in
Java. The integration with the application server Java environment is seamless.
Consequently the administration of the messaging components is performed differently
compared to V5. Figure 7-1 on page 95 shows the conceptual contrast between the two
implementations.

94

WebSphere Application Server V6 Migration Guide

Figure 7-1 Comparison of Version 5 versus Version 6 messaging implementation

In addition to the implementation differences, asynchronous messaging has a different

architecture. Components that are new are a messaging communications component called
the System Integration Bus, or SIBus, and JMS Unified Connection Factories. Figure 7-2
summarizes the relationships between these components.

Figure 7-2 Version 6 Messaging components

An application that uses point-to-point messaging acts as a producer or consumer of

messages with JMS queues.
An administrator can define a JMS queue, an administrative object that encapsulates the
queue name and other configuration properties that the administrator wants to preserve.
The administrator configures the queue onto a destination on a SIBus. Such a queue is
available, over a long period of time, to all applications with access to the destination. The
destination is provided by only one member (an application server or cluster) of the service
integration bus. A destination for a queue is localized to either an application server or cluster.
A queue that is localized to a cluster is partitioned across the servers in that cluster.
A JMS connection factory creates connections to the messaging engine that localizes the
destination. The preferred way for an administrator to define a JMS connection factory for
queues is to define a unified JMS connection factory. Such unified JMS connection factories
support both queues and topics, which enables applications to use the same, common,
connection factories. As an alternative to defining unified JMS connection factories, an
administrator can define domain-specific JMS queue connection factories, as used for
administration before JMS 1.1.
Chapter 7. Runtime administration overview

95

See the IBM Education assistant section on service integration technologies for this set of
tutorials for a more detailed discussion on the messaging design:
ftp://ftp.software.ibm.com/software/eod/WAS_6-0/WPM/index.html

Installation
WebSphere Application Server Version 5 installs the application server, the Web server, and
the Web server plug-ins with a single installer that installs all three in sequence. WebSphere
Application Server Version 6 uses independent installers to install these three components.
See 7.2, Installation on page 96 for details on how to perform installations.

Profiles
Profiles are a concept of packaging a WebSphere installation into a single set of read-only
binary executable files, and multiple sets of writable data files that represent application
server instances. See 7.2.3, Profiles on page 101 for details on the concepts of how profiles
work and how to administer them.

7.1.3 Concepts preserved from V5

If you are familiar with V5, these topics are a review, but if you have only used V4, you should
be aware of these conceptual changes.

HTTP administrative console

The administrative console is has much the same structure compared to Version 5, but the
screens have been reformatted to reduce scrolling. Some of the configuration categories are
changed or moved. The default address has changed to:
http://localhost:9060/ibm/console

See 7.3, Administrative console on page 109 for more details on the changes to the
administrative console.

Cell administration
Network Deployment cells continue to be managed by a deployment manager as they had
been in V5. The deployment manager manages the configuration data for the nodes in the
cell and pushes that data to the node as required. The concept of a cell has been expanded
to include both V5 nodes and V6 nodes in order to allow a staged migration of large numbers
of nodes. See 8.4, V5 Network Deployment on page 140 for an overview of cell migrations.
Also see Starting servers on page 112 for details about starting and stopping cell members.

7.2 Installation
Installation of the WebSphere Application Server Version 6 has changed the basic structure
and sequence of the installers. Previous versions used a single integrated installer which
installed the application server, Web server, and Web server plug-ins all in one installation
step. Version 6 uses independent installer steps coordinated by a Web page containing links
to the individual installers.
Another major new aspect of the application server installer is that installation is now
segmented into independent installation wizards.

96

WebSphere Application Server V6 Migration Guide

7.2.1 Launchpad
The installer launchpad page offers links which starts each of the individual installers.
The launchpad is started by running the launchpad script from the top directory of the
installation media. Figure 7-3 shows a Windows file view of the installation media. If your
operating system is not Windows, the filename would be launchpad.sh and it would be in the
same position on the media.

Figure 7-3 Launchpad location

Running the launchpad script starts the default browser and the browser screen looks similar
to Figure 7-4. Each installer is started by selecting the appropriate link in the blue navigation
bar on the left side of the launchpad page. When you select the link at the left, the right side of
the page changes. You then select the link on the left that begins with the phrase Launch the
installation wizard.

Figure 7-4 Launchpad initial screen

7.2.2 Individual component installers

Each component of the WebSphere Application Server Version 6 installation is created by an
installer specific to that component.

Application Server
The Application Server installer is started from the launchpad page. It is a Java installer that
installs the binary portion of WebSphere Application Server. The Application Server is
installed in two major phases. The first phase consists of installation of the product binary
Chapter 7. Runtime administration overview

97

read-only files. The second phase of the installation is the creation of a profile, which is a
conceptual container for all the writable files that constitute the configuration description for
an application server. After the binary files are installed and a profile is created, the
installation is considered complete. If you need to run multiple servers on the same system,
you would optionally create additional profiles to correspond to those additional server
configurations.
WebSphere Application Server and WebSphere Application Server Express are both
products that use only application servers as the building blocks of systems. Figure 7-5
applies explicitly to these products in that the installation wizard creates a default profile that
describes an application server configuration. Contrast this notion of these two products to
the WebSphere Application Server Network Deployment product by examining Figure 7-6.
WebSphere Application Server Network Deployment uses three types of configuration
descriptions, namely application servers, deployment managers, and node agents.
Therefore, WebSphere Application Server Network Deployment needs to create three
different types of profile to represent those types of configuration entities. The installation
wizard for WebSphere Application Server Network Deployment gives you the option to start
the profile creator, which is a separate command which creates profiles.

Figure 7-5 Conceptual installation for WebSphere Application Server

Figure 7-6 Conceptual installation for WebSphere Application Server Network Deployment

After launching the installer, you accept the software license agreement and specify the
directory where you want to install the binary files. The installer also verifies that you have the
correct operating system prerequisites and prompts you if your system does not meet the
prerequisites.
Figure 7-7 on page 99 shows the feature selection choices you can make. Notice that the
Web server is no longer listed here as it was in previous versions. You can only choose
whether you want samples installed or the Javadoc documentation.

98

WebSphere Application Server V6 Migration Guide

Figure 7-7 Installation selection choices

If you are installing WebSphere Application Server Network Deployment, the installer would
proceed to confirm your selections and install all the binary files. When the installer is done
installing the binary file portion, you are given the option to run the profile creation wizard.
See Creating profiles on page 102 for more information about the profile creation wizard.
If you are installing WebSphere Application Server or WebSphere Application Server
Express, the installer would present more screens to fill in. For these products the first default
profile configuration is integrated with installation of the binary portion.
Figure 7-8 shows the port number assignments. The default selections work fine if you are
only installing one application server on this system. As you create more profiles, the ports
increment to avoid port conflicts. If you have multiple installations on the same system, you
must be aware of all the port assignments and assign numbers such that there are no
conflicts.

Figure 7-8 Installation port assignments

Figure 7-9 on page 100 shows the screen which asks for the node name and host name. You
may specify any name for the node name. The host name typically matches the hostname
setting of the operating system, which is probably the correct value. You may need to specify
some other name if the system has multiple network interfaces.

Chapter 7. Runtime administration overview

99

Figure 7-9 Installation node name and host name

Figure 7-10 shows the Windows Services definition which is displayed only for a Windows
operating system. If the top box is checked, a Windows service is created for this server. You
would then be able to start the server through the Windows Services control panel. By
default, this services runs as the System account. If you do not want the System account, you
can specify an arbitrary user and password if you check the last box.

Figure 7-10 Installation service definition

The installer presents a final screen confirming your values, and the binary files are installed,
and a default profile, named default, is created.

Web server
The Web server that is bundled with WebSphere Application Server Version 6 is IBM HTTP
Server Version 6. In previous versions this Web server installation was integrated with the
application server installation. For V6, IBM HTTP Server Version 6 is installed independently
with a separate installer. The installer is launched via the launchpad. The installation is
straightforward and asks for information such as directory location, port numbers for the
HTTP port and administrative port, and configuration parameters for the Windows Service.
You may default all the screen fields except for the Windows Service settings which is
optional. If you select to have the startup managed by Windows Services, you must either
specify the system user, or specify a valid user and password.

100

WebSphere Application Server V6 Migration Guide

Web Server plug-ins

The WebSphere Web server plug-ins are installed with a separate installer that is accessed
through the Launchpad. See 7.2.1, Launchpad on page 97 for more details on the
launchpad.
The plug-in is native executable code which analyzes incoming HTTP requests and routes
appropriate requests to a WebSphere Application Server. The Web server plug-ins must be
installed on the same system as the Web server because the plug-in files must be locally
accessible to the Web server.
The plug-in installer asks you for several options.

Directory where to install

Location of Web server and its configuration file
Type of Web server
Is the application server remote or local from the Web server?
The name of the Web server by which it is identified in the administrative console.
The location of the application server when local is specified.
The location of the plug-in configuration file

If you specify local such that the application server is on the same system, the installer
creates a Web server instance under the administrative console Web servers section. If you
specify remote, the installer creates a script that you must transport to the system where the
application server is installed. You then run the script on that system to create the Web server
instance.
See 10.3.6, Migrating Web server and WebSphere plug-ins on page 185 for a complete
example of creating a local Web server.

7.2.3 Profiles
A new method of managing installation configurations is the concept of creating multiple
profiles under a single installation on a system. Understanding this concept is crucial in
learning how to create cells of multiple nodes.

Understanding profiles
Profiles allow multiple server configurations to share the same binary files. WebSphere
Application Server Version 4 allows multiple installations to achieve the creation of multiple
servers on the same system. This type of configuration is wasteful of disk space because it
creates multiple copies of the Java binary files. WebSphere Application Server Version 5
creates an improvement over this situation with the wsinstance command. wsinstance
creates multiple servers by creating sets of the writable configuration files for each server that
share the same Java binary files, thus saving disk space.
Since profiles are a more general solution, the V5 wsinstance command no longer exists.
wsinstance has been replaced by the profile creation wizard and the wasprofile command.
Profiles do not have any limitations in that each profile has the same flexibility and power as
any of the other profiles. There is no distinction of profiles with regard to the order of creation.
Table 7-1 on page 102 shows that there are three profile types. Table 7-2 on page 102 shows
that only WebSphere Application Server Network Deployment is capable of creating
Deployment Manager and Custom profiles because the function of those types of profile only
makes sense in a Network Deployment cell environment.

Chapter 7. Runtime administration overview

101

Table 7-1 Purposes for profile types

Profile type

Creates

Application Server

Single application server

Deployment manager

New cell with single deployment manager

Custom

Federated node with node agent but no

application servers

Table 7-2 Profile types allowed

Product

Allows these profiles

WebSphere Application Server

Application Server

WebSphere Application Server Express

Application Server

WebSphere Application Server Network

Deployment

Application Server
Deployment manager
Custom

Creating profiles
Profiles are created by launching the profile creation wizard. Figure 7-11 shows the location
of the profile creation wizard for a Windows system. If you have a different operating system,
it will be in a same relative location within the installation directory, however the name of the
file will be slightly different depending on your type of operating system

Figure 7-11 Location of Profile Creation Wizard

Figure 7-12 on page 103 shows the initial screen of the profile creation wizard.

102

WebSphere Application Server V6 Migration Guide

Figure 7-12 Initial screen for Profile Creation Wizard

Figure 7-13 shows the choice of type of profile you wish to create. You are presented with this
screen only for WebSphere Application Server Network Deployment. If you are creating a
profile for WebSphere Application Server Express or WebSphere Application Server, this
selection screen is not shown because Application Server is the only available type.

Figure 7-13 Profile choices

Figure 7-14 and Figure 7-15 on page 104 show selection of the profile name and location.
The default location is located within the installation directory, but you may place the profile in
any directory.

Figure 7-14 Profile name selection

Chapter 7. Runtime administration overview

103

Figure 7-15 Profile directory location

Figure 7-16 shows specification of the node name, cell name, and host name for the
application server. If you are creating a profile for WebSphere Application Server Express or
WebSphere Application Server, this cell name is not shown because the cell name is not
pertinent to these products.

Figure 7-16 Node, host, and cell name for profiles

Figure 7-17 on page 105 shows the entire list of server ports that may be changed. This
screen shows all the default values. The profile creation wizard detects that there are multiple
profiles already in existence and increment some of the port numbers in an attempt at
maintaining port uniqueness. You should not rely on this feature. You should change port
assignments by strict analysis of which servers will be running on the system concurrently.

104

WebSphere Application Server V6 Migration Guide

Figure 7-17 Profile port assignmens

If you are installing on Windows, you are presented with the screen in Figure 7-18 which
allows you the choice to install the application server as a windows service. If you check that
option, you must supply a valid user and password that is used to run the service every time
your system reboots.

Figure 7-18 Profile Windows service definition

After entering all the required information, the profile creation wizard creates the profile and
then offers to allow you to run the First Steps page in your browser where you can start and
the application server.
Profiles can also be created from the command line using the wasprofile command. The
syntax of wasprofile for creation mode is:
wasprofile -create
-profileName profile_name

Chapter 7. Runtime administration overview

105

-profilePath fully_qualified_profile_path
-templatePath template_path
-nodeName node_name
[-cellName cell_name]
-hostName host_name
-server iSeries_server_name
[-startingPort starting_port | -portsFile filepath]
-winserviceCheck true | false
-winserviceAccountType specifieduser | localsystem
-winserviceUserName yourusername
-winservicePassword yourpassword
-winserviceStartupType manual | automatic | disabled

This is an example of using wasprofile to create a profile using a ports specification file.
Please note that this command would be entered on one line. The example is shown in
multiple lines only for readability.
wasprofile
-create
-profileName node1
-profilePath
C:\ExpressV6\IBM\WebSphere\AppServer\profiles\node1
-templatePath
C:\ExpressV6\IBM\WebSphere\AppServer\profileTemplates\default
-nodeName node1
-cellName cell1
-hostName production1
-startingPort 20002

For a more complete overview of profiles, see the IBM Education Assistant for tutorials on
using profiles at this address:
ftp://ftp.software.ibm.com/software/eod/WAS_6-0/Install_Migration/index.html

7.2.4 Silent installation

Silent installation is accomplished via command line options just as in V4 and V5. However,
the contents of the response file that includes the installation responses have changed
format. If you have customized a response file for a V4 or a V5 installation, you must discard
that file and re-specify your option selections with the new V6 response file.
Each installer has its own response template file with options that are specific to that installer.

Application server response file

Response template files for application servers are located in the WebSphere Application
Server subdirectory on the installation media. Figure 7-19 on page 107 shows the location of
the response template file, responsefile.base.txt, for WebSphere Application Server. For
WebSphere Application Server Express, the response template file is named
responsefile.express.txt.

106

WebSphere Application Server V6 Migration Guide

Figure 7-19 Silent installation response file for WebSphere Application Server

Figure 7-20 shows the location of the response template file for WebSphere Application
Server Network Deployment. In this case, the response template file is named
responsefile.nd.txt. Also note the files beginning with names responsefile.pct. If you want to
create a profile as part of the silent install, you need to edit these files to specify profile
settings.

Figure 7-20 Silent installation response file for WebSphere Application Server Network Deployment

IBM HTTP Server response files

The location of the response template file for the IBM HTTP Server is located in the ihs
subdirectory of the installation media. Figure 7-21 on page 108 shows the location of the file
named responsefile.txt.

Chapter 7. Runtime administration overview

107

Figure 7-21 Silent installation response file for IBM HTTP Server

Web server plug-in response files

The location of the response template file for the plug-in is in the plugin subdirectory of the
installation media. Figure 7-22 shows the location of the file named responsefile.txt.

Figure 7-22 Silent installation response file for Web server plug-ins

Customizing response files

To customize a response file, first make a copy of the response template file that is on the
installation media. When you edit the response file, you should refer to the commentary in the
file which explains each setting. Be sure you change the setting that indicates you agree to
the licensing terms, as shown in this example.
-W silentInstallLicenseAcceptance.value="true"

If you fail to change this setting from the default of false, the installer will not run, since the
interpretation of the false setting means that you do not agree to the license terms.
Each section of the response file has a description of the setting surrounded in comment
lines. You follow the instructions in the commentary and customize the setting that you need
to change. Below is an example section showing how the ports are specified with the default
settings.
#########################################################################
#
# Node name
#
# Please select the node name for the Application Server. Node name

108

WebSphere Application Server V6 Migration Guide

# under one cell has to be unique.

#
# Replace YOUR_NODE_NAME with the actual node name. Comment the line to use
# the default value.
#
-W nodehostandcellnamepanelInstallWizardBean.nodeName="YOUR_NODE_NAME"

In this example, you could not use the default. You must substitute the phrase
YOUR_NODE_NAME for the actual node name you wish to assign.

Running the installer

Once you have customized the response files, you run the installer from the command line
similar to this example. In this case the file C:\temp\myoptionsfile.txt is your customized
response file.
install -options "C:\temp\myoptionsfile.txt" -silent

7.3 Administrative console

The administrative console is accessed from your Internet browser as is the case for any of
the WebSphere Application Server Version 5 products as well as WebSphere Application
Server Version 4 Advanced Edition Single Server. Server configurations are changed by
navigating to the appropriate section in the navigation bar. You then change values in a
browser form and submit the values by clicking the OK button. While you are editing the
configuration, a temporary copy is saved while you work. When all the changes are complete,
save the configuration which then commits your changes to the config directory in the profile
of the server that you are editing.

7.3.1 Console address

The default administrative console address has been changed to:
http://localhost:9060/ibm/console

The default port has been changed to 9060 to avoid conflicting with the 9090 port on the AIX
operating system. Please note that 9060 is a default port assignment that can be changed
when you create a profile for the server which runs the administrative console application.
See Creating profiles on page 102 for more information about creating profiles.

7.3.2 Messaging components

The administrative console has two sections in the left navigation area that pertain to
asynchronous messaging. Figure 7-23 on page 110 shows the JMS resources section which
is similar to that section for V5. WebSphere MQ and Generic refer to external JMS providers
and have the identical configuration semantics as in V5.
Default messaging refers to the embedded JMS messaging provider that reflects the new
messaging design for V6. See Asynchronous messaging architecture on page 94 for an
overview of the new messaging design.
V5 default messaging refers to the V5 compatibility interface to messaging. This interface has
two purposes. The first purpose is to represent the JMS resources for a V5 node running in a
V6 cell. Since a V5 node implements messaging with V5 components, the semantics of
configuration are identical to that of V5. The second purpose is to represent the JMS
resources that have been migrated from a V5 node to a V6 node using the automatic
Chapter 7. Runtime administration overview

109

migration utilities. For this second purpose, the administrative console shows you an interface
that looks similar to how V5 is configured, but the actual messaging implementation is that of
V6. For both of these cases, the application that uses these JMS resources needs no
changes.
See 10.3, Automatic migration: Application Server V5 to Express V6 on page 175 for an
example of migrating a V5 node with an application that uses JMS default resources.

Figure 7-23 JMS resource provider

7.3.3 Data sources

Data source configuration is nested under the JDBC Provider section of the left navigation
area of the administrative console. Figure 7-24 shows that data source configuration has two
different types of data source. The topmost, simply called Data Sources, which we call a
default data source, uses a JCA architecture to manage connections to the database that
backs the data source. This architecture was introduced for V5 and continues to be
configured identically in V6. The second type of data source is identified as Data Sources
(Version 4) uses the V4 Connection Managers architecture.
The choice of which data source to configure is determined by your application. If your
application uses the EJB 1.1 programming interfaces, you should configure a V4 data source.
If your application uses the EJB 2.0 or EJB 2.1 programming interfaces, you should configure
a default data source.
The automatic migration utilities are aware of these two types of data source and migrate to
the right type. For the case of migrating from a V4 system, a V4 type data source is created in
the V6 profile. For the case of migrating from V5, the same type of data source is migrated to
the V6 profile.
See Figure 10-6 on page 174 for an example of migrating a V4 data source. See Figure 10-12
on page 179 for an example of migrating a default data source.

Figure 7-24 JDBC Provider

110

WebSphere Application Server V6 Migration Guide

7.3.4 Plugin-Cfg generation

Plug-in configuration file generation for previous versions is controlled either from the
administrative console or with the command GenPluginCfg. The plug-in configuration file is
then manually transported to the server.
The administrative console method of regenerating the plug-in configuration file has changed
for V6. The control button to regenerate the plug-in configuration file is located under the Web
server instance. Figure 7-25 shows a Web server which is found under the Servers section.
To regenerate the plug-in configuration file, select the Web server, in this case webserver1,
and click the Generate Plug-in button. The message at the top indicates successful file
generation and also indicates the location of the file that was generated.

Figure 7-25 Web server configuration

Generating the plug-in configuration file from the Web server instance has different semantics
than that of previous versions. Previous versions select all applications mapped to any
application server. V6 has a different selection semantic in that only applications that are
mapped to that Web server are selected for mapping into that file. Figure 7-26 shows an
example of an application that is mapped to both webserver1 and server1. This application
must be mapped to webserver1 or it is not included in the plug-in configuration file when it is
generated by the Generate Plug-In button.

Figure 7-26 Selecting servers for Web servers

7.4 How to perform basic functions

These are some basic system management tasks that you will be performing frequently.

Application installation
The installation for WebSphere Application Server Version 6 is started by the launchpad
command located on the top level directory of the install media. Many operating systems
Chapter 7. Runtime administration overview

111

automatically start the launchpad when you insert the media into the external media drive. If
the launchpad is not started automatically, start it from the command line or a graphical files
system viewer. See 7.2.1, Launchpad on page 97 for more details on using launchpad.

Starting servers
A stand-alone node is started from the command line with the startServer command. The
most common syntax for startServer is:
startServer server_name [-profileName profile]

where the profile specification is optional. If profile is omitted, then the default profile is
assumed. The profile can be implicitly selected by running the command from the bin
directory of the profile to be selected.
Here are some examples.
Start the server named server1 in the default profile
cd /d c:\Websphere\bin
startServer server1

Start the server division1 in profile named sales

startServer division1 -profileName sales

Start the server named server1 in the profile under the profiles directory
cd /d c:\Websphere\profiles\policies\bin
startServer server1

Stopping servers
Application servers are stopped with the stopServer command. The most common syntax for
stopServer is:
stopServer server_name [-profileName profile]

The profile specification is optional, and uses the same profile selection semantics as the
startServer command described above.
Some examples of stopServer are as follows:
Stop the server named server1 in the default profile
cd /d c:\Websphere\bin
stopServer server1

Stop the server division1 in profile named sales

stopServer division1 -profileName sales

Stop the server named server1 in the policies profile under the profiles directory
cd /d c:\Websphere\profiles\policies\bin
stopServer server1

Starting a deployment manager

A deployment manager is started with the startManager command. The most common syntax
is:
startManager [-profileName profile]

As with all commands that accept a profile name, the name is optional and defaults to the
default profile. The selected profile must be a deployment manager type. Some usage
examples are shown.

112

WebSphere Application Server V6 Migration Guide

 Start the deployment manager in profile named dmgr1

startManager -profileName dmgr1

Start the deployment manager in the dmgr2 profile under the profiles directory
cd /d c:\Websphere\profiles\dmgr2\bin
startManager

Stopping a deployment manager

A deployment manager is stopped with the stopManager command. The most common syntax
is:
stopManager [-profileName profile]

Some usage examples are shown.

Stop the deployment manager in the profile named dmgr1
stopManager -profileName dmgr1

Stop the deployment manager in the dmgr2 profile under the profiles directory
cd /d c:\Websphere\profiles\dmgr2\bin
stopManager

Starting a node agent

The node agent is created when an application server joins a Network Deployment cell. See
Joining a Network Deployment cell on page 114 for details on how to join a server into a cell.
The node agent must be started before any application servers in the node can start. The
most common syntax is:
startNode [-profileName profile]

As with all commands that accept a profile name, the name is optional and defaults to the
default profile. The selected profile must be a deployment manager type. Some usage
examples are shown.
Start the node agent in profile named node1
startNode -profileName node1

Start the node agent in the node1 profile under the profiles directory
cd /d c:\Websphere\profiles\node1\bin
startNode

Stopping a node agent

A node agent is started with the stopNode command. The most common syntax is:
stopNode [-profileName profile]

As with all commands that accept a profile name, the name is optional and defaults to the
default profile. The selected profile must be a federated node profile. Some usage examples
are shown.
Start the node agent in the profile named node1
stopNode -profileName node1

Start the node agent in the node1 profile under the profiles directory
cd /d c:\Websphere\profiles\node1\bin
stopNode

Chapter 7. Runtime administration overview

113

Joining a Network Deployment cell

A Network Deployment cell is created when the deployment manager profile is created. This
cell that consists of only a deployment manager would be considered an empty cell. The cell
is considered empty because there are no nodes in the cell yet.
A node joins a cell by running the addNode command. The act of joining a cell is also called
federating a node into a cell. The addNode command operates on an application server profile
and contacts a deployment manager and asks it to join the node to the cell.
The most common syntax of the addNode command is shown.
addNode dmgr_host [dmgr_port] [-profileName profile]

The deployment manager host name is the only required argument. The second optional
argument is the port that the deployment manager listens on. As with all commands that
select a profile, the profile name is optional and defaults to the default profile. Here are some
examples of usage of addNode.
Add the node defined by the default profile to the cell managed by dmanager1
addNode dmanager1

Add the node in the profile node1 to the cell managed by dmanager1 which is listening on
port 8885
addNode dmanager1 8885 -profileName node1

After addNode is complete, the node is part of the cell. Assuming the cell was empty at the
start, the cell now has a single node member. The node now consists of two entities, a node
agent and an application server. The node agent is created and started automatically by
addNode. The application server that is created at the time the profile is created still exists, but
it is not automatically started. See Starting servers on page 112 for examples of how to start
application servers.
An alternate way to join a cell is to create a custom profile. The profile creation wizard, upon
receiving your selection of a custom profile type, prompts you to specify a deployment
manager host name and port number. The deployment manager must be started before the
custom profile creation can complete. Upon completion, the cell has a single node member.
However, this node only has a node agent. There is no application servers defined for this
type of profile. Application servers would then be created through the administrative console
for the deployment manager.

7.5 Changes in default settings

There are a few server or application settings that have changed either semantics or a default
value such that applications may not behave in an identical manner from one version of
WebSphere Application Server to a succeeding version. The following settings changed in
the transition to V5. What this means is that an application running on V4 that is migrated to
V6 may not run correctly unless these settings are verified for needed changes. Any
applications being migrated from V5 to V6 do not need any such verification because the V6
settings are identical to those for V5.

7.5.1 Class loader

Class loader semantics have changed in V6 compared to those in V4. There are several
possibilities for symptoms:

114

WebSphere Application Server V6 Migration Guide

 Your application has utility classes that duplicate classes contained in the WebSphere
system classes directories. Your classes fail to override the system classes.
Your application contains classes such that each module may contain classes that conflict
with classes in another module.
Version 4 has three attributes of classloading that work differently from V6:
1. In V4, the application classloader for Web modules precedes the system class loaders
such that classes in the Web module are searched first. This default behavior can be
changed by setting the system property com.ibm.ws.classloader.warDelegationMode to
the value false.
In V6, and also V5, a Web module classloader is searched last with respect to the system
class loaders. This default behavior is changed by changing the setting class loader mode
to PARENT_LAST using the administrative console.
Note: Version 4 refers to the term classloader delegation mode, while V5 and V6 refer
to the same term as simply classloader mode.
EJB modules in V4, and also V5 and V6, have their classloader searched last as a default.
V4 uses the system property com.ibm.ws.classloader.ejbDelegationMode to change the
default behavior. V5 and V6 uses the classloader delegation mode setting PARENT_LAST
to change the behavior such that the EJB module classloader is searched first.
V6 classloader mode is changed in the administrative console. Classloader mode may be
changed at three levels:
Server
Enterprise application
Web module
We recommend that you do not change the classloader mode at the server level, since
this affects all the applications deployed on that server. Our recommendation is to change
classloader mode at the enterprise application level, which affects all the EJB modules. If
any of the Web modules need a different classloader mode, then you would change each
Web module individually.
Figure 7-27 on page 116 shows changing the classloader mode for the enterprise
application MyBankMDB.
Figure 7-28 on page 116 shows changing the classloader mode for a Web module.
You can read more about the topic of class loaders and how to change the behavior in the
WebSphere Application Server InfoCenter. Please refer to this article: Class Loaders,
found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.bas
e.doc/info/aes/ae/crun_classload.html

Chapter 7. Runtime administration overview

115

Figure 7-27 Changing class loader mode and policy for an application

Figure 7-28 Changing class loader mode for a Web module

2. As the default, the application classloader has a module visibility that allows modules to
have their own class loaders, thus eliminating class conflicts. V4 specifies module visibility
settings at the server level only. By contrast, V5 and V6 specify a similar settings at these
levels:
a. Server settings allow you to specify the class loader policy for applications, which can
be one of these values:

116

WebSphere Application Server V6 Migration Guide

i. Single means that a single classloader is used for every application on that server.
This setting provides the most class sharing, but it also offers opportunity for class
conflicts.
ii. Multiple means that multiple class loaders are used. Each application has its own
classloader. This value is the default.
b. Each application can be configured to specify the WAR, or Web module, classloader
policy which can be one of these values:
i. Module means that each Web module has its own class loader. This value is the
default.
ii. Application means that every Web module uses the application class loader. Thus,
a single application class loader loads every module in the application, including
Web modules, EJB modules, and dependency JAR files.
Table 7-3 shows a summary of how to convert from V4 settings to V6 settings.
Table 7-3 MIgrating visibility settings from V4 to V6
Version 4 module visibility

Version 6 application class

loader policy

Version 6 Web module class

loader policy

Server

Single

Application

Compatibility

Single

Module

Application

Multiple

Application

Module

Multiple

Module

J2EE

Multiple

Module

Table 7-27 on page 116 shows an example of setting the WAR class loader policy for the
application MyBankMDB. Figure 7-29 shows an example of setting the classloader policy
for the server server1.

Figure 7-29 Changing class loader policy for a server

Chapter 7. Runtime administration overview

117

3. The application extensions classpath location from V4 has been dropped in favor of a
more flexible scheme called application shared libraries. V4 configures a special directory
under the installation root directory, lib/ext, as a directory where you can place class jar
files and have every application class loader search this classpath. The system
classloaders do not search this path.
The shared library method that is used in V5 and V6 works similarly in that a single
directory, or even a list of directories, can contain application classes that are not visible to
the system class loaders. The advantage over the applications extension classpath of V4
is that the configuration is more flexible.
a. Each shared library can be restricted to a subset of applications rather than the entire
set of applications deployed to a server.
b. Each shared library can be configured to point to an arbitrary list of directories on the
system.
Figure 7-30 shows that you navigate to the shared library definition screen under the
Environment category. Figure 7-31 on page 119 shows creating the shared library
definition. For the classpath field, specify a list of directories, all on a separate line. Do not
use any punctuation such as semicolons. Each directory will contain one or more JAR
files.

Figure 7-30 Navigating to shared library creation

118

WebSphere Application Server V6 Migration Guide

Figure 7-31 Creating a shared library definition

Once you create a shared library definition, you can associate the shared library with one
or more applications. Figure 7-32 shows specifying the shared library with the
MyBankMDB application.

Figure 7-32 Associating a shared library with an application

7.5.2 Transaction isolation level

Applications that perform transactions to databases may have issues with the transaction
isolation level when migrating from V4 to V6. Applications that perform transactions in a Web
module may encounter changes in how the application behaves with respect to the database.
The issue is that the isolation level for transactions in a Web module are defaulted to
TRANSACTION_READ_COMMITTED for V4. When the application is deployed to V6, the
default value for the isolation level is TRANSACTION_REPEATABLE_READ for all supported
Chapter 7. Runtime administration overview

119

databases except for Oracle. The default isolation level for Oracle is
TRANSACTION_READ_COMMITTED. The result is that the application may experience a
loss of performance due to database lock contention. In the worst case, the application may
experience database deadlocks. See this article for more information about isolation level
settings for both Web modules and EJB modules: Isolation level and resource reference,
found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.base.d
oc/info/aes/ae/cdat_isolevel.html

The solution requires that you set the isolation level to the value that your application expects
by specifying the isolation level in a data source resource reference for the data sources that
are used by the application. You can edit resource references by using the Application
Assembly Toolkit that is included with the V6 product, or you can use one of the Rational
Developer products. See this article for more information about how to edit resource
references: Creating or changing a resource reference, found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.base.d
oc/info/aes/ae/tatk_crtresref.html

7.5.3 getResource path syntax

WebSphere Application Server Version 6 changed the manner in which it interprets the
resource path for the getResource and getResourceAsStream methods. See Slash
character on the getResource path on page 31 for background on why this behavior has
changed.
The default behavior is such that many applications may receive a MalformedURLException
on Version 6 whereas these applications did not get the exception on Version 5. This default
behavior was changed to pass the J2EE compliance tests. You can change the behavior back
to the Version 5 behavior by setting the prependSlashToResource property for the Web
container on the application server. Figure 7-33 shows an example of how to set this property
using the administrative console. After adding the property, remember to save the
configuration and restart the server.

Figure 7-33 Setting custom property for Web container

120

WebSphere Application Server V6 Migration Guide

7.6 Automatic migration utilities

This section describes utilities that are shipped with the WebSphere Application Server that
can be used for migration of system configuration and applications from a previous version of
WebSphere Application Server to the current one.

7.6.1 Command line utilities introduction

There are four commands shipped with WebSphere Application Server Version 6 to assist in
migration of configuration and applications between WebSphere Application Server versions.
clientUpgrade - this command is used by developers or administrators to upgrade
resources in client jar files.
convertScriptCompatibility - this command is used by administrators to convert their
configuration from a mode that supports backward compatibility of 5.x administration
scripts to a mode that is fully 6.0.
WASPreUpgrade - this command is used to save WebSphere configuration and application
information into a migration-specific backup directory.
WASPostUpgrade - this command is used to process the migration-specific backup directory
that was created by WASPreUpgrade and import that configuration and enterprise
applications into the current WebSphere Application Server environment.

7.6.2 Configuration migration

There are two utilities that are shipped with the WebSphere Application Server runtime and
used in conjunction with each other to migrate the administration configuration from a
previous version of WebSphere Application Server to WebSphere Application Server Version
6. The overall migration process is to install the V6.0 product, back up the previous version
configuration and necessary files, and import the configuration from the previous version into
WebSphere Application Server Version 6. The migration wizard can call them or you can call
them manually.
These commands, as introduced above, are:
WASPreUpgrade
WASPostUpgrade
Their participation in the overall migration is shown in Figure 7-34 on page 122.

Chapter 7. Runtime administration overview

121

Figure 7-34 General migration process steps

WASPreUpgrade command
The WASPreUpgrade command is used to save the configuration from the previous version of
WebSphere Application Server into a backup directory. This backup directory is later used by
the WASPostUpgrade command to import this configuration into WebSphere Application Server
Version 6. The WASPreUpgrade command provides the status both to the screen and to log
files in the backup directory. ASCII log file names start with the text WASPreUpgrade and
include a date timestamp.
The following files are saved in the backup directory:
For V4.0.x

bin/setupCmdLine.sh (or bin/setupCmdLine.bat for Windows platforms)

classes (not saved for iSeries)
config (V4.0.x Advanced Single Server Edition only)
installableApps
installedApps
installedConnectors (V4.x Advanced Edition only)
properties

For V5.0.x and 5.1.x

classes (not saved for iSeries)

config
installableApps
installedApps
properties
Any instances created by using the wsinstance command (For iSeries, WASPreUpgrade
must be invoked for each instance.)

The WASPreUpgrade command exports the existing application server configuration from the
repository when migrating from V4.x Advanced Edition. If you are migrating V4.x Advanced
Edition, the administrative server of the existing environment must be running.

122

WebSphere Application Server V6 Migration Guide

This command is also available in the migration directory on the Installation CD. This
directory can be used for scenarios where you need to run WASPreUpgrade without first
installing WebSphere Application Server Version 6.

How to run it
WASPreUpgrade backupDirectory currentWebSphereDirectory
[administrationNodeName]
[-import xmiDataFile]
[-nameServiceHost host_name [-nameServicePort port_number]]
[-traceString traceSpec [-traceFile fileName]]

The first two arguments are required and positional. The third argument is required and
positional only when upgrading from WebSphere Application Server Version 4 Advanced
Edition.
Supported parameters include:
backupDirectory
Required positional parameter. The name of the directory in which the WASPreUpgrade
command stores the saved configuration and files, and from which the WASPostUpgrade
command reads the configuration and files. The WASPreUpgrade command creates this
directory if it does not already exist.
currentWebSphereDirectory
Required positional parameter. The name of the installation root directory for the current
V4.0.x, V5.0.x or V5.1.x installation.
administrationNodeName
Optional positional parameter. The name of the node containing the administrative server
for the currently installed product. The value of this argument must match the node name
given in the topology tree on the Topology tab of the Administrative Console for the
currently installed product. The WASPreUpgrade command calls the XMLConfig command
using this parameter. This is a required parameter only when upgrading from WebSphere
Application Server Version 4 Advanced Edition.
-nameServiceHost -nameServicePort
When specified, the WASPreUpgrade command passes these optional parameters to the
XMLConfig command. Use them to override the default host name and port number used
by the XMLConfig command. This is only applicable when upgrading from WebSphere
Application Server Version 4 Advanced Edition.
-import
The name of the XML Metadata Interchange (XMI) configuration file to process. This is
optional when upgrading from WebSphere Application Server Version 4 Advanced Edition
Single Server or WebSphere Application Server Version 4 Advanced Edition because the
program uses the V4.0 config\server-cfg.xml file by default. When migrating from a
WebSphere Application Server Version 4 Advanced Edition configuration that uses
anything other than the default server-cfg.xml file, you must use the -import option along
with the path to the configuration file. You also must use the -import and path option when
running WASPostUpgrade, to point to the non-default xml configuration file in the directory
created by WASPreUpgrade.
-traceString traceSpec -traceFile fileName
Optional parameters to gather trace information for IBM service personnel. Specify a
traceSpec of "*=all=enabled" (with quotation marks) to gather all trace information.

Chapter 7. Runtime administration overview

123

WASPostUpgrade command
The WASPostUpgrade command imports the V4.0.x, V5.0.x or V5.1.x configuration data. This
command uses information created by the WASPreUpgrade command to restore the previous
configuration to a V6 installation.
This command can be run multiple times with different configuration files to incrementally
update the V6.0 configuration.

How to run it
WASPostUpgrade backupDirectory
[-oldProfile < oldProfileName >]
[-profileName < profileName >]
[-import < xmiDataFile >]
[-portBlock < portStartingBlock >]
[-backupConfig < true | false >]
[-replacePorts < true | false >]
[-includeApps < true | false >]
[-scriptCompatibility < true | false >]
[-connectionTimeout < timeoutInMinutes >]
[-substitute "key1=value1[;key2=value2;[...]]"]
[[-traceString traceSpec [-traceFile fileName]]

The first argument is required. Supported parameters include:

backupDirectory
Required parameter. The name of the directory in which the WASPreUpgrade command
stores the saved configuration and files, and from which the WASPostUpgrade command
reads the configuration and files. The WASPreUpgrade command creates this directory if it
does not already exist.
-oldProfile <profile name> - This optional parameter is used for migrating instances
from previous WebSphere Application Server versions. In WebSphere Application Server
Version 5, instance names are defined by "instanceName" and "hostName". These names
are concatenated together to form a unique name. The instance must already exist in the
migration backup directory before executing this command. Prior to this release,
-instance was an undocumented parameter used by iSeries to support their instance
architecture, this support continues as is. For iSeries if not specified the default instance is
used (called "default").
-profileName <profile name> - This optional parameter is used for migrating to profiles
in this release. This profile must have already been created by the user before calling
WASPostUpgrade. If not specified, the default profile is used. An error is reported if no
default is found.
-import < xmiDataFile > An optional name of the XML Metadata Interchange (XMI)
configuration file to process. Specify the WebSphere Application Server Version 4
Advanced Edition Single Server configuration file or an XML configuration data file that the
XMLConfig command created. When migrating from a WebSphere Application Server
Version 4 Advanced Edition Single Server configuration that uses anything other than the
default server-cfg.xml file, you must use the -import option along with the path to the
non-default XML configuration file in the directory created by WASPreUpgrade. If not
specified, the program uses the default XML configuration file in the backup directory.
-portBlock <startingPortNumber> - This optional parameter is used to specify the
starting seed value to be used when creating new ports.
[-backupConfig <true|false>] - An optional parameter used to back up the existing
configuration of the current profile before adding the saved configuration from the earlier
release to the current instance. The default is true, to use the backupConfig command to

124

WebSphere Application Server V6 Migration Guide

save a copy of the current configuration into the profile_name/temp directory. Use the
restoreConfig command to restore that configuration as required.
-replacePorts <false|true> - An optional parameter used to define how to migrate
virtual host and server transport ports. The default for migrations from V4.0.x is false (do
not replace default port definitions); the default for migrations from V5.x is true (do replace
default port definitions). Migrating adds configuration data from the previous version to the
existing data in the V6.0 configuration. In some cases, existing port definitions from the
earlier release are carefully set to avoid port conflicts with other products. In such cases, it
is likely that you would want to migrate the settings into V6.0. Use the -replacePorts
parameter to totally replace settings in the V6.0 environment with the settings from the
previous version. Select true to replace all virtual host alias port settings during migration.
If migrating from V5.0.x or later, transport settings in existing servers are replaced by the
settings from the previous version.
-includeApps <true|false> - This optional parameter is used to specify whether to only
migrate the configuration or to include the user enterprise applications as part of the
migration. The default setting is true. System applications are migrated irrespective of this
setting. Sample applications are typically not migrated. The only exception is during ND
Phase1 processing.
-scriptCompatibility <-true|false> - This optional parameter is used if migration
should create Transport and ProcessDef definitions in the configuration instead of
Channels and ProcessDefs. This would be used if customers have existing wsadmin
scripts or programs that used SM configuration APIs to create or modify Transport or
ProcessDef definitions. The default is true.
-connectionTimeout timeoutInMinutes This is an optional parameter to be used if a
SOAP/RMI time-out occurs when performing a migration of a managed node. This
parameter is specified in minutes (the default value is 10). It is possible to run into a
SOAP/RMI time-out issue when migrating a very large or very complex configuration; if
this happens, you should increase the amount of time before a SOAP/RMI connection
time-out occurs and run migration again.
-substitute "key1=value1[;key2=value2;[...]]"
An optional argument passed to the XMLConfig command. Specify values for security
variables to be substituted (for example, -substitute
"NODE_NAME=admin_node;APP_SERVER=default_server"). In the input XML data file, each
key should appear as $key$ for substitution. This argument substitutes any occurrence of
$NODE_NAME$ with admin_node and $APP_SERVER$ with default_server in the input
XML file.
If the substitution string contains semicolons, use $semiColon$ to separate it from the ";"
delimiter. On UNIX platforms, be sure to add an escape character to each dollar sign ($)
within the substitution string (for example, \$semiColon\$). This parameter is applicable
for configurations saved from Versions 4.0.x Advanced Edition.
-traceString -traceFile Optional parameters to gather trace information for IBM service
personnel. Specify a traceSpec of "*=all=enabled" (with quotation marks) to gather all
trace information.

After migration
It is always a good idea to review the results of migration by reviewing the migration logs in
the backup and V6.0 profile logs directory. Some of the configuration may need to be
modified based on the results of the migration.

Chapter 7. Runtime administration overview

125

7.6.3 Graphical wizard for configuration migration

A separate migration wizard for WebSphere Distributed platforms is also provided that
provides a Graphical User Interface (GUI) to the WASPreUpgrade and WASPostUpgrade
commands.
In previous versions of WebSphere Application Server, the migration wizard is integrated with
the installation process for WebSphere Distributed platforms. This approach has some
distinct advantages and disadvantages. The advantages include ease of use and integration
with the silent installation support. However, the disadvantages include the inability to apply
automatic migration utility fixes before migrating and a combination of skill sets required for
the installation process.
The separate migration wizard approach eliminates the disadvantages and continues to
provide a easy to use interface. The ability to integrate with silent install can be replaced by
calling the WASPreUpgrade and WASPostUpgrade commands directly as part of the installation
tasks.
The mIgration wizard does not provide interfaces for all the options that are available by using
the WASPostUpgrade command directly. However, it can be used for most migration tasks.
The migration wizard can be launched from the FirstSteps window shown in Figure 7-35.

Figure 7-35 First steps

Figure 7-36 on page 127 shows the initial screen of the migration wizard. The initial screen
lists an overview of the installation and migration steps for WebSphere Application Server
Version 6.

126

WebSphere Application Server V6 Migration Guide

Figure 7-36 Initial screen of migration wizard

1. Install WebSphere Application Server Version 6 using the installation wizard. Note that for
Base and Express installations, a default profile is created during this step.
2. Use the profile creation wizard, which is also located in the First Steps window, to create
any profiles that are required. For WebSphere Application Server Network Deployment no
default profile is created during installation. For this environment, a deployment manager
profile must be created. For each managed node in the existing 5.0 or 5.1 cell either a
stand-alone profile or a custom profile (that is not federated during profile creation) must
be created using the profile creation wizard. See 10.5.3, V6 installation preparation on
page 201 for more details on specific node name or cell name requirements for specific
migration scenarios.
3. The third step is to run the Migration wizard using one of the profiles created in the
previous steps.
Figure 7-37 on page 128 shows a list of existing WebSphere Application Server Versions
4.0.x, 5.0.x and 5.1 installations that can be migrated. You can either select one from the list
or supply a directory name of a different one if, for some reason, it was not detected and
entered into the selection list. The last entry field is used only when migrating from
WebSphere Application Server V4.0. For WebSphere Application Server Version 4 Advanced
Edition, you can specify a file created by XMLConfig export instead of the one migration would
use by exporting XMLConfig directly. For WebSphere Application Server Version 4 Advanced
Edition Single Server, you can specify a configuration file other than the default one.

Chapter 7. Runtime administration overview

127

Figure 7-37 Detected versions in migration wizard

Figure 7-38 shows how to specify the location of the migration-specific backup directory that
is created by WASPreUpgrade. You can specify any valid directory name for this field. It is
advisable to specify a location that is not a subdirectory of an existing WebSphere Application
Server location. It is possible that, at some point, that version of WebSphere Application
Server may be uninstalled and you may unintentionally erase this migration-specific backup
directory.

Figure 7-38 Specifying backup directory in migration wizard

Figure 7-39 on page 129 shows how to select the Version 6 profile that is used during
migration. It has a drop-down menu of all existing profiles that are compatible (to the basic
degree) with the type of migration that is being performed. For example, in this case we are
migrating from WebSphere Application Server Version 5. A compatible profile is either a
stand-alone or a custom profile. These types of profiles are listed in the drop-down box.
However, there are some scenarios where the values used when creating these profiles is
128

WebSphere Application Server V6 Migration Guide

important. See 10.5.3, V6 installation preparation on page 201 for more details on specific
node name or cell name requirements for specific migration scenarios.

Figure 7-39 Specifying target profile name in migration wizard

Figure 7-40 shows the choice for how to handle migration of port assignments. The default
value is to use the same port values in the WebSphere Application Server Version 6
configuration as the existing WebSphere Application Server configuration. This supposes a
replacement of the existing WebSphere Application Server installation with the latest
WebSphere Application Server Version 6 configuration. Choosing this option means you
cannot run WebSphere Application Server installations and the new WebSphere Application
Server Version 6 installations concurrently because there would be port conflicts.

Figure 7-40 Specifying port assignments in migration wizard

You can also choose to not map the port values over during the migration process. You do
this by selecting to use port values already assigned to the target profile. This allows you to

Chapter 7. Runtime administration overview

129

run the previous WebSphere Application Server installations and the new WebSphere
Application Server Version 6 installations concurrently. This radio button maps to the
-replacePorts parameter on the WASPostUpgrade command.
Figure 7-41 shows the start of running the WASPreUpgrade command in the migration wizard.
The command takes some time to complete.

Figure 7-41 Executing WASPreUpgrade in migration wizard

Figure 7-42 shows the completion of running the WASPreUpgrade command in the migration
wizard. Verify the last message is shown which indicates a successful first step of Migration
has completed. One failure that can occur for WebSphere Application Server Version 4
Advanced Edition scenarios is when the 4.0 administration server is not running. When
WASPreUpgrade runs for this scenario, it calls XMLConfig export to access the existing
configuration in the repository. The 4.0 administration server must be running for this to work.

Figure 7-42 Completion of WASPreUpgrade in migration wizard

Figure 7-43 on page 131 shows the results of running the WASPostUpgrade command in the
migration wizard. This is the final panel and shows a summary of the final messages from
WASPostUpgrade. This can be quite a bit of output and shows the information of migrating the
configuration, installing the applications and (in some scenarios) calling GenPlugInCfg to
130

WebSphere Application Server V6 Migration Guide

generate the plug-in configuration. It is important to view the final message for an indication of
success, warning or failure. In most cases a warning message is displayed at the bottom of
the panel. You should review any messages that have a code ending in "W" so that you can
see warnings about deprecations or configuration updates that need to be done.

Figure 7-43 Completion in migration wizard

7.6.4 Script compatibility

The convertScriptCompatibility command is to convert all or portions of a configuration
from script compatibility mode to a configuration that may not be compliant with existing 5.x
customer scripts.
The scope of the configuration changes in the configuration are dependant on the type of
profile that is being processed. For stand-alone profiles, the default is to convert all servers
owned by the node in that configuration. An additional -serverName parameter can be used
for more granular control. For Deployment manager profiles, the default behavior is to convert
all nodes and all servers owned by those nodes. Additional parameters -nodeName and
-serverName can be used for more granular control. Note that nodes are checked to verify
that they are at a 6.0 level before they are processed, this is required to support mixed-node
configurations. Client environments are not processed.
The conversions that take place by this command are:
1. processDef -> processDefs - objects of type processDef are converted to use
processDefs as defined in the WebSphere Application Server Version 6 server.xml model.
The existing processDef object remains in the configuration and is ignored by the runtime.
For Distributed and iSeries platforms there can be only one occurrence of a processDefs
object in a server configuration. If an existing processDefs object is found when
performing this conversion then it is used and updated, otherwise a new object is created.
For zSeries platforms more than one processDefs object can exist in the server. For this
case the object with the same name is found and updated.
2. transports -> channels - Existing transport entries in the configuration are mapped to
channel support. This affects server.xml and serverindex.xml files. The values of the
transport settings are used to create new channel entries.

Chapter 7. Runtime administration overview

131

How to run it
convertScriptCompatibility [-help]
[-backupConfig true | false]
[-profileName <profile name>]
[-nodeName <node name>]
[-serverName < server name>]
[[-traceString <traceSpec> [-traceFile <fileName>]]

where:
[-help] - displays help for the command
[-backupConfig <true | false>] - This is used to back up the existing configuration
before changes are made to the configuration by migration. If not specified, the default is
true.
[-profileName <profile name>] - If provided, this value can be used to specify a specific
profile configuration in the WebSphere Application Server Version 6 environment. If not
specified, the default profile is used. If the default has not been set or cannot be found, an
error is returned.
[-nodeName <node name>]- If provided, this can be used to specify that a particular node
name should be processed instead of every node in the configuration. It is most useful
when processing a Deployment manager profile but is allowed on all profile types. If not
specified then all nodes in the configuration are converted.
[-serverName <server name>] - If provided, this can be used to specify that a particular
server name should be processed instead of every server in the configuration. It can be
used on all profile types and can be used in conjunction with the -nodeName parameter
when processing Deployment manager profiles. If not specified then all servers in the
configuration are converted. If used in conjunction with the -nodeName parameter then all
processing is limited to the specified node name.
[-traceString traceSpec [-traceFile fileName]] - These optional parameters are
used to gather trace information for use by IBM service personnel. The value of
traceString is "*=all=enabled" and must be specified with quotation marks to be
processed correctly.

7.6.5 J2EE application clients conversion

J2EE EAR files may exist on the client or server that have client JARs contained in them that
have J2EE resources within those JARs. If these resources are at WebSphere Application
Server V4.0 level they need to be updated to be WebSphere Application Server Version 6
resources. You may also want to upgrade WebSphere Application Server Versions 5.0 and
5.1 applications to ensure they are using the latest level of WebSphere Application Server 6.0
resources. The clientUpgrade command can be run on these J2EE EAR files to perform this
upgrade.
This command is not run automatically as part of the installation process because the location
of the J2EE EAR files are not in a predetermined location. The customer must run this
command against their J2EE EAR files themselves.
Note that copies of client JARs are not made in the J2EE EAR file. If the J2EE EAR file needs
to be used with WebSphere Application Server V4.0 as well as with WebSphere Application
Server Version 6, then it is necessary to make a copy of the J2EE EAR file before using
clientUpgrade.

132

WebSphere Application Server V6 Migration Guide

How to run it
clientUpgrade EAR_file
[-clientJar client_jar ]
[-logFileLocation logFileLocation]
[-traceString traceSpec [-traceFile fileNSame ]]

where:
EAR_file is the fully qualified path to the EAR file that contains client JAR files to process.
-clientJar specifies a JAR file for processing. If not specified, the program transforms all
client JAR files in the EAR file.
-logFileLocation Use this optional parameter to specify an alternate location to store the
log output.
-traceString -traceFile gathers trace information for IBM service personnel. Specify a
traceSpec of "*=all=enabled" (with quotation marks) to gather all trace information.

Chapter 7. Runtime administration overview

133

134

WebSphere Application Server V6 Migration Guide

Chapter 8.

Migration tasks
This chapter discusses major migration tasks for specific WebSphere components.

Copyright IBM Corp. 2005. All rights reserved.

135

8.1 Migration utilities supported versions

Table 8-1 shows the products that the automatic migration utilities support as a starting point.
Table 8-1 Supported WebSphere versions for migration starting points
Version 4.0

Version 5.0

Version 5.1

WebSphere Application Server

Advanced Edition

WebSphere Application Server

WebSphere Application Server

WebSphere Application Server

Advanced Edition Single Server

WebSphere Application Server

Express

WebSphere Application Server

Express

WebSphere Application Server

Enterprise Edition

WebSphere Application Server

Network Deployment

WebSphere Application Server

Network Deployment

WebSphere Application Server

Enterprise

WebSphere Business
Integration Server Foundation

Each of these products may be migrated using automatic migration utilities. The migration
utilities WASPreUpgrade and WASPostUpgrade work as a pair of command line commands to
copy and transform the server configuration and applications and place that information into a
V6 profile. See 7.6, Automatic migration utilities on page 121 for an overview of the
automatic migration utilities. See 7.2.3, Profiles on page 101 for an overview of profiles.

8.2 Migrating single stand-alone nodes

All of the products in Table 8-1 may be configured to operate as a single stand-alone server.
Even though we use the term stand-alone server, we also extend the term to mean a
stand-alone node that may have multiple application servers defined. We address Network
Deployment cell configurations in 8.4, V5 Network Deployment on page 140. However, the
migration steps described for a stand-alone node also apply to each of the nodes in a
Network Deployment cell.
See 10.2, Automatic migration: V4 AE Single Server to V6 on page 171 and 10.3,
Automatic migration: Application Server V5 to Express V6 on page 175 for complete
examples of migrating stand-alone nodes.
The migration steps for stand-alone servers is conceptually simple. See Figure 8-1 on
page 137 for a diagram of the steps.

136

WebSphere Application Server V6 Migration Guide

Figure 8-1 Migrating Application Servers from previous versions

1. Complete a V6 installation and create an application server type profile. When you create
the profile and specify the node name, be aware of your choice of node name. The node
name of the target V6 node must match the node name of the source application server
configuration for these configurations, where the source system is:
WebSphere Application Server Version 4 Advanced Edition.
WebSphere Application Server V5 node that is a member of a Network Deployment
cell
For other source configurations, the node name is not crucial.
See 7.2, Installation on page 96 for more information about installation and profile
creation.
2. Before WASPreUpgrade is run, you may want to stop the server, but stopping at this point
is optional. One exception is migrating WebSphere Application Server Version 4
Advanced Edition. The V4 administration server must be active so that WASPreUpgrade
can contact the administration server to extract the configuration information.
3. WASPreUpgrade is run on the source system to copy the server and application into a
backup directory. WASPreUpgrade may be run directly from the installation media, thus
eliminating the need to install Version 6 on the source system. Running directly from the
installation media allows you to migrate from one system to a different system. If you do
want to migrate to a different physical system, you need to transfer this directory in its
entirety to the target system in order to perform the next step.
Once WASPreUpgrade completes consult the output log which is placed in the backup
directory that it creates. You should evaluate any warnings or errors and take appropriate
action.
If you chose to use the migration wizard, you will skip the next step. Also note that since
the migration wizard calls WASPreUpgrade and WASPostUpgrade in a seamless step, you
cannot use migration wizard in the situation where you are migrating to a different physical
system. See 7.6.3, Graphical wizard for configuration migration on page 126 for more
information about running the migration wizard.
4. WASPostUpgrade is run on the backup directory. Examine the output log for any warnings
or errors.
5. Once the WASPostUpgrade completes, the new node can be tested while the old node
continues to run. If the old node and the new node reside on the same physical system,

Chapter 8. Migration tasks

137

you may have to stop the old node and all the servers if you did not take steps to insure
that there are no port conflicts. When the new node is finished testing, the old node can be
permanently taken down and the new node switched online.
6. If your application server works in conjunction with a Web server, you must upgrade your
Web server installation to a supported level. You must also upgrade the WebSphere
plug-in installation so that the Web server is able to route requests to the V6 application
server. This upgrade is a manual installation of these two components. See Web server
on page 100 for an overview of the installation steps for Web servers and plug-ins.
There are several situations that may require you to make manual modifications to the target
configuration once migration is complete. You may either edit files in the backup directory or
change the configuration items in the target profile with the administrative console. Editing the
files in the backup directory may be best for you if you are comfortable with editing XML files
or you have some sort of automation available to make changes. If you do make change to
the backup directory, make sure you make a backup copy of any file you change. If you are
not comfortable changing XML files, you should make your changes with the administrative
console.
If you are migrating from one system to a different physical system, the new system may
not be perfectly identical. Some items to examine and evaluate the need to change are
Users and passwords for security settings.
Fixed file system paths that may part of a classpath for resources such as JDBC
providers or shared libraries.
Database specifications such as database names, database hosts, or database users.
Port conflicts may arise after migration. The remedy is to respecify the port assignments in
a new profile and rerun the migration steps. The migration wizard may help you identify
port conflicts. See Infocenter external reference for more details on fixing port conflicts.

8.3 Version 4: multiple servers

WebSphere Application Server Version 4 Advanced Edition has the capability of managing
multiple servers through a single point called the administration server. WebSphere
Application Server Network Deployment Version 6 is the equivalent product that has the
same capability of managing several servers on different systems from a single point of
control. The Version 6 Network Deployment manager performs the same function as the V4
administration server in that it acts as a single control point for managing multiple servers.
We describe the general steps to migrate a WebSphere Application Server Version 4
Advanced Edition installation to a WebSphere Application Server Network Deployment
Version 6 with all of the node configuration preserved as well as the applications.
See 10.4, Automatic migration: V4 AE Server Group to a V6 Network Deployment Cluster
on page 189 for a detailed example of the following steps.
1. Install WebSphere Application Server Network Deployment Version 6 and create a profile
with the type of deployment manager. See 7.2.3, Profiles on page 101 for detailed
information about creating profiles.
2. Migrate the global configuration information from the V4 installation to the deployment
manager profile. Figure 8-2 on page 140 illustrates this step.
3. Start the deployment manager. See Starting a deployment manager on page 112 for
details about starting the deployment manager.
4. For each node in the V4 installation that you wish to migrate:

138

WebSphere Application Server V6 Migration Guide

a. Migrate the node from the V4 installation to a V6 Application Server node according to
the detailed steps outlined for a single node in 8.2, Migrating single stand-alone
nodes on page 136. Ensure that the node name in the V6 profile matches the node
name of the V4 node that you are attempting to migrate. Figure 8-3 on page 140
represents this step.
b. Add the node to the cell using the addNode command. The action of adding a node to a
cell is also called federating a node. Determine whether you want the applications
installed on that node to remain on the node once it joins the cell. If you do want to
keep the applications, make sure you use the -includeapps option on the addNode
command.
5. After all the nodes are migrated, install any applications that are assigned to server groups
in the V4 installation. If there are such applications, they are placed in the installableApps
directory under the application server profile. Installation is accomplished by installing an
Enterprise Application via the administrative console on the deployment manager.
Note that the difference between migrating the deployment manager and migrating a node is
only the match on the node name. For the deployment manager, the V6 node name must not
match any of the V4 node names and thus only global information is copied to the
deployment manager profile. In other words, global information is intended to be applied to
every node of the cell. For an application server node migration, the V6 node name of the
profile must match the intended V4 node name; the node name is used as an implicit
selection for the intended node. If the node does not match, and the target is an application
server type profile, the migration utilities do not migrate the intended information, namely the
node configuration and applications.
The applications that are migrated for a node migration fall into two categories.
The applications that are assigned to specific servers in the V4 domain are migrated to the
V6 application server profile in an installed state. This means the application is installed,
configured, and ready to go. When you start the application server, those installed
applications are loaded and ready to execute.
When you add the node to the cell, you have to determine whether you want the
applications that are automatically installed by the automatic migration utilities to remain
installed after joining the cell. If you do want the applications to remain, remember to
specify -includeApps on the addNode command.
addNode dmgr_host -includeApps

Applications that are assigned to server groups, or clusters, are not automatically installed
in the node. These applications are stored, in EAR format, in the installableApps directory
in the V6 profile. It is your responsibility to install these manually. We recommend that you
wait until all the nodes are joined into the cell. At that time, you would install the clustered
applications into the cell via the deployment manager administrative console.

Chapter 8. Migration tasks

139

Figure 8-2 Migrating deployment manager from V4 configuration

Figure 8-3 Migrating Application Server from V4 configuration

8.4 V5 Network Deployment

WebSphere Application Server Network Deployment Version 6 has a similar architectural
structure as WebSphere Application Server Network Deployment Version 5. Therefore, a V5
Network Deployment cell can be migrated to a V6 cell with a great deal of automation. Very
few manual steps are needed. Moreover, each of the nodes of the cell can be migrated in an
incremental fashion such that some of the nodes are not yet migrated, while some are, and
the cell continues to operate. This concept of incremental migration whereby you can operate
a cell with nodes at different versions is called a mixed version cell. A mixed version cell is
flexible enough that nodes in a cooperating server cluster may be at different versions.
See 10.5, Automatic migration: V5 Network Deployment Cluster to V6 Network Deployment
Cluster on page 198 for a detailed example of the following steps.
1. Install WebSphere Application Server Network Deployment Version 6 and create a profile
with the type of deployment manager. See 7.2.3, Profiles on page 101 for detailed
information about creating profiles.
2. Migrate the deployment manager from the V5 Network Deployment installation to the V6
deployment manager profile. When you create the profile, make sure you specify the cell
name such that it matches the cell name of the V5 cell. You should also ensure that the
deployment manager node name matches that of V5. Figure 8-4 on page 141 represents
this step.
140

WebSphere Application Server V6 Migration Guide

3. Start the deployment manager. See Starting a deployment manager on page 112 for
details about how to start the deployment manager.
When this step is complete, the cell is fully operational. The V6 deployment manager is
managing the cell consisting entirely of V5 nodes.
4. If your configuration is using an external Web server, upgrade the Web server and plug-ins
manually. Figure 8-5 on page 142 shows this step. At the conclusion of this step, the cell is
fully operational. The upgraded Web server routes HTTP requests to V5 application
servers through V6 plug-ins.
a. Manually upgrading a Web server is a matter of installing the proper version of Web
server that is approved for use with WebSphere Application Server Version 6. See
Appendix A, Prerequisite software on page 225 for a list of approved Web servers.
See 7.2, Installation on page 96 for an overview of installing IBM HTTP Server
Version 6.
b. Manually upgrading the Web server plug-ins is a matter of installing the WebSphere
Application Server Version 6 Web Server Plug-ins as a separate install procedure. See
7.2, Installation on page 96 for an overview of installing Web server plug-ins.
5. Migrate each node from the V5 installation to a V6 Application Server node according to
the detailed steps outlined for a Single Server Node in 8.2, Migrating single stand-alone
nodes on page 136.
Ensure that the node name in the V6 profile matches the node name of the V5 node that
you are attempting to migrate.
After migrating the node, start the node agent with the startNode command before
attempting to start any of the application servers.
Figure 8-6 on page 142 represents this step. The cell now consists of one or more V5
nodes, one or more V6 nodes, and a Web server routing HTTP requests to those nodes
via a V6 Web server plug-in.

Figure 8-4 Version 5 cell migration - deployment manager

Chapter 8. Migration tasks

141

Figure 8-5 Version 5 cell migration - Web server and Plug-in

Figure 8-6 Version 5 cell migration - application server node

The following are temporary restrictions on the capabilities of mixed version cells. These
restrictions are in effect at the time of this publication for the initial release of V6.0. These
restrictions will be lifted with a future fix delivery. Check the WebSphere support Web site for
recent fix information at this address:
http://www-1.ibm.com/support/docview.wss?rs=180&context=SSEQTP&uid=swg27004980#1

142

WebSphere Application Server V6 Migration Guide

so you can determine when you can apply code updates to address these restrictions.
Additional V5 nodes cannot be added to a mixed version cell with addNode. The only
means to create a mixed node cell that contains both V5 and V6 nodes is to migrate a V5
cell to V6 using the automatic migration utilities. However, you can always add a V6 node
to any cell with addNode.
Additional servers cannot be added to a V5 node participating in a mixed version cell.
However, you can always add servers to a V6 node in a mixed version cell.
The only means to expand the size of a server cluster defined in a mixed version cell is to
add a V6 server to the cluster.
These restrictions affect expansion capability of the cell with respect to adding servers or
nodes. There are no restrictions with nodes and servers in a cell with respect to modifying the
configuration of these nodes and servers, regardless of its version. In other words, you are
free to modify settings, install and uninstall applications, and make any other changes that
you may need to make to control the operation of the cell.

8.5 Web servers and plug-ins

Migration of Web servers and the Web server plug-in modules is a manual task that consists
of a new installation of these components. You should install both of these components in
order to have a correct relationship with the V6 application server.

8.5.1 IBM HTTP Server Version 6

If you are using IBM HTTP Server in your V4 or V5 WebSphere installation, you may want to
upgrade to IBM HTTP Server Version 6. You have the flexibility to install IBM HTTP Server
Version 6 in either of these ways.
Upgrade your previous version in place if you no longer need the previous version.
However, you should edit the httpd.conf configuration file to remove the plug-in
customization lines.
Install in a new directory if you need to run the previous version Web server at the same
time. Make sure you choose port numbers that are different from the version you already
have installed.
See the IBM Education assistant for more information about installing IBM HTTP Server V6 at
this address:
ftp://ftp.software.ibm.com/software/eod/WAS_6-0/Install_Migration/index.html

8.5.2 Other Web server brands

If you are using a non-IBM brand of Web server, you should verify that the version you have is
approved for use with WebSphere V6. See Appendix A, Prerequisite software on page 225
for information about Web server compatibility. Contact your Web server vendor for
information about installing non-IBM Web servers.

8.5.3 Web Server Plug-ins

WebSphere V6 Web Server Plug-ins are no longer packaged with the application server
installation. Web Server Plug-ins are installed with a separate installer in a separate directory.
Web Server Plug-ins should be installed after installing a V6 compatible Web server.

Chapter 8. Migration tasks

143

See the IBM Education assistant for more information about installing plug-ins at this
address:
ftp://ftp.software.ibm.com/software/eod/WAS_6-0/Install_Migration/index.html

8.6 Messaging migration

If you use V5 JMS messaging resources, please be aware of several migration topics that
may affect you.
If you use WebSphere MQ as a JMS provider, you must update your WebSphere MQ
installation to Fix Pack 8 or later. You can obtain more information about the latest fix packs
at:
http://www-306.ibm.com/software/integration/mqfamily/support/summary/

If you use wsadmin administration scripts for V5 to control or create JMS resources, you may
have to modify your scripts to run on V6. See 9.4, Migrating from version 5 embedded
messaging on page 152 for more details about which scripting commands are affected.
JMS resources on V6 are configured differently from V5 in the administrative console. See
7.3.2, Messaging components on page 109 for an overview of these changes. See 10.6,
Manual migration: installation of J2EE 1.3 Enterprise Application on V6 Application Server
on page 210 for a detailed example of how to configure these resources.

8.7 Web Services

There are a few other considerations to take into account if you are using some Web Services
in releases prior to WebSphere Application Server Version 6 and you plan to migrate their
usage. These considerations are primarily in the area of migrating your environment. The
scenarios described below are not automatically migrated. They require planning and some
manual steps that are described below.

8.7.1 Migration of Web Services Gateway configuration

The configuration of Web Services Gateway has changed in WebSphere Application Server
Version 6. In previous versions, it was contained outside of the WebSphere Application
Server configuration and managed by a program that was not part of the administrative
console. The Web Services Gateway configuration has been merged into the administrative
console and profile structure in V6.0. This is one of the migration considerations when using
Web Services Gateway in V6.0.
There are a couple of alternative migration strategies that can be chosen for this scenario,
depending on the requirements. Coexistence is supported. This means that you can run both
Version 5 and Version 6 of Web Services Gateway concurrently. If coexistence is not required
then you can migrate directly from WebSphere Application Server Version 5 to WebSphere
Application Server Version 6.

Coexistence support
If you have Web Services Gateways running on WebSphere Application Server Version 5,
they can, subject to certain restrictions, co-exist with WebSphere Application Server Version
6 gateway instances.

144

WebSphere Application Server V6 Migration Guide

Before you choose to use a mixture of V5 and V6 gateways, you should be aware of the
following restrictions to co-existence:
The V5 Web Services Gateway application is not supported on V6.0 or later application
servers.
The service integration technologies endpoint listener applications are not supported if
installed on V5 application servers.
The V6 administrative console and the service integration technologies administrative
commands can only be used to change the configuration of gateways running on V6
application servers. To change the configuration of a gateway running on a V5 application
server, you use a Web browser to access the V5 gateway user interface.

Steps for this task

1. Save the V5 gateway configurations.
2. Migrate the cell to V6 without migrating the application servers.
3. Restore the V5 gateway configurations to the V5 application servers within the V6 cell.

Migrating a complete gateway configuration

You use the command migratewsgw to migrate an existing gateway configuration from a V5
application server to the new gateway capability on a V6 application server.
The migration procedure takes an existing gateway application whose configuration has been
exported to an XML file and uses the exported XML file to configure the same gateway
functionality on a V6 application server. You can migrate a V5 gateway that is in production
use without stopping the gateway; requester applications can then switch over to using the
new gateway configuration while the existing V5 gateway continues to run.
The considerations and number of steps to perform this migration are significant and it is best
to see the following WebSphere Application Server Version 6 InfoCenter article for more
information: Migrating a complete gateway configuration, found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.pmc.nd
.doc/tasks/twsg_coex_migrate.html

8.7.2 Migration of Web Services Gateway applications using WS-Security

Web Services is an evolving set of specifications. The security aspect of this is called
WS-Security and is also evolving. WebSphere Application Server V5.0.2 and V5.1 support
SOAP Message Security Draft 13 (formerly Web Services Security Core Specification).
WebSphere Application Server Version 6 supports SOAP Message Security Draft 13 as well
as SOAP Message Security V1.0, which became the V1.0 OASIS standard. However, Web
Services Gateway only supports SOAP Message Security V1.0 in the initial release of
WebSphere Application Server Version 6. All WebSphere Application Server V5.0.2 and V5.1
Web Services Gateway applications using WS-Security must be changed to use this latest
version of the specification.
Note that this is considered a temporary restriction and support for SOAP Message Security
Draft 13 is currently planned to be provided in a future WebSphere Application Server Version
6 maintenance release.

Chapter 8. Migration tasks

145

8.7.3 Migration to UDDI V3

The supported version of UDDI in WebSphere Application Server Version 6 is UDDI V3. This
is different than prior releases of WebSphere Application Server and migration of the UDDI
data is required.
You can use the process described in this section to migrate a UDDI Registry to UDDI V3,
running in WebSphere Application Server Version 6, subject to the following constraints:
Your existing registry uses a DB2 database.
Your existing registry runs in WebSphere Application Server Version 5 or later.
If you are migrating from the UDDI V1.1 or 1.1.1, which runs on WebSphere Application
Server V4.x, you should first migrate to UDDI V2 running on WebSphere Application Server
Version 5 as described in the WebSphere Application Server V5 Information Center.
You can only run the V2 UDDI Registry, supplied in WebSphere Application Server Version 5,
in a WebSphere Application Server Version 6 server if you are running in a mixed version cell
migration mode. In this configuration, the WebSphere Application Server Version 6
deployment manager manages the Version 5.x nodes, and the V2 UDDI Registry is
supported only for migration purposes; it is not supported for normal execution.
If you have UDDI deployed in a clustered application server and you migrate to WebSphere
Application Server Version 6, you cannot run UDDI across the mixed version cluster. You can
continue to run the UDDI Registry on the server(s) that remain at Version 5 , but you cannot
run the UDDI Registry in the V6 servers until all nodes in the cluster have been migrated to
Version 6. This is because the UDDI data needs to be migrated from the UDDI V2 format to
the UDDI V3 format.
If you are migrating the UDDI Registry from a WebSphere Application Server Network
Deployment Version 5 configuration, or from a WebSphere Application Server Version 5
stand-alone application server, the steps are very similar. For a migration to a WebSphere
Application Server Network Deployment configuration, one suggested option is to perform
incremental migration such that you configure a mixed version cell. See 8.4, V5 Network
Deployment on page 140 for more information about configuring mixed version cells. In this
way, individual application servers may be migrated when convenient in a incremental
manner.
The considerations and number of steps to perform this migration are significant and it is best
to see the following WebSphere Application Server Version 6 InfoCenter article for more
information: Migrating to V3 of the UDDI Registry, found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.nd.doc
/info/ae/ae/twsu_migrate.html

8.8 Multi-broker migration

The implementation of the Data Replication Services has fundamentally changed in
WebSphere Application Server Version 6, and the V5 multi-broker configuration no longer
applies to the V6.0 runtime. The V5 multi-broker configuration can continue to be used for V5
nodes, and in fact is maintained by migration logic when the deployment manager is migrated
from V5.x to V6.0. However, after you upgrade your deployment manager to WebSphere
Application Server Version 6, you can only create new data replication domains. Any
multi-broker domains that you create with a previous version of WebSphere Application
Server are still functional; however, you cannot create new multi-broker domains or
replicators using WebSphere Application Server Version 6 administration tools.

146

WebSphere Application Server V6 Migration Guide

The different versions of application servers cannot communicate with each other. When
migrating your servers to the current version of WebSphere Application Server, keep at least
two application servers running on the previous version so that replication remains functional.
The considerations and number of steps to perform this migration are significant and it is best
to see the following WebSphere Application Server Version 6 InfoCenter article for more
information: Migrating V6.0 servers from multi-broker replication domains to data replication
domains, found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.nd.doc
/info/ae/ae/trun_drs_migrate.html

Chapter 8. Migration tasks

147

148

WebSphere Application Server V6 Migration Guide

Chapter 9.

Script compatibility
This chapter discusses administrative scripting compatibility issues.

Copyright IBM Corp. 2005. All rights reserved.

149

9.1 Introduction
Migration of wsadmin administration scripts that use JACL and Jpython from WebSphere
Application Server V5 to WebSphere Application Server V6.0 should be relatively
straightforward since there is a high degree of compatibility between versions. However,
there are a few noted exceptions that are discussed in detail in this chapter. Migration may
also be required as a result of changes to the scripting language itself since WebSphere
Application Server V6.0 uses a JACL 1.3.1 engine.
For administrative scripts using wscp and XMLConfig prior to WebSphere Application Server
5.0, it is recommended that all scripts be first migrated to wsadmin syntax. Please see 9.6,
Version 4 wscp migration on page 155 for information about wscp scripts.
Conceptually, the old scripts can operate under compatible support so that they continue to
function. Compatibility with the old scripts is achieved by automatic migration utilities in
WebSphere Application Server 6.0 that make the data locations and data objects that they
operate on WebSphere Application Server 5.0 compatible, so no changes would be required
to the scripts themselves. That is not to say that they are entirely forward compatible; there
might be cases which require direct modification to the scripts for things to continue working
smoothly. Scripts may also have to be modified at some later point in time to deal with
deprecated functionality and make use of the new way of performing that same function.

9.2 Compatibility of data location

In order to remain compatible with previous versions of scripts, WebSphere Application
Server 6.0 offers accessibility of data from multiple locations. The old V5 locations and the
new V6.0 locations are concurrently accessible. Dual location accessibility can be accessed
directly without the assistance of script compatibility support provided by the automatic
migration utilities. As long as the new location is not updated, the data is accessed from the
old location. Once the new location is updated, it becomes the current data and is used for
further accesses and updates. Warning messages are logged when the old location is still
being used.

9.2.1 Transaction logs

The location of the transaction log directory attribute has changed from the
ApplicationServer::TransactionService to the ServerEntry::recoveryLogs. As long as the new
location is not used, the value from the old location is used. Scripts that modify the old
location can still be used; that value takes effect until a value in the new location is set. This
example shows how to change the transaction log location.
JACL language example:
Old location:
set transService [$AdminConfig list TransactionService $server1]
$AdminConfig showAttribute $transService transactionLogDirectory

New location:
$AdminConfig list ServerEntry $node
set serverEntry <select one of the ServerEntry from output of above command>
set recoveryLog [$AdminConfig showAttribute $serverEntry recoveryLog]
$AdminConfig showAttribute $recoveryLog transactionLogDirectory

150

WebSphere Application Server V6 Migration Guide

9.3 Compatibility with new object types

Some configuration objects and configuration data for WebSphere Application Server V5 may
need to be migrated in such a way so that they continue to be compatible with the
WebSphere Application Server V5 wsadmin scripts. These changes are assisted by the
compatibility mode provided by WASPostUpgrade command. During migration, the default is to
migrate using the compatibility mode. If this option is taken, then the old object types are
migrated into the new configuration; all existing scripts do run unchanged.
See 7.6.4, Script compatibility on page 131 for more information about how to use script
compatibility.

9.3.1 HTTP transports

The new architecture for V6 uses the new channel framework. HTTP definitions are mapped
on top of this support. When the compatibility mode is chosen, the old HTTPTransport objects
are migrated and mapped onto the channel architecture. Existing scripts can modify these
objects and do run unchanged.
Here is an example of how to write this:
Jacl language example:
set server [$AdminConfig getid /Node:mynode/Server:myserv/]
set web_container [$AdminConfig list WebContainer $server]
$AdminConfig modify $web_container {{transports:HTTPTransport {{{sslEnabled true}
{sslConfig DefaultSSLSettings} {address {{host *} {port 9080}}}}}}}
$AdminConfig save

Jython language example:

server = AdminConfig.getid('/Node:mynode/Server:myserv/')
web_container = AdminConfig.list('WebContainer', server)
AdminConfig.modify(web_container, [['transports:HTTPTransport', [[['sslEnabled',
'true'], ['sslConfig', 'DefaultSSLSettings'], ['address', [['host', '*'], ['port',
9080]]]]]]])
AdminConfig.save()

9.3.2 Process definition

The name of the process definition object is changed from processDef to processDefs. You
can mitigate this change by using the compatibility mode mapping provided by the automatic
migration utilities. The change to scripts to use the new location is as follows:
JACL language example:
Old example:
set processDef [$AdminConfig list JavaProcessDef $server1]
set processDef [$AdminConfig showAttribute $server1 processDefinition]

New example:
set processDefs [$AdminConfig list JavaProcessDef $server1]
set processDefs [$AdminConfig showAttribute $server1 processDefinitions]

Jython language example:

Old example:
processDef = AdminConfig.list('JavaProcessDef', server1)
print processDef

Chapter 9. Script compatibility

151

 New example:
processDefs = AdminConfig.list('JavaProcessDef', server1)
print processDefs

9.4 Migrating from version 5 embedded messaging

WebSphere Application Server 6.0 introduces a new embedded JMS engine as part of the
new System Integration Bus model, the SIBJMS. Most scripts that confine themselves to
acting on JMS resources do not need to be changed immediately and should continue to
work unmodified with one noted exception. The exception is the V5 embedded messaging
that provides the DIRECT port for publish/subscribe messaging, as set on the topic
connection factory. If any Version 5 topic connection factory has the Port property set to
DIRECT, change it to QUEUED before use with the Version 6 default messaging provider.
It is important to separate the JMS providers and their JMS resources from the underlying
messaging system. The same script may deal with both JMS resources and the JMS server.
However, concepts can be better discussed with this separation of concerns. This chapter
deals only with changes to administration scripts for V5 embedded messaging system. The
migration situation for WebSphere MQ as the external messaging system or third-party
external messaging system is beyond the scope of this chapter.
When using the automatic migration utilities provided with WebSphere Application Server 6.0,
almost everything is copied and continues to work without changes to the application, the
runtime and the associated administrative scripts. The automatic migration utilities take the
Version 5 application server and migrate it to a Version 6 application server with the same
name. This server is added as a member of a service integration bus that is named for the
node on which the server is located. A messaging engine is created automatically on that bus
for the application server. A default WebSphere MQ client link, called Default.MQClientLink, is
created automatically for the node and assigned to the messaging engine for the application
server. For each JMS queue defined on the Version 5 server, the automatic migration utilities
create a new bus queue with the same name as the Version 5 JMS queue, and create a
message point assigned to the messaging engine. Messages sent to the JMS queues are
stored and processed at the message point. After migrating the node, the basic single-node
scenario becomes:
1. The JMS application can continue to access the Version 5 JMS resources, which are now
managed as V5 default messaging JMS resources implemented by the WebSphere
Application Server Version 6 default messaging provider.
2. The JMS application communicates with the Version 5 JMS resources through the
WebSphere MQ client link and the messaging engine. This is invisible to the JMS
application.
3. The JMS resources, a JMS queue connection factory, and a JMS queue, are managed as
Version 5 default messaging JMS resources.
4. The new bus queue is managed as a resource of the service integration bus. Messages
for JMS Q (V5) are stored and processed by the message point for the associated bus
destination.
5. The WebSphere MQ client link presents itself as a queue manager and transforms
between the WebSphere MQ client protocols used by Version 5 JMS applications and the
WebSphere Application Server Version 6 protocols used by messaging engines. The MQ
client link provides a Version 5 emulation mode within the Version 6 SI Bus framework.

152

WebSphere Application Server V6 Migration Guide

9.4.1 Migration of scripts to SIB JMS

In general, it is recommended to replace the Version 5 default messaging JMS resources with
equivalent Version 6 default messaging provider JMS resources as soon as it is conveniently
possible (after all JMS applications using those resources have been moved onto
WebSphere Application Server Version 6). You should define any new JMS resources as
Version 6 resources, for example WASQueue should become SIBJMSQueue. Note that V5
requires scripts to locate the correct JMS provider, but the V6 commands hide this. In V5, the
scripts use AdminConfig to directly manipulate objects. The SIBJMS objects are not intended
for direct access but rather for access via $AdminTask commands.
For example:
$AdminConfig create WASQueue

becomes
$AdminTask createSIBJMSQueue

In most cases, the changes to the script will be more than a minor syntactic update since
there is no direct mapping between the attributes of these objects. See this InfoCenter article
to figure out how to achieve equivalent function: AdminTask object for scripted administration,
found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.nd.doc
/info/ae/ae/cxml_admintask.html

Version 5.0 JMS applications accessed JMS resources through a JMS Server, which acted as
one or more queue managers. The WebSphere Application Server Version 6 default
messaging provider uses fully integrated message bus and therefor needs no JMS server. In
this case, we configure the Service Integration Bus to replace the logical JMS server. Note
that not every bus emulates the V5 embedded messaging system but rather that it relies on
specific configuration of the MQClientLink and on a particular naming convention for bus
destinations.
In considering the changes that are required to migrate the scripts, the following two steps are
recommended.
1. All scripts need to be modified to test for the existence of the default SI Bus and create
one if necessary. One cannot assume there is always an SI Bus present, as you could
formerly assume that there was a JMS server present.
If you use the automatic migration utilities, then the SI Bus is created automatically. On a
stand-alone node, the JMS server runs as the jmsserver service of an application server. If
you migrate a WebSphere Application Server Version 5 stand-alone node to Version 6, the
Version 5 application server is migrated to a Version 6 application server with the same
name. The server is added as a member of a service integration bus that is named for the
node on which the server is located. A messaging engine is created automatically on that
bus for the application server. In a deployment manager cell, each managed node has at
most one JMS server. If you migrate a WebSphere Application Server Version 5 managed
node to Version 6, the JMS server is migrated to an application server, called jmsserver,
and added as a member of a service integration bus that has the same name as the node.
A messaging engine is created automatically on that bus for the application server. There
is only one such application server and bus for each Version 5 node. For each JMS queue
defined on the JMS server, the automatic migration utilities create a new bus queue with
the same name as the Version 5 JMS queue, and then create a message point assigned
to the messaging engine. Messages sent to the JMS queues are stored and processed at
the message point.

Chapter 9. Script compatibility

153

2. Scripts accessing the JMS server need to be changed. All scripts that modify the V5 JMS
Server queue lists need to be changed to transform queue lists to SI Bus destinations both
for a post-migration bus or any other bus that you create.
The automatic migration utilities do not migrate the data on WebSphere Application Server
Version 5 queues. Any messages and knowledge of durable subscriptions held by the JMS
server should be consumed before migrating the node to WebSphere Application Server
Version 6. If it is not possible to have the application consume the messages, the only
alternative is to write an application to run on a Version 6.0 server. This application needs to
access the Version 5 JMS server, get the Version 5 messages, and resend them to
applications on WebSphere Application Server V6.0.

9.4.2 Wildcard syntax conversion

Existing WebSphere Application Server Version 5 client applications using the Version 5
connection factory and destination definitions use the WebSphere MQ Integrator wildcard
convention. Such applications can connect to the default messaging provider and service
integration bus, and automatically have their wildcard syntax mapped to the XPath
convention when subscriptions are created. Any display of these subscriptions through a
Version 6 administrative interface shows the XPath syntax.

9.4.3 Replacing MDB listener ports with JMS activation specifications

A JMS application that uses a message-driven bean and its listener port in WebSphere
Application Server Version 5 can continue to use the listener port without change in
WebSphere Application Server Version 5. However, the message listener service uses the
Application Server Facilities (ASF), which are an optional part of the JMS specification. Also,
ASF is not supported by the service integration technologies on which the Version 6 default
messaging provider is implemented.
The Version 6 default messaging provider is implemented as a Java Connection Architecture
(JCA) resource adapter, for which inbound connectivity is configured as an activation
specification.
Therefore, as soon as is conveniently possible, you should replace any listener port with a
JMS activation specification for use by MDB applications with the Version 6 default
messaging provider.
If you used the listener port retry count in WebSphere Application Server Version 5, there is
one extra consideration. The Java Connection Architecture has no concept of a listener port
retry count, so this is not supported by the Version 6 default messaging provider. This should
not present a problem because the Version 6 default messaging provides destinations with a
Maximum failed deliveries setting. This defines the maximum number of times that the
service tries to deliver a message to the destination before forwarding it to the exception
destination. Although applications do not need to be changed, any wsadmin or JMX scripts
that make use of the listener port retry count need to be changed to make use of the
Maximum failed deliveries setting for use in WebSphere Application Server Version 6.

9.5 Jacl 1.2.6 and Jacl 1.3.1 differences

A new version of Jacl (1.3.1) is shipped with WebSphere Application Server Version 6. With
this Jacl version, the regexp command supports only tcl 8.0 regexp command syntax. If your
existing V5.x Jacl script uses the regexp command syntax that is supported in Jacl 1.2.6 but

154

WebSphere Application Server V6 Migration Guide

not in Jacl 1.3.1, you may not get a match, or you may get a compile error for your regexp
command similar to the following:
com.ibm.bsf.BSFException: error while eval'ing Jacl expression:
couldn't compile regular expression pattern: ?+* follows nothing
while executing
"regexp {(?x)
..."
("if" test expression)
invoked from within
"if {[regexp {(?x)
..."
(file testregexp.jacl line 2)
(file line 2)
invoked from within
"source testregexp.jacl"

There is no workaround for this regression problem. The Jacl developers have indicated that
this is by design and there is no simple patch to fix this design decision.

9.6 Version 4 wscp migration

This section discusses migrating V4 wscp scripts to the V6 wsadmin scripting language.
For the most up-to-date information about migrating wscp scripts, consult the InfoCenter
article Migrating V4.0.x administrative scripts to V6 wsadmin, found at:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.nd.doc
/info/ae/ae/txml_migrate4to6.html

9.6.1 Migration steps

Migration of scripts based on the earlier versions of WebSphere to wsadmin is necessary
since the elements involved are very different. For similar reasons, automation would not
work very well either. The good news is that wsadmin can do all that wscp and xmlConfig did,
and more. The following steps help to streamline migration of scripts further:
1. Isolate the wscp or XMLConfig commands in your scripts.
2. Separate them into configuration and operational commands.
This paves the way for better understanding of the wsadmin commands, since in
WebSphere V6, there is a very clear distinction between runtime and configuration
objects.
Configuration commands include:

Create, modify, show, showAll, install, uninstall, list, remove

CreateClone, removeClone
All security configuration
All security role assignments

Operational commands include:

start, stop, show, testConnection
All DrAdmin commands
regenPluginCfg
3. Identify corresponding configuration objects in WebSphere V6, as listed in Table 9-1 on
page 156.

Chapter 9. Script compatibility

155

Table 9-1 Corresponding configuration objects in WebSphere V6.0

wscp 4.0 command

wsadmin 6 configuration type

ApplicationServer

Server

Context

Not applicable

DataSource

WAS40DataSource, DataSource

Domain

Not applicable

EnterpriseApp

ApplicationDeployment; also, use

AdminApp

GenericServer

Server

J2CConnectionFactory

J2CConectionFactory

J2CResourceAdapter

J2CResourceAdapter

JDBCDriver

JDBCProvider

JMSConnectionFactory

JMSConnectionFactory

JMSDestination

JMSDestination

JMSProvider

JMSProvider

MailSession

MailSession

Module

ModuleDeployment; also, use AdminApp

Node

Node

ServerGroup

ServerCluster

URL

URL

URLProvider

URLProvider

VirtualHost

VirtualHost

4. Identify wsadmin attribute names.

Attribute names have changed in wsadmin from the previous versions. These, however,
are easy to map using the help functions. Get a list of the attributes that are used in the
scripts and map them to the new names.
5. Convert application install commands.
Use AdminApp installInteractive to complete one install. Then you can use the
wsadmin.traceout log file to construct an install command for your script. The message
WASX7278I points to all the data.
6. Convert operational commands.
Use the information in 9.6.2, Migration from V4.0 to V6 on page 156 for specific version
mappings. A number of common tasks have been provided as examples. These should
help in finding the right operation map.

9.6.2 Migration from V4.0 to V6

Migrating scripts from V4 to V6 involves translating the script syntax to a new object
command structure. The command interpreter has been renamed.

156

WebSphere Application Server V6 Migration Guide

wscp
The wscp tool is invoked using the wscp.bat or wscp.sh program. You can specific the -f
option to run a script file, or the -c option to run a command. If you specify neither, an
interactive shell appears.
The operation of wscp is affected by a .wscprc properties file that is placed in the user's home
directory. There is no default properties file shipped with the product. An alternate properties
file may be specified on the command line by using the -p option.

wsadmin
The wsadmin tool is invoked using the wsadmin.bat or wsadmin.sh program. You can specific
the -f option to run a script file, or the -c option to run a command. If you specify neither, an
interactive shell appears. Multiple -c commands may be specified on the command line, and
there are additional options that may be specified. For more details, please refer to the
InfoCenter.
Table 9-2 Mapping of wscp 4.0 to wsadmin 6.0
wscp 4.0

wsadmin 6.0

action

Object and
command

Mbean, if any

Operation, if any

server start

AdminControl
startServer

server stop

AdminControl
stopServer

servergroup start

AdminControl
invoke

Cluster

start

servergroup stop

AdminControl
invoke

Cluster

stop

application start

AdminControl
invoke

ApplicationManager

startApplication

application stop

AdminControl
invoke

ApplicationManager

stopApplication

node stop

AdminControl
invoke

NodeAgent

stop

check runtime
attributes

For state, see if

MBean is running;
for others,
AdminControl
getAttribute

<any mbean>

<attributeName>

regenPluginCfg

AdminControl
invoke

PluginCfgGenerator

generate

testConnection

AdminControl
testConnection

DataSource

Chapter 9. Script compatibility

157

wscp 4.0

wsadmin 6.0

enable security

security on
command in
securityProcs.jacl

disable security

securityoff
command in
securityProcs.jacl

Task-based scenarios
This section provides examples of wscp-to-wsadmin migration.

Server administration
Start an application server:
wscp 4.0
ApplicationServer start
/Node:mynode/ApplicationServer:myserv/

wsadmin V6
This command only makes sense in a Network Deployment installation. In a Base
installation, if you are connected to a server, you are connected to the only server and
you cannot request that another be started. But in a Network Deployment installation,
you can use:
$AdminControl startServer myserv mynode

If mynode is the node the client is connected to, the node name may be omitted:
$AdminControl startServer myserv

Stop an application server:

This is an operational command. wscp 4.0 requires that you know the hierarchical name of
the application server in question: the node name and server name. You need the same
information in V6, and you also need to understand that what you are stopping is an object
called a Server, not an ApplicationServer. Servers represent logical processes on many
platforms (for example, Windows and AIX) and are the entities that are stopped and
started. ApplicationServers are contained within Servers.
wscp 4.0
ApplicationServer stop
{/Node:mynode/ApplicationServer:Default Server/}

wsadmin V6
There is more than one way to stop a server using wsadmin. The simplest method is
by using the stopServer command on the AdminControl object:
$AdminControl stopServer server1 mynode

If mynode is the node the client is connected to, the node name may be omitted:
$AdminControl stopServer server1

Create a new application server:

This is a configuration command. wscp 4.0 requires that you know the hierarchical name
of the application server in question: the node name and server name. You need the same

158

WebSphere Application Server V6 Migration Guide

information in V6, and you also need to understand that what you are creating is an object
called a Server, not an ApplicationServer.
wscp 4.0
ApplicationServer create
/Node:mynode/ApplicationServer:myserv/ -attribute
{{Stdout myfile.out}}

wsadmin V6
This can be done using a single command in wsadmin, but it is clearer to show it using
two. Server objects are contained within nodes. The 4.0 ApplicationServer attribute
called Stdout is replaced by the fileName attribute embedded within the
outputStreamRedirect attribute of the Server.
wsadmin>set node [$AdminConfig getid
/Node:mynode/]
wsadmin>$AdminConfig create Server $node {{name myserv} {outputStreamRedirect
{{fileName myfile.out}}}}]
wsadmin>$AdminConfig save

Remove an application server:

This is a configuration command.
wscp 4.0
ApplicationServer remove /Node:mynode/ApplicationServer:myserv/

wsadmin V6
This can be done with a single command in wsadmin, but it is clearer to show it using
two.
wsadmin>set serv [$AdminConfig getid
/Node:mynode/Server:myserv/]
wsadmin>$AdminConfig remove $serv
wsadmin>$AdminConfig save

Connect to remote server:

wscp 4.0
Set the wscp.host name in the default.wscprc file:
wscp.hostname = myhost

wsadmin V6
Launch the scripting program by passing in the host parameter:
wsadmin -host myhost.austin.ibm.com

Application management
Enterprise Application - install:
In 4.0, wscp scripts used the EnterpriseApp and Module commands to install and uninstall
applications. WebSphere V6 wsadmin scripts use the AdminApp command to perform
similar configuration actions.
wscp 4.0
The EnterpriseApp install command has a complex syntax, so we build up some
pieces of the command beforehand:

construct -modvirtualhosts option

wscp> set modhost1 [list mtcomps.war default_host]
wscp> set modhosts [list $modhost1]
Chapter 9. Script compatibility

159

construct -resourcereferences option

wscp> set resref1 [list mtcomps.war::mail/MailSession9 mail/DefaultMailSession]
wscp> set resref2 [list deplmtest.jar::MailEJBObject::mail/MailSession9
mail/DefaultMailSession]
wscp> set resrefs [list $resref1 $resref2]

invoke install
wscp> EnterpriseApp install /Node:mynode/
c:/WebSphere/AppServer/installableApps/jmsample.ear -appname MailSampleApp
-defappserver /Node:$mynode/ApplicationServer:myserv/ -modvirtualhosts $modhosts
-resourcereferences $resrefs

wsadmin V6
As with 4.0, the application install commands can have a very involved syntax. The
command sequence given below accomplishes approximately the same thing as the
4.0 commands above, but there are simpler ways to do this.

construct -MapWebModToVH option

wsadmin> set modtovh1 [list "JavaMail Sample WebApp" mtcomps.war,WEB-INF/web.xml
default_host]
wsadmin> set modtovh [list $modtovh1]

construct -MapResRefToEJB option

wsadmin> set resreftoejb1 [list deplmtest.jar MailEJBObject
deplmtest.jar,META-INF/ejb-jar.xml mail/MailSession9 javax.mail.Session
mail/DefaultMailSession]
wsadmin> set resreftoejb2 [list "JavaMail Sample WebApp" ""
mtcomps.war,WEB-INF/web.xml mail/MailSession9 javax.mail.Session mail/bozo]
wsadmin> set resreftoejb [list $resreftoejb1 $resreftoejb2]

Construct attribute string

wsadmin> set attrs [list -MapWebModToVH $modtovh -MapResRefToEJB $resreftoejb
-node mynode -server myserv -appname MailSampleApp]
#
invoke install
wsadmin> $AdminApp install c:/WebSphere/AppServer/installableApps/jmsample.ear
$attrs

Install default/standard applications

The standard EAR files that ship with the product can be installed (in the federation
of the node into a cell, where the apps have to be installed specifically) as follows:
$AdminApp install
\"c:/<WAS_HOME>/samples/lib/TechnologySamples/TechnologySamples.ear\" {-appname
TechnologySamples -cell node1Network -node node1 -usedefaultbindings"

The Help utility can be used to get more information for the above commands. In this case,
there are other commands that offer more information about the options. The AdminApp,
taskInfo and options commands are particular helpful in listing all the options and
information about them. You can also use the AdminApp installInteractive command (with the
same options as the install command) to be prompted for each option and step through the

160

WebSphere Application Server V6 Migration Guide

install, setting your values. This command with all its options is logged in the
wsadmin.traceout file in the logs directory, under message WASX7278I.
Enterprise Application - uninstall:
wscp 4.0
wscp> EnterpriseApp remove {/EnterpriseApp:Sample Application/}

wsadmin V6
wsadmin> $AdminApp uninstall TechnologySamples

Enterprise Application - edit:

wscp 4.0
wscp> EnterpriseApp modify {/EnterpriseApp:Trade Sample/} -attribute {{Name
changedName}}

wsadmin V6
wsadmin> $AdminApp edit DefaultApplication {-BindJndiForEJBNonMessageBinding
{{"Increment Enterprise Java Bean" "Increment" "Increment.jar,META-INF/ejb-jar.xml"
"Increment1"}}}

While testing, it is easier to use editInteractive and get a list of the options and the
variables that can be changed. Then use those with the edit command in your scripts. In the
above command, -BindJndiForEJBNonMessageBinding is the option we are using to change
the JNDI name of the ejb Increment, with the URI Increment.jar,META-INF/ejb.jar.xml.

Administration of runtime objects: query, change

This change is temporary and reverts back to the old setting in the event of server stoppage.
To permanently change it, the configured object has to be changed. However, this setting can
be used to get trace outputs.
wsadmin> set trace [lindex [$AdminControl queryNames type=TraceService,*],0]
wsadmin> $AdminControl setAttribute $trace traceSpecification com.ibm.*=all=enabled

Administration of configured objects

Modifying attributes of application servers, enterprise applications, and other configured
objects:
wscp 4.0
wscp> ApplicationServer modify /Node:dev-pc/ApplicationServer:myServer/ \
-attribute {{PingInterval 120}}

wsadmin V6
wsadmin> set trace [$AdminConfig getid /TraceServer:/
wsadmin> $AdminConfig modify trace
{{startupTraceSpecification=com.ibm.ws.*=all=enabled}}
wsadmin> $AdminConfig save

The change in the configuration is seen only when the server is restarted.
If you made changes and do not want to save them, then you can call the reset
command:
wsadmin> $AdminConfig reset

There are some other useful commands, such as:

wsadmin> $AdminConfig hasChanges -

This can be invoked before a save to check for changes to the configuration.

Chapter 9. Script compatibility

161

wsadmin> $AdminConfig setSaveMode rollbackOnConflict -

This is called to set the save mode.

Refer to the InfoCenter for more details about these commands.
List the configured server groups:
This is a configuration command in V6.
wscp 4.0
ServerGroup list

You could put the result of this command into a Jacl list and invoke other operations
such as show or modify on the members of the list.
wsadmin V6
Again, in V6 there are server clusters instead of server groups.
$AdminConfig list ServerCluster

Again, you can put the result of this command into a Jacl list and invoke other config
commands such as show or modify on the members of the list. In order to invoke
operational commands such as stop, you need to do a little more work:

Get the config ID of the cluster of interest:

set myclust [$AdminConfig getid /ServerCluster:mycluster/]

The name returned can be used to get the ObjectName of the running Cluster
MBean:
set runningCluster = [$AdminConfig getObjectName $myclust]

At this point, runningCluster has the object name for the running instance of the
ServerCluster (or it is empty if it is not running). This object name can be used for
control purposes:
$AdminControl invoke $runningCluster stop

Display help:
wscp 4.0
To obtain general help:
wscp> help

To obtain help on a particular object:

wscp> object_type help

or:
wscp> ApplicationServer help

wsadmin V6
Displaying general help is done using the $Help object:
wsadmin>$Help help

This lists all the options available. In general, attributes and operations when passing
in an Mbean are the most useful. To get the Mbean associated, you have to use the
following command:
wsadmin>$AdminControl queryNames type=Server,*

162

WebSphere Application Server V6 Migration Guide

 List actions available on configured objects:

wscp 4.0
Here, with any object, you can get help by specifying:
"<objName>

help operations"

wscp> ApplicationServer help operations

wsadmin V6
Since we are dealing with configured objects here, the wsadmin object to be used is
AdminConfig.
$AdminConfig attributes Server

Cluster administration
Create a server group:
WebSphere 4.0 server groups are no more; we now have server clusters in their place.
The members of a cluster are not clones so much as they are servers with identical
application configurations.
wscp 4.0
This example assumes that there already exists an application server named as1 that
is to be used as the first clone in a server group.
wscp>ServerGroup create /ServerGroup:sg1/ -baseInstance
/Node:mynode/ApplicationServer:as1/
-serverGroupAttrs {{EJBServerAttributes
{{SelectionPolicy roundrobin}}}}

wsadmin V6
wsadmin>set serverid [$AdminConfig getid /Node:mynode/Server:as1/]
wsadmin>$AdminConfig convertToCluster $serverid MyCluster

Clone a ServerGroup:
wscp 4.0
wscp>ServerGroup clone /ServerGroup:sg1/ -cloneAttrs
{{Name newServer}} -node /Node:mynode/

wsadmin V6
The following three commands could be combined into a single nested command, but
it is more clear to show them as three separate commands. The first gets the cluster
ID, the second gets the node ID, and the last command creates a new member of an
existing cluster.
wsadmin>set mycluster [$AdminConfig getid
/ServerCluster:mycluster/]
wsadmin>set mynode [$AdminConfig getid
/Node:mynode/]
wsadmin>$AdminConfig createClusterMember $mycluster
$mynode {{memberName newServer}}

Start a ServerGroup:
This is an operational command.
wscp 4.0
ServerGroup start /ServerGroup:cluster1/

Chapter 9. Script compatibility

163

 wsadmin V6
Again, these two commands could be combined into one. We look up the Cluster
MBean, then invoke start on it:
wsadmin>set cl1 [$AdminControl completeObjectName type=Cluster,name=cluster1,*]
wsadmin>$AdminControl invoke $cl1 start

It is possible that there is no running MBean for cluster1 if the cluster has not been
loaded first. If this is the case, use the ClusterMgr MBean to retrieve the cluster:
wsadmin>set clustermgr [$AdminControl
completeObjectName type=ClusterMgr,*]
wsadmin>$AdminControl invoke $clustermgr
retrieveCluster cluster1

Stop a ServerGroup:
This is an operational command.
wscp 4.0
wscp>ServerGroup stop /ServerGroup:cluster1/

wsadmin V6
Again, these two commands could be combined into one. We look up the Cluster
MBean, then invoke start on it:
wsadmin>set cl1 [$AdminControl completeObjectName type=Cluster,name=cluster1,*]
wsadmin>$AdminControl invoke $cl1 stop

Remove a clone:
There is no command for removing a server from a cluster once it has been added. You
must delete the server.

Other tasks
Set the Trace specification:
wscp 4.0
wscp> DrAdmin remote <portno> -setTrace com.ibm.ejs.*=all=enabled

wsadmin V6
There are two ways to set tracing with wsadmin in WebSphere V6. One takes
immediate effect, but is temporary and is set on the runtime, using AdminControl.
wsadmin> set ts [$AdminControl queryNames
type=TraceService,node=<nodeName>,process=<serverName>,*]
wsadmin> $AdminControl setAttribute $ts traceSpecification com.ibm.*=all=enabled

However, if you want your change to persist, then you should change the configuration
by using AdminConfig.
wsadmin> set svr [$AdminConfig getid /Node:<nodeName>/Server:<serverName>/]
wsadmin> set ts [$AdminConfig list TraceService $svr]
wsadmin> $AdminConfig modify $ts {{startupTraceSpecification com.ibm.*=all=enabled}}

There is also a way to change the TraceLog specifications:

wsadmin> set svr [$AdminConfig getid /Node:<nodeName>/Server:<serverName>/]
wsadmin> set ts [$AdminConfig list TraceService $svr]
wsadmin> set trlog [$AdminConfig list TraceLog $ts]

164

WebSphere Application Server V6 Migration Guide

wsadmin> $AdminConfig modify $trlog {{fileName myFile.log} {maxNumberOfBackupFiles

10} {rolloverSize 2}}

Enable security:
wscp 4.0
wscp>SecurityConfig setAuthenticationMechanism LOCALOS -userid {me secret}
wscp>SecurityConfig enableSecurity

wsadmin V6
V6 ships a profile that is referenced in the default wsadmin.properties file so that it runs
by default. This is securityProcs.jacl, and it implements various security configuration
functions. As of this writing, it only supports two functions: securityon and securityoff.
securityon [user [password]]

This turns on local security. If a user name is supplied, it is set in the security config. If
both a user name and password are supplied, the securityon function checks the
validity of the user/password combination, and fails the function if the combination is
not valid.
So the equivalent V6 command is:
securityon userName pwd

Disable local OS security:

wscp 4.0
SecurityConfig disableSecurity

wsadmin V6
V6 ships a profile that is referenced in the default wsadmin.properties file so that it runs
by default. This is securityProcs.jacl, and it implements various security configuration
functions. It only supports two functions: securityon and securityoff.
securityoff

Install JDBCDrivers:
wscp 4.0
wscp>JDBCDriver create /JDBCDriver:mydriver/ -attribute {{ImplClass
COM.ibm.db2.jdbc.DB2ConnectionPoolDataSource}}
wscp>JDBCDriver install /JDBCDriver:mydriver/ -node /Node:mynode/ -jarFile
c:/SQLLIB/java/db2java.zip

wsadmin V6
There is no separate install step in WebSphere V6. The JAR file name required in the
V4.0 install step is replaced by the classpath attribute on the V6 JDBCProvider object.
In WebSphere V6, resources can exist at the server, node, or cell level of the
configuration. The V6 equivalent of providing the node in the 4.0 JDBCDriver install
command is that we create our V6 JDBCProvider at the node level.
wsadmin>set node [$AdminConfig getid /Node:mynode/]
wsadmin>$AdminConfig create JDBCProvider $node {{classpath
c:/SQLLIB/java/db2java.zip} {implementationClassName
COM.ibm.db2.jdbc.DB2ConnectionPoolDataSource} {name
mydriver}}

Chapter 9. Script compatibility

165

 Ping node and AppServers for current status:

wscp 4.0
The point of this task is generally to determine if a given server is running:
wscp>set servers [ApplicationServer list]
wscp>foreach server $servers {
set result ApplicationServer show $server -attribute
{CurrentState}
puts "state for server $server: $result"
}

wsadmin V6
This task is a little more involved in WebSphere V6 because configuration and control
commands are separated. When we get a list of all the servers in the first statement of
the code shown below, we are getting a list of all the servers defined in the
configuration. This is just configuration data; we cannot interrogate the configuration
data to find out what servers are running, because the config data only contains
configuration information. The running state of a server is not configuration information.
So for each server defined, we ask for the ObjectName of any running instance of the
server. If the server is not running, nothing is returned from the getObjectName
command on the AdminConfig object. If the server is running, we ask for its state
attribute. This may appear superfluous; if the Mbean is there, the server is running
and the state should be STARTED. It is possible, however, for the state to be something
other than STARTED, for example, STOPPING.
set servers [$AdminConfig list Server]
foreach server $servers {
set objName [$AdminConfig getObjectName $server]
if {[llength $objName] == 0} {
puts "server $server is not running"
} else {
set result [$AdminControl getAttribute $objName state]
puts "state for server $server: $result"
}
}

Test connections to data sources:

WebSphere 4.0 introduced a means for testing the connection to a DataSource object;
this function is available in WebSphere V6 as well.
wscp 4.0
wscp>set myds /JDBCDriver:mydriver/DataSource:myds/
wscp>DataSource testConnection $myds

wsadmin V6
In WebSphere V6, the testConnection command is part of the AdminControl object,
because it is an operational command. But this particular operational command takes
a configuration ID as an argument, so we invoke the getid command on the
AdminConfig object to get it:
wsadmin>set myds [$AdminConfig getid /JDBCProvider:mydriver/DataSource:myds/]
wsadmin>$AdminControl testConnection $myds

In many cases, a user ID and password (or other properties) are required to complete
the test connection. If this is the case, you get message WASX7216E describing the
missing properties:
WASX7216E: 2 attributes required for testConnection are missing: "[user, password]"
To complete this operation, please supply the missing attributes as an option,
following this example: {{user user_val} {password password_val}}

166

WebSphere Application Server V6 Migration Guide

In this case, you will need to issue the commands as follows:

set myds [$AdminConfig getid /JDBCProvider:mydriver/DataSource:myds/]
$AdminControl testConnection $myds {{user myuser} {password secret}}

Regenerate the plug-in configuration:

wscp 4.0
wscp> Node regenPluginCfg /Node:myNode/

wsadmin V6
wsadmin>set cfg [$AdminControl queryNames type=PluginCfgGenerator,*]
wsadmin>$AdminControl invoke $cfg generate "C:/was50/WebSphere/AppServer
C:/was50/WebSphere/AppServer/config node1Network node1 server1 genPlugin.txt"

Chapter 9. Script compatibility

167

168

WebSphere Application Server V6 Migration Guide

10

Chapter 10.

Runtime application migration

examples
This chapter show examples of migrating applications and server configurations.

Copyright IBM Corp. 2005. All rights reserved.

169

10.1 Overview of migration examples

The migration examples shown in this chapter are simple examples that are intended to
illustrate the detailed steps of moving existing applications, application resources, and the
server environment settings to a V6 WebSphere installation.
The applications are simple examples that either are used in our internal education classes or
ship with the WebSphere system. The application design is not important in itself. However,
we wish to show how data sources and JMS sources are migrated. We chose a simple EJB
banking application that also uses an MDB interface. For the cases where the starting
configuration is V4, we chose the same application but without the MDB interface. We do not
show the details of configuring the database back end of the data source since database
configuration is not germane to this book. We also do not show the detailed operation of the
sample application at the end of the exercise because the application operation details are
not important. However, we did test the application at the end of the exercise to prove that the
procedure was correct. The starting point is a working application on a source environment.
The ending point is a working application on a target environment running on WebSphere V6.
Four of the five examples illustrate the use of the automatic migration utilities discussed in
7.6, Automatic migration utilities on page 121. These examples show the detailed use of the
automatic migration utilities and then examine the migrated artifacts on the target V6
environment.
The fifth example shows a case of manual migration. The automatic migration utilities are not
used. Instead, the detailed steps of installing and configuring the application using the
administrative console are shown.
These are the examples.
1. Automatic migration: V4 AE Single Server to V6 Application Server
This example starts with the J2EE 1.2 application consisting of a Web module and a EJB
1.1 module installed on V4 AE Single Server. The automatic migration utilities migrate the
application and resources to a stand-alone Application Server.
2. Automatic migration: V5 Application Server to V6 Application Server Express
This example starts with the J2EE 1.3 application consisting of a Web module and an EJB
2.0 module installed on V5.1 Application Server. The automatic migration utilities migrate
the application and resources to a stand-alone Application Server. A IBM HTTP Server V6
is installed and configured.
3. Automatic migration: V4 AE Clustered Server Group to V6 Network Deployment Cell
This example starts with a J2EE 1.2 application installed on a server group in V4 AE. The
automatic migration utilities migrate the application and resources to group of V6
stand-alone application servers. The servers are added to a V6 Network Deployment cell
and the servers are configured in a cluster.
4. Automatic migration: V5 Network Deployment Cell to V6 Network Deployment Cell
This example starts with a J2EE 1.3 application installed on a V5 Network Deployment cell
containing clustered servers. The automatic migration utilities migrate the application and
resources to V6 cell. The deployment manager and server nodes are migrated in a staged
sequence illustrating the concept of mixed version cells.

170

WebSphere Application Server V6 Migration Guide

5. Manual Migration: Installing J2EE 1.3 Enterprise Application on V6 Application Server

This example starts with a V6 stand-alone application server. The J2EE 1.3 application is
installed and the data source and JMS resources are configured manually using the
administrative console.
The examples in this chapter are based on the Windows operating system., Other operating
systems have small variations in some terminology. If you are using an operating system
other than Windows, you may need to make adjustments in the following terminology:
File system path names have a different syntax
Script names use a different suffix
The profile creation wizard has a different name for each platform

10.2 Automatic migration: V4 AE Single Server to V6

This example shows how to use the migration utilities to migrate WebSphere Application
Server Advanced Edition Single Server to a WebSphere Application Server V6 environment.
We tested V4.0.1, but any V4 fix level should work. The application we used to illustrate the
migration techniques is a J2EE 1.2 application we call MyBank. The application is a very
simple simulation of a banking application. The EJB module contains a CMP bean and a
session bean. The CMP bean uses a data source which points to a database of a single
table. The database is implemented on IBM DB2 Version 8.1.

Preparing your existing environment for migration

You should perform any application backups before performing a migration of your existing
environment. The migration utilities simply make a copy of the key files on the existing
system. There are no changes made on the source configuration, and therefore, there is no
explicit reason that the source configuration would be modified in any way. However, it is
always good practice to backup a working configuration before undertaking any major event.

Reviewing application and resources on your existing environment

The particular operation of the application is not important to this exercise. However, it is
useful to show the application and resources that we intend to test.
Figure 10-1 shows the administrative console and the MyBank application.

Figure 10-1 Version 4 applications

Figure 10-2 on page 172 shows the JDBC Provider that MyBank uses, and Figure 10-3 on
page 172 shows the data source.
Chapter 10. Runtime application migration examples

171

Figure 10-2 Version 4 JDBC drivers

Figure 10-3 Version 4 data source

Preparing the V6 installation

You will need to install and configure WebSphere V6 according to the instructions found
online at this article:
ftp://ftp.software.ibm.com/software/eod/WAS_6-0/Install_Migration/index.html

When you create the V6 profile, you have the flexibility to specify any node name or cell name
that you desire. Neither the cell name or the node name is crucial in making this exercise
work. The node name and cell names are important in the other exercises that we discuss in
this chapter. The important name to record is the profile name because this profile name will
be specified in the steps involving the auto-migration utilities.

Running automatic migration utilities

For this migration exercise, we are illustrating migrating such that Version 4 and Version 6 do
not reside on the same system. This is possible because the installation media contains a
WASPreUpgrade command that can be run directly from the installation media without first
installing WebSphere V6. In the following example, we have the installation media mounted
as drive H: and execute the command from this drive.

172

WebSphere Application Server V6 Migration Guide

set WAS_BIN=h:\migration\bin
%WAS_BIN%\WASPreUpgrade.bat G:\BACKUPS\brewski_AESV4 G:\WebSphereV4\AppServer

After running the WASPreUpgrade command, you should check its status by consulting the
output log which will be located in the backup directory. The example below shows the last
few lines of the log which indicates successful completion.
File - G:\BACKUPS\brewski_AESV4\ WASPreUpgrade.Mon-Oct-11-10.01.35-2004.log
deleted lines for brevity
MIGR0303I: The existing WebSphere Application Server environment is saved.
MIGR0420I: The first step of migration completed successfully.

The WASPreUpgrade command created the G:\BACKUPS\brewski_AESV4 directory as its

output. Transfer the contents of this directory to the second system where WebSphere V6 is
installed. The means of transfer is not important. We happened to use the technique of
zipping the directory, then transferred the zip file via FTP, and finally unzipped to a directory
called E:\BACKUPS\brewski_AESV4.
Once this backup directory has been transferred, run the WASPreUpgrade command using the
directory as input, and the V6 profile as a container for the output. The following example
shows the commands. The WASPostUpgrade command is run from the V6 installation directory.
call e:\WASv6\bin\setupCmdline.bat
set WAS_BIN=%WAS_HOME%\bin
set BACKUPDIR=E:\BACKUPS\brewski_AESV4
set PROFILE=olepaint_v4_mig
%WAS_BIN%\WASPostUpgrade %BACKUPDIR% -profileName %PROFILE%

After the WASPostUpgrade command completes, you should review the output log for errors or
warnings. The following examples shows an example warning message. Since this warning
pertains to the JDBC driver for the application data source we are migrating, we show later
that we do indeed heed the warning and change the classpath as suggested.
File E:\WASv6\profiles\olepaint_v4_mig\logs\WASPostUpgrade.Mon-Oct-11-10.39.42-2004.log
MIGR0260W: JDBCProvider MybankDB2 has been added to the configuration, but the class path
parameter might need to be updated if its prerequisite has changed.

Reviewing application and resources on V6

After running the migration utilities and verifying that the utilities ran correctly, the next step is
to start the Version 6 application server and verify that the application and its resources have
been migrated and are intact.
Change the directory to the profile location containing the bin directory and start the server
from that directory. Our location is shown in this example:
cd E:\WASv6\profiles\olepaint_v4_mig\bin
startServer server1

Your directory would be different. Note that WebSphere Application server is installed at
E:\WASv6 and we are using the profile named olepaint_v4_mig.
Once the server has started, observe the application and resources in the administrative
console. Start the console according to the default URL
http://localhost:9060/ibm/console/. Your console URL may be different if you configured
a non-default port.
Figure 10-4 on page 174 shows the MyBankApp application has been migrated to the new
profile. Figure 10-5 on page 174 shows the JDBC driver resource. Note that the JDBC DB2
driver resided in a different directory, and we changed the classpath to update this new path.
Chapter 10. Runtime application migration examples

173

Figure 10-4 Version 6 application view

Figure 10-5 Version 6 JDBC provider

Figure 10-6 shows the V4 data source. Note that since the data source was migrated from
V4, its has V4 semantics and is found under the V4 data source link.

Figure 10-6 Migrated Version 4 data source

174

WebSphere Application Server V6 Migration Guide

Confirm the application is functioning correctly with the appropriate application test scenarios.

10.3 Automatic migration: Application Server V5 to Express V6

This example shows how to use the migration utilities to migrate WebSphere Application
Server V5.1 to a WebSphere Application Server Express V6 environment. We tested V5.1,
but any V5 fix level should work. The application we used to illustrate the migration
techniques is a more complex variation of the MyBank application used in the example in
10.3, Automatic migration: Application Server V5 to Express V6 on page 175. This variation
we have named MyBankMDB. This application has added an MDB interface and therefore
must use JMS resources. One of the interesting aspects of this example is to show how the
JMS resources are migrated.

10.3.1 Preparing your existing environment for migration

You should perform any application backups before performing a migration of your existing
environment. The migration utilities simply make a copy of the key files on the existing
system. There are no changes made on the source configuration, and therefore, there is no
explicit reason that the source configuration would be modified in any way. However, it is
always good practice to back up a working configuration before undertaking any major event.

10.3.2 Reviewing application and resources on your existing environment

The particular operation of the application is not important to this exercise. However, it is
useful to show the application and resources that we intend to test.
Figure 10-7 shows the applications we are using. The application that we are testing is
MyBankMDB.

Figure 10-7 Version 5 applications

Figure 10-8 on page 176 shows the JDBC resources that the application uses.

Chapter 10. Runtime application migration examples

175

Figure 10-8 Version 5 JDBC Provider

Figure 10-9 shows the WebSphere JMS Provider queue connection factory, which is QCF for
our application.

Figure 10-9 Version 5 Queue Connection Factory

Figure 10-10 on page 177 shows the WebSphere JMS Provider queue destination, which is
Q1 for our application.

176

WebSphere Application Server V6 Migration Guide

Figure 10-10 V5 Queue Destination

10.3.3 Preparing the V6 installation

WebSphere Application Server Express V6 is installed by starting the Launchpad command as
shown in 7.2.1, Launchpad on page 97. The defaults are taken for all the server port
assignments, as shown in Figure 7-8 on page 99. The target directory location of the
installation is overridden in order to make typing the directory name straightforward, but this
directory location is not crucial.

10.3.4 Running automigration utilities

For this migration exercise, we are illustrating migrating such that Version 5.1 and Version 6
reside on the same system. This is in contrast to the scenario described in 10.2, Automatic
migration: V4 AE Single Server to V6 on page 171, where the two installations are on
different systems. The case where both installations are on the same system simplifies the
required steps.
In the following example, we have installed WebSphere Application Server Express V6 under
the directory E:\WebSphere_V6.
call E:\WebSphere_V6\bin\setupCmdline.bat
set WAS_BIN=%WAS_HOME%\bin
set OLDWASHOME=d:\WebSphere\AppServer
set BACKUPDIR=E:\BACKUPS\20041029
%WAS_BIN%\WASPreUpgrade %BACKUPDIR% %OLDWASHOME%

After running the WASPreUpgrade command, you should check its status by consulting the
output log which will be located in the backup directory. The example below shows the last
few lines of the log which indicates successful completion.
File - E:\BACKUPS\20041029\WASPreUpgrade.Fri-Oct-29-08.29.07-2004.log
First several lines deleted
MIGR0303I: The existing WebSphere Application Server environment is saved.
MIGR0420I: The first step of migration completed successfully.

The WASPreUpgrade command creates the E:\BACKUPS\20041029 directory as its output.

You run WASPreUpgrade using the directory as input, and the V6 profile as a container for the
output. The following example shows the commands. The WASPostUpgrade command is run
from the V6 installation directory.
Chapter 10. Runtime application migration examples

177

call E:\WebSphere_V6\bin\setupCmdline.bat
set WAS_BIN=%WAS_HOME%\bin
set BACKUPDIR=E:\BACKUPS\20041029
%WAS_BIN%\WASPostUpgrade %BACKUPDIR%

Please note that the WASPostUpgrade command in this example only uses the single required
argument of the backup directory. The profile name is defaulted because we are operating on
the default profile.
After the WASPostUpgrade command completes, you should review the output log for errors or
warnings. The following example shows an example warning message. The warning
message below is quite common and can often be ignored. You should examine any
warnings about port assignments to determine whether the assignment will conflict with other
servers.
file E:\WebSphere_V6\profiles\default\logs\WASPostUpgrade.Fri-Oct-29-08.35.11-2004.log
MIGR0331W: Port 9080 in file
E:\WebSphere_V6\profiles\default\config\cells\OLEPAINTNode01Cell\nodes\olepaint\servers\ser
ver1\server.xml is migrated, but is already assigned in file
com.ibm.websphere.migration.postupgrade.ApplicationServerHelper$PortMapping@6ca5260a; this
situation might result in port conflicts.

10.3.5 Reviewing application and resources on V6

After running the migration utilities and verifying that the utilities ran correctly, the next step is
to start the V6 application server and verify that the application and its resources have been
migrated and are intact.
Change the directory to the profile location containing the bin directory and start the server
from that directory. Our location is shown here:
cd /d E:\WebSphere_V6\bin\profiles\default\bin
startServer server1

Your directory would be different.

Once the server has started, observe the application and resources in the administrative
console. Start the console according to default URL http://localhost:9060/ibm/console/.
Your console URL may be different if you configured a non-default port.
Figure 10-11 on page 179 shows the MyBankMDB application has been migrated to the new
profile.

178

WebSphere Application Server V6 Migration Guide

Figure 10-11 Applications list

The JDBC driver and JDBC data source are shown in Figure 10-12 and Figure 10-13 on
page 180. Note that the classpath for the JDBC provider was not changed for this example
because we are using the same system to do the migration. Also note that this is a default V5
type data source that is migrated. Contrast this normal data source with the V4 data source
that is migrated in the example in Figure 10-6 on page 174.

Figure 10-12 Example V5 JDBC driver

Chapter 10. Runtime application migration examples

179

Figure 10-13 Example V5 data source

System Integration Bus (SIBus) is the first JMS resource to examine. A default SIBus is
created by the migration utilities in which the name matches the node name. Figure 10-14,
Figure 10-15 and Figure 10-16 on page 181 show the SIBus that is created.

Figure 10-14 Service integration resources

Figure 10-15 Service integration buses

180

WebSphere Application Server V6 Migration Guide

Figure 10-16 Bus general properties

JMS resources that are found in V5 that are required by the example applications are queue
connection factories and queue destinations. These resources are located under JMS
providers identified as V5 default messaging, as shown in Figure 10-17, Figure 10-18 on
page 182, and Figure 10-19 on page 182.

Figure 10-17 JMS provider resources

Chapter 10. Runtime application migration examples

181

Figure 10-18 v5 default messaging provider

Figure 10-19 JMS provider additional properties

The applications in the example require queue connection factories and queue destinations.
Figure 10-20 on page 183 and Figure 10-21 on page 183 show these resources.

182

WebSphere Application Server V6 Migration Guide

Figure 10-20 Queue connection factory

Figure 10-21 Queue destination

Queue destinations also have references under the SIBus destinations. Figure 10-22 shows
the queue destinations. Note that the SIBus destination prefixes the V5 default messaging
queue destination with the characters WQ_.

Figure 10-22 Queue destinations under SI Bus

The MDB listener ports are defined under the application server. The migration utilities
migrate both the MDB listener port and the application listener port binding. Figure 10-23 on
page 184, Figure 10-24 on page 184, Figure 10-25 on page 184, Figure 10-26 on page 184,
and Figure 10-27 on page 184 illustrate navigating under the server definition to find the
listener port definition.

Chapter 10. Runtime application migration examples

183

Figure 10-23 Application servers

Figure 10-24 Message listener service under application servers

Figure 10-25 Message listener service properties

Figure 10-26 Listener port for MyBank application

Figure 10-27 General properties for listener port

184

WebSphere Application Server V6 Migration Guide

The application bindings are also bound to the same MDB listener port. Figure 10-28,
Figure 10-29, and Figure 10-30 show the listener port attributes.

Figure 10-28 Migrated example applications

Figure 10-29 Listener port bindings under each application

Figure 10-30 Listener port bindings values

10.3.6 Migrating Web server and WebSphere plug-ins

A single server scenario may optionally use a Web server in the configuration. WebSphere
plug-in management has been enhanced for WebSphere Application Server Version 6 and
consequently the installation and configuration of the Web server and plug-ins is a bit more
complex than on previous versions. See Web Server plug-ins on page 101 for an overview
of WebSphere plug-ins.
The example shows the process of installing IBM HTTP Server V6 along with the required
plug-in on the same system as the application server. This example, where everything is
installed on the same system, represents a typical configuration in a developer test
environment.
Before beginning the installation of the Web server, ensure that the application server is
stopped.
Install the IBM HTTP Server V6 by launching the launchpad and selecting IBM HTTP Server
Installation. Then select the Launch the installation wizard link. See 7.2.1, Launchpad on
page 97 for an overview of the launchpad. Figure 10-31 on page 186 shows the launchpad
screen for this step.
Chapter 10. Runtime application migration examples

185

Figure 10-31 Launchpad selecting installation of IBM HTTP Server

Follow the prompts in the Web server installation wizard. Specify the Web server installation
directory, typical default installation, and decide if you want the Web server to be installed as
a Windows service.
At the conclusion of the installation of the Web server, you are given the option to run the
WebSphere plug-ins installation wizard. Figure 10-32 shows the introductory screen where
you may choose to see more detailed installation instructions.
After accepting the license agreement, Figure 10-33 on page 187 shows the type of Web
server, which is the IBM HTTP Server V6 for this example.
Figure 10-34 on page 187 shows the remote configuration selection screen where we select
Remote. A Remote selection seems to contradict the actual example configuration, so an
explanation is in order.
The meaning of Remote in the selection screen is that the Web server and the application
server are remote from each other on separate systems. The meaning of Local in the
selection screen is that the Web server is on the same system as the application server. If
Local is chosen, the WebSphere plug-in installer creates a managed Web server instance in
the application server to manage the plug-in configuration files, which only works with the IBM
HTTP Server V6 Web server. We select the Remote case so that this configuration does not
occur.
The plug-ins are installed on the same system as the Web server by necessity, because the
plug-in is executable code which must be loaded by the Web server.
.

Figure 10-32 Plug-in installation initial window

186

WebSphere Application Server V6 Migration Guide

Figure 10-33 Plug-in selection

Figure 10-34 Plug-in selection remote and local

Figure 10-35 specifies a directory location for the plug-in binary files.

Figure 10-35 Plug-in target directory

Figure 10-36 shows the location of the Web server configuration file, which is edited by the
installer to point to the plug-in binary and the plug-in configuration file.

Figure 10-36 Plug-in Web server configuration file location

Figure 10-37 on page 188 shows the default name of the Web server instance under the
application server. Choose a name that represents something meaningful to you.

Chapter 10. Runtime application migration examples

187

Figure 10-37 Plug-in Web server definition

Figure 10-38 shows the default location of the plug-in configuration file which is contained in
the application server configuration. This file location is placed into a line in the Web server
configuration file.
Figure 10-39 shows the final screen of the plug-in installation wizard.

Figure 10-38 Plug-in configuration file

Figure 10-39 Plug-in confirmation

When the plug-in installation is complete, verify that the configurations in various files are
correct. The last few lines of the Web server configuration file look like this:
file E:\IBMHTTPServer_V6\conf\httpd.conf
lines deleted for brevity
LoadModule was_ap20_module "E:\WebSphere_Plugins_V6\bin\mod_was_ap20_http.dll"
WebSpherePluginConfig
"E:\WebSphere_V6\profiles\default\config\cells\OLEPAINTNode01Cell\nodes\webserver1_node\ser
vers\webserver1\plugin-cfg.xml"

This excerpt from the plugin-cfg.xml shows that the applications are mapped properly:
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/JMSSampleWeb/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/JMSSampleWebservlet/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/MyBankWeb/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/MyBankWebservlet/*"/>

188

WebSphere Application Server V6 Migration Guide

Note that the plug-in configuration file was automatically generated by the plug-in installer.
Also note that all the applications that are migrated by the migration utilities are mapped into
the plug-in configuration file because the plug-in installer runs after the migration utilities. The
order of these two steps is important. If the plug-ins are installed before running the migration
utilities, then be sure to map each application to webserver1 and then generate the plug-in
configuration file. See 7.3.4, Plugin-Cfg generation on page 111 for the steps to map
applications to Web servers.

10.3.7 Confirming that the application is functioning correctly

Before testing the applications, start the Web server and application server. If you configured
the servers under Windows services, start them with the Windows Services Control Panel.
Otherwise, start the servers via the command line as shown in this example:
cd /d E:\IBMHTTPServer_V6\bin
E:\IBMHTTPServer_V6\bin>apache
cd /d E:\WebSphere_V6\profiles\default\bin
startServer server1

Verify that the applications are accessible by accessing the proper URL via both ports 9080
and 80.

10.4 Automatic migration: V4 AE Server Group to a V6 Network

Deployment Cluster
This example shows how to use the command line migration utilities to migrate a WebSphere
Application Server Version 4 Advanced Edition Server Group to a WebSphere Application
Server Network Deployment Version 6 environment. The migration wizard can also be used if
preferred. An example using the migration wizard is provided for migration of the WebSphere
Application Server Network Deployment Server Cluster from V5 to V6. We used fix level 4.0.6
for this example but any V4 fix level should work. The application used to illustrate the
migration techniques is one of the sample applications that ships with WebSphere Application
Server Version 4 Advanced Edition. The sample application includes two Web modules as
well as two EJB modules. The EJB modules include a stateless session EJB for the
BeenThere application and a CMP entity EJB for the Hitcount application. The CMP EJB
bean uses a data source which points to a single table database, which is implemented in
IBM DB2 Version 8.1.
Note: This example is based on the Windows operating system. Other operating systems
will vary slightly in the script names (for example, backupConfig.sh instead of
backupConfig.bat) as well as the OS commands for directory creation, etc. Information
about each of the differences for each OS is documented in the WebSphere Application
Server V6 Info Center.

10.4.1 Preparing your existing environment for migration

Even though the WebSphere Application Server Version 6 migration utilities make copies of
the key files on the existing WebSphere system, it is recommended that you perform a file
system backup on your system using a mechanism appropriate for your operating system. A
backup provides you with a recovery point should problems occur during the migration
process. In addition, since the configuration repository for WebSphere Application Server
Chapter 10. Runtime application migration examples

189

Version 4 Advanced Edition is stored in a relational database, you should also perform a
database backup using the tools provided by your database vendor.

10.4.2 Preparing for a V6 installation

After installation of WebSphere Application Server Version 6, you need to create two types of
profiles to which to migrate your WebSphere Application Server Version 4 Advanced Edition
environment:
A custom profile for each Version 6 node to which the V4 Server Group is migrated.
A deployment manager profile on the Version 6 node where the deployment manager is
running.
Note: Each of the Version 6 nodes that you create custom profiles for must be stand-alone
nodes during the migration process. Do not federate the custom profiles into the Version 6
cell with the addNode command until after the migration process is complete.
Figure 10-40 shows that the deployment manager profile type is selected. At the bottom of
the window, you also see the custom profile type. A more complete discussion of profile
creation is discussed in Creating profiles on page 102.

Figure 10-40 Version 6 profile type selection

10.4.3 Reviewing the V4 configuration

The current WebSphere Application Server Version 4 Advanced Edition system configuration
is shown in Figure 10-41 on page 191. There is a single node in the cell; sonoma and a
SonomaServerGroup which is comprised of two servers, SonomaServer1 and
SonomaServer2. In most cases, you will no doubt have more than one node, but you can
simply repeat the steps indicated below for each node in order to perform your migration.

190

WebSphere Application Server V6 Migration Guide

Figure 10-41 Version 4 console showing server groups

Figure 10-42 shows the application that is currently installed.

Figure 10-42 Version 4 console showing applications

Figure 10-43 shows the JDBC driver and associated data sources.

Figure 10-43 Version 4 console showing JDBC provider

Chapter 10. Runtime application migration examples

191

10.4.4 Migrating nodes using automatic migration utilities

The first step in performing the migration is to execute the WASPreUpgrade command. This
command and the results are shown in Example 10-1. The required command line arguments
for this command are:
WASPreUpgrade <backup directory name> <existing WAS V4 install directory>

In this example, we have chosen to save the results in the directory C:\WAS40\backups and
the existing V4 install directory is C:\WAS40\AppServer.
Example 10-1 Executing WASPreUpgrade
C:\WAS60\AppServer\profiles\SonomaCustom01\bin>WASPreUpgrade c:\WAS40\backups
c:\WAS40\AppServer sonoma
IBM WebSphere Application Server, Release 6.0
Product Upgrade PreUpgrade tool, Version 1.0
Copyright IBM Corp., 1997-2004
MIGR0300I: The migration function is starting to save the existing WebSphere Application
Server environment.
MIGR0241I: Output of Get character encoding settings.
MIGR0301I: The existing configuration is being exported.
MIGR0241I: Output of XMLConfig Export.
[11/30/04 21:00:58:769 PST] 5c405690 VirtualHostCo A XMLC0052I: Exporting VirtualHost :
default_host
[11/30/04 21:00:58:849 PST] 5c405690 JMSProviderCo A XMLC0052I: Exporting JMSProvider : IBM
MQSeries
[11/30/04 21:00:59:000 PST] 5c405690 URLProviderCo A XMLC0052I: Exporting URLProvider :
Default URL Provider
[11/30/04 21:00:59:100 PST] 5c405690 JDBCDriverCon A XMLC0052I: Exporting JDBCDriver :
Sample DB Driver
[11/30/04 21:00:59:210 PST] 5c405690 DataSourceCon A XMLC0052I: Exporting DataSource :
SampleDataSource
[11/30/04 21:00:59:230 PST] 5c405690 DataSourceCon A XMLC0052I: Exporting DataSource :
sample
[11/30/04 21:00:59:280 PST] 5c405690 NodeConfig
A XMLC0052I: Exporting Node : sonoma
[11/30/04 21:00:59:661 PST] 5c405690 ApplicationSe A XMLC0052I: Exporting ApplicationServer
: Default Server
[11/30/04 21:01:00:262 PST] 5c405690 SecurityConfi A XMLC0052I: Exporting SecurityConfig :
{1}
[11/30/04 21:01:01:033 PST] 5c405690 ServerGroupCo A XMLC0052I: Exporting ServerGroup :
SonomaServerGroup
[11/30/04 21:01:01:984 PST] 5c405690 EnterpriseApp A XMLC0052I: Exporting EnterpriseApp :
Sample Application
MIGR0302I: The existing files are being saved.
MIGR0303I: The existing WebSphere Application Server environment is saved.
MIGR0420I: The first step of migration completed successfully.
C:\WAS60\AppServer\profiles\SonomaCustom01\bin>

After successful completion of WASPreUpgade, we are ready to run WASPostUpgrade which

imports the configuration for our WebSphere Application Server Version 4 Advanced Edition
node to the WebSphere Application Server Version 6 node custom profile that we have
created. Example 10-2 on page 193 shows the execution of the WASPostUpgrade command.
Note that we have run this command from the bin directory for the custom profile that
corresponds to the custom profile that we created earlier. Also note that if we had multiple
nodes, we would perform the WASPostUpgrade command once on each of the Version 6
nodes.
192

WebSphere Application Server V6 Migration Guide

Example 10-2 Executing WASPostUpgrade

C:\WAS60\AppServer\profiles\SonomaCustom01\bin>WASPostUpgrade C:\WAS40\backups
IBM WebSphere Application Server, Release 6.0
Product Upgrade PostUpgrade tool, Version 1.0
Copyright IBM Corp., 1997-2004
MIGR0304I:
MIGR0367I:
MIGR0241I:
ADMU0116I:

The previous WebSphere environment is being restored.

Backing up the current WebSphere Application Server environment.
Output of backupConfig.
Tool information is being logged in file
C:\WAS60\AppServer\profiles\SonomaCustom01\logs\backupConfig.log
ADMU0128I: Starting tool with the SonomaCustom01 profile
ADMU5001I: Backing up config directory
C:\WAS60\AppServer/profiles/SonomaCustom01\config to file
C:\WAS60\AppServer\profiles\SonomaCustom01\temp\MigrationBackup.Thu-D
ec-02-18.47.42-2004.zip
ADMU5002I: 174 files successfully backed up
MIGR0237I: The migration function read configuration file C:\WAS60\AppServer\pro
files\SonomaCustom01\config\cells\localhostNode01Cell\security.xml successfully.
output edited for brevity
MIGR0408I:
MIGR0341W:
a model or
MIGR0241I:

The configuration is saved successfully.

The application Sample_Application was not installed. The application is part of
server group configuration.
Output of GenPluginCfg.

IBM WebSphere Application Server, Release 6.0

WebSphere Plugin Configuration Generator
Copyright IBM Corp., 1997-2004
PLGC0013I: The plug-in is generating a server plug-in configuration file for all of servers
in the cell localhostNode01Cell.
PLGC0005I: Plug-in configuration file =
C:\WAS60\AppServer/profiles/SonomaCustom01\config\cells\plugin-cfg.xml
MIGR0307I: The restoration of the previous WebSphere Application Server environment is
complete.
MIGR0271W: The migration completed with warnings.

The output runs for many pages, so the example in this book has been edited to exclude
many of the repetitive lines. As you can see, the migration has completed with warnings. It is
important that you examine the warnings to determine if you need to take any corrective
action before proceeding. In this example, we see the following warnings:
That the application server initial and maximum heap sizes were not imported and may
need to be adjusted
That port conflicts might occur if there are pre-existing servers on our V6 node. In this
case, there arent any we can safely ignore.
That it may be necessary to modify the classpath entries for the URL Provider, JMS
Provider and JDBC Driver if the locations differ for these entries between the V4.x node
and the V6.0 node.
That certain security settings and properties are not migrated. You should configure the
LDAP settings before enabling security. Also, various KeyRing files are not migrated. You
should either manually migrate the KeyRing settings, or configure SSL to use new
KeyRings. Since periodic KeyRing maintenance is a good idea, you might want to take
this opportunity to do so, but only if it does not impact your current production machines.
Chapter 10. Runtime application migration examples

193

In our example, we are going to wait before making any changes since we will need to run
WASPostUpgrade on the deployment manager profile. Some of the warnings refer to cell wide
configuration parameters, such as LDAP server settings for Global Security. It is best to note
the warnings here and make the changes all at once.
Once you have examined the output from the WASPostUpgrade command, you are ready to
run addNode. This is depicted in Example 10-3, where the deployment manager is running on
the same node, sonoma, that the Application Servers are on.
Note: Recall that you need to run WASPostUpgrade on each of the nodes that you are
migrating, and you should do so before running addNode.
Example 10-3 Executing addNode
C:\WAS60\AppServer\profiles\SonomaCustom01\bin>addnode sonoma
ADMU0116I: Tool information is being logged in file
C:\WAS60\AppServer\profiles\SonomaCustom01\logs\addNode.log
ADMU0128I: Starting tool with the SonomaCustom01 profile
ADMU0001I: Begin federation of node sonoma with Deployment Manager at
sonoma:8879.
ADMU0009I: Successfully connected to Deployment Manager Server: sonoma:8879
ADMU0505I: Servers found in configuration:
ADMU0506I: Server name: server1
ADMU0506I: Server name: SonomaServer1
ADMU0506I: Server name: SonomaServer2
ADMU2010I: Stopping all server processes for node sonoma
ADMU0512I: Server server1 cannot be reached. It appears to be stopped.
ADMU0512I: Server SonomaServer1 cannot be reached. It appears to be stopped.
ADMU0512I: Server SonomaServer2 cannot be reached. It appears to be stopped.
ADMU0024I: Deleting the old backup directory.
ADMU0015I: Backing up the original cell repository.
ADMU0012I: Creating Node Agent configuration for node: sonoma
ADMU0014I: Adding node sonoma configuration to cell: sonomaNetwork
ADMU0016I: Synchronizing configuration between node and cell.
oldVarTable: {}
newVarTable: {}
diffTable: {}
ADMU0018I: Launching Node Agent process for node: sonoma
ADMU0020I: Reading configuration for Node Agent process: nodeagent
ADMU0022I: Node Agent launched. Waiting for initialization status.
ADMU0030I: Node Agent initialization completed successfully. Process id is:
3004
ADMU0300I: Congratulations! Your node sonoma has been successfully incorporated
into the sonomaNetwork cell.
ADMU0306I: Be aware:
ADMU0302I: Any cell-level documents from the standalone localhostNode01Cell
configuration have not been migrated to the new cell.
ADMU0307I: You might want to:
ADMU0303I: Update the configuration on the sonomaNetwork Deployment Manager
with values from the old cell-level documents.
ADMU0306I: Be aware:
ADMU0304I: Because -includeapps was not specified, applications installed on
the standalone node were not installed on the new cell.
ADMU0307I: You might want to:
ADMU0305I: Install applications onto the sonomaNetwork cell using wsadmin
$AdminApp or the Administrative Console.
ADMU0003I: Node sonoma has been successfully federated.

194

WebSphere Application Server V6 Migration Guide

10.4.5 Migrating the deployment manager using automatic migration utilities

While the node has been successfully migrated and federated into the cell, we are still not
finished. We still need to run WASPostUpgrade on the deployment manager profile so that
various cell wide definitions such as the Server Cluster and Resources can be migrated. If
you were to go to the administrative console at this point, without running WASPostUpgrade on
the deployment manager, these resources would not be configured. An example of this is
shown by the missing Server Cluster in Figure 10-44.

Figure 10-44 Version 6 console showing clusters

After stopping the deployment manager with the stopManager command, we are ready to run
WASPostUpgrade on the deployment manager profile that we created. We execute this
command from the bin directory under the deployment manager profile as shown in
Example 10-4.
Example 10-4 Executing WASPostUpgrade on deployment manager
C:\WAS60\AppServer\profiles\SonomaDmgr01\bin>WASPostUpgrade C:\WAS40\backups
IBM WebSphere Application Server, Release 6.0
Product Upgrade PostUpgrade tool, Version 1.0
Copyright IBM Corp., 1997-2004
MIGR0304I:
MIGR0367I:
MIGR0241I:
ADMU0116I:

The previous WebSphere environment is being restored.

Backing up the current WebSphere Application Server environment.
Output of backupConfig.
Tool information is being logged in file
C:\WAS60\AppServer\profiles\SonomaDmgr01\logs\backupConfig.log
edited for brevity

MIGR0408I: The configuration is saved successfully.

MIGR0307I: The restoration of the previous WebSphere Application Server environment is
complete.
MIGR0271W: The migration completed with warnings.

At this point, make a note of the various warnings so that you can make any changes or
updates required for the Application Server and deployment manager all at once, as
mentioned previously, after starting the deployment manager using the startManager
command.

Chapter 10. Runtime application migration examples

195

Figure 10-45 Server clusters after deployment manager migration

After starting the deployment manager, you should navigate to various artifacts mentioned in
before to make sure that they are now present. These are depicted in Figure 10-46,
Figure 10-47 on page 197, and Figure 10-48 on page 198 for the ServerGroup that is now a
Server Cluster, the JDBC Driver and its associated V4 Data Sources. Be sure to ensure that
the classpath settings are correct for the JDBC Driver, and to update the LDAP server
settings for Global Security as well as the KeyRing settings.

Figure 10-46 Version 6 console showing JDBC provider

196

WebSphere Application Server V6 Migration Guide

Figure 10-47 Version 6 console showing data source

Once you have made updates to the resources or application server definitions such as heap
size, you are ready to install the Enterprise Application to the Server Cluster. Please note that
migration from V4 to V6 does not migrate the application installation, but it does place the
EAR file for any applications in this directory:
profiles/nodeprofile/installableableApps

In our example, this is:

C:\WAS60\AppServer\profiles\SonomaCustom01\installableApps

We then install any applications in this directory via the administrative console. This process
is very similar to installation on V4 or V5. Once you have finished installing the application, be
sure to save your changes and synchronize your changes with all the nodes in the cluster.

10.4.6 Migrating Web Server and plug-ins

You are now ready to regenerate the HTTP server plug-in file and distribute it to the HTTP
servers. Depending on whether or not you have chosen to create managed nodes for your
HTTP servers, the mechanism for distributing the updated plug-in configuration file varies.
Your options are:
Create a custom profile so that you have an node agent to manage your HTTP server,
plug-in file configuration and plug-in file distribution.
Install IBM HTTP Server V6.0, which provides HTTP server and plug-in maintenance
without a node agent.
Manually manage HTTP server and plug-in maintenance.
See 10.3.6, Migrating Web server and WebSphere plug-ins on page 185 for more details on
migrating the Web server.
Once you have taken care of plug-in maintenance, you are ready to start your Server Cluster.
Once the Server Cluster is started, it looks as shown in Figure 10-48 on page 198.

Chapter 10. Runtime application migration examples

197

Figure 10-48 Version 6 console showing starting the cluster

Assuming your application test is successful, you have completed your V4.x to V6.0
migration.

10.5 Automatic migration: V5 Network Deployment Cluster to

V6 Network Deployment Cluster
This example shows how to use the the migration wizard to migrate a WebSphere Application
Server Network Deployment Version 5 Server Cluster to a V6 environment. The command
line utilities can also be used if preferred. We use fix level 5.1.1 for this example but any
Version 5 level can be migrated in the same manner. The application we use is one of the
sample applications that ships with WebSphere Application Server Version 5; the default
application includes a Web module as well as an EJB module. The EJB module includes a
CMP entity EJB for the hitcount application. The CMP EJB bean uses a data source which
points to a single table database, which is implemented in IBM DB2 Version 8.1.
While we are going to migrate both the application server (Server Cluster) node(s) and the
deployment manager node in this example, a Version 6 deployment manager can manage a
cell comprised of both Version 5 and Version 6 nodes. We demonstrate the V6 deployment
manager managing a Version 5 node. This capability allows you to incrementally upgrade
your runtime and applications, minimizing or possibly eliminating any application service
interruption.
Note: Within a given cell, the deployment manager must be at the latest release and
highest version of any nodes in the cell, in order for it to manage the nodes in the cell.

10.5.1 Preparing your existing environment for migration

Even though the automatic migration utilities make copies of the key files on the existing
WebSphere system, it is recommended that you perform a file system backup on your
system, using a mechanism appropriate for your operating system before starting any
migration activities; this provides you with a recovery point should problems occur during the
migration process.

198

WebSphere Application Server V6 Migration Guide

10.5.2 Starting the configuration

You will need to take note of the current Version 5 node and cell names before you proceed
with Version 6 profile creation. The names for the cell and the nodes should match when
moving from Version 5 to Version 6. This information is available from a variety of sources;
perhaps the easiest way is to look at the cell name in the administration console shown in
Figure 10-49.

Figure 10-49 Version 5 console cell name

The node names are shown in Figure 10-50, where sonoma is the application server node
name and sonomaManager is the deployment manager node name. In cases where
multiple nodes exist, record the names for the V5 application server nodes and then create a
V6 custom or stand-alone application server profile for each of those nodes.

Figure 10-50 Version 5 console nodes in cell

Note: You must use the same node and cell names when migrating from Version 5 to
Version 6.
The current V5.x cell has a server cluster named SonomaCluster as depicted in
Figure 10-51 on page 200.
Chapter 10. Runtime application migration examples

199

Figure 10-51 Version 5 console clusters in cell

The Server Cluster is comprised of two application servers, clusterserver1 and

clusterserver2, as shown in Figure 10-52.

Figure 10-52 Version 5 console servers in cluster

The Enterprise Applications installed are shown in Figure 10-53 on page 201. The application
running in the Server Cluster is the DefaultApplication. You will note that the Server Cluster
and application are running. You can migrate a V5.x node without stopping it. The migration
tools can collect all the configuration data while the node is either running or stopped, but you
must stop the V5.x node before you can start the V6.0 node that you are migrating to.

200

WebSphere Application Server V6 Migration Guide

Figure 10-53 Version 5 console applications

10.5.3 V6 installation preparation

After the installation of WebSphere Application Server Network Deployment, you must create
two types of profiles:
Create either a custom profile or a stand-alone server profile for each node where the
Server Cluster is installed. We use a custom profile in this example.
Create a deployment manager profile on the node where the deployment manager is
running.
Note: Each of the target Version 6 nodes that you create custom profiles for must be
stand-alone nodes during the migration process. Do not federate the custom profiles into
the Version 6 cell with the addNode command prior to starting the migration process. The
migration utilities perform this task during the migration process.

The specification of a custom profile is shown in Figure 10-54. Node and host name
properties are depicted in Figure 10-55 on page 202. Recall that the node name information
must match the current V5 node name information, as discussed previously.

Figure 10-54 Selecting custom profile

Chapter 10. Runtime application migration examples

201

Figure 10-55 Profile node and host names

The selection of a deployment manager profile in the profile creation wizard is shown in
Figure 10-56. Specification of the node, host and cell names are shown in Figure 10-57 on
page 203. Again as noted previously, the node and cell names in V6.0 must match the
information from the V5.x configuration.

Figure 10-56 Selecting deployment manager profile

202

WebSphere Application Server V6 Migration Guide

Figure 10-57 Profile node and host names for deployment manager

10.5.4 Deployment manager migration using the migration wizard

The V6 migration wizard is a graphical alternative to the command line WASPreUpgrade and
WASPostUpgrade commands, and is launched from the firststeps directory under the profile
that we are migrating to. Since the first step in migrating the cell is to migrate the V5.x
deployment manager to a V6.0 deployment manager, locate the firststeps directory under
your deployment manager profile. In the example case, this is
C:\WAS60\AppServer\profiles\SonomaDmgr01\firststeps. From there, open a command
window and type in firststeps. This brings up the First steps client, as shown in
Figure 10-58.

Figure 10-58 First steps

Select the migration wizard which launches the migration wizard client as shown in
Figure 10-59 on page 204, then select Next to continue with the migration wizard dialog.

Chapter 10. Runtime application migration examples

203

Figure 10-59 Starting migration wizard

This then brings up the version selection dialog as shown in Figure 10-60. In this case, since
we are migrating the deployment manager, we select the Network Deployment installation
on the machine.
Note: Before proceeding any further, be sure to stop the Version 5 deployment manager
with the stopManager command if you have not already done so. Failure to do so results in
a migration failure.

Figure 10-60 Migration wizard existing versions

Specify the directory where the backup of the current V5.x configuration is saved, as shown in
Figure 10-61 on page 205.

204

WebSphere Application Server V6 Migration Guide

Figure 10-61 Migration wizard backup directory

The last input before the migration occurs is the specification of the target profile, as shown in
Figure 10-62.

Figure 10-62 Migration wizard target profile

Note: Be sure to start the migration wizard from the startup directory under the profile you
are migrating to; this simplifies input of the information related to the to configuration you
are migrating to.
Then proceed to start the migration wizard, which invokes the WASPreUpgrade command as
shown in Figure 10-63.

Figure 10-63 Migration wizard completion of WASPreUpgrade

Selecting Next invokes the WASPostUpgrade command, as shown in Figure 10-64 on

page 206.

Chapter 10. Runtime application migration examples

205

Figure 10-64 Migration wizard WASPostUpgrade starting

As with the command line version of WASPostUpgrade, you should review all the messages
generated to make sure that your deployment manager migration has completed
successfully. In our example, the final message was:
MIGR0271W: The migration completed with warnings.

We look at the migration log at C:\was51\backups\migration\dmgr and look for warning

message codes that end in W. In our example, the following warnings were generated:
MIGR0401W: The Transports setting in file server.xml is deprecated.
MIGR0331W: Port 9043 in file
C:\WAS60\AppServer\profiles\SonomaDmgr01\config\cells\sonomaNetwork\nodes\sono
maManager\servers\dmgr\server.xml is migrated, but is already assigned in file
com.ibm.websphere.migration.postupgrade.ApplicationServerHelper$PortMapping@21d
5bca; this situation might result in port conflicts.
MIGR0401W: The PMIService:initialSpecLevel setting in file server.xml is deprecated.
MIGR0379W: Do not use the existing deployment manager in the old configuration. It has
been disabled.
Tip: The last character in WebSphere log messages indicates the type of message.
The possible values are A - Audit, I - Informational, E - Error, W - Warning, F - Fatal, O
- System.out by user application or internal components, R - System.err by user
application or internal components, U - a special type used by the message logging
component of the WebSphere Application Server runtime, Z - a placeholder to indicate
that the type was not recognized.
After review of the messages and investigation of the possible port conflict, we determine that
we are ready to start the V6 deployment manager to start managing our V5.1 cell. All the
other messages in the log end in I indicating that they are Informational messages.
After starting the deployment manager with the StartManager command, we invoke the
adminconsole application from a Web browser with the URL:
http://sonoma:9090/admin

which redirects to:

http://sonoma:9090/ibm/console

206

WebSphere Application Server V6 Migration Guide

which is the new URL for Version 6. Note that even though the default Version 6
administration port is 9060, we choose to retain 9090 while selecting options in the migration
wizard).
In Figure 10-65, we navigate to the Application Servers dialog (Servers -> Application
Servers). We can see the two application servers in our cluster running and we can also see
that they are V5.1.1 application servers. It is worth noting that, during the conversion of the
deployment manager, we did not stop the node agent or the application servers running on
our node. As a result, application availability was not impacted during this portion of the
migration.

Figure 10-65 Version 6 console showing servers

When we look at the nodes in our cell in Figure 10-66, we see that the managed node,
sonoma, is a V5.1.1 node. However, the deployment manager node, sonomaManager, is a
V6.0 node.

Figure 10-66 Version 6 console showing nodes in cell

10.5.5 Managed node migration using the migration wizard

Now that we have a V6.0 deployment manager managing our cell, we can start to migrate our
managed nodes. In our example, we are only dealing with a single managed node, while in a
production environment multiple nodes would exist, which would allow us to stop and migrate
one node (and the application servers on it) at a time, while the remaining nodes (and
application servers) continue to serve applications requests.
Chapter 10. Runtime application migration examples

207

We start the migration wizard by navigating to the firststeps directory under the custom profile
for the managed node that we created earlier, and select the Migration wizard. See
Figure 10-67. Note that the First Steps Java client for a managed node profile differs from the
First Steps Java client for a deployment manager profile.

Figure 10-67 First steps for node migration

We proceed through the migration wizard as we did for the deployment manager migration.
First, select the V5.1 version that we are going to migrate, then specify a backup directory.
C:\WAS51\backups\migration\sonomanode

If we were migrating multiple nodes, we would specify a different backup directory for each of
our nodes in this fashion.
We then select the target profile for our migration, as shown in Figure 10-68. By starting First
Steps and the migration wizard from the profile, the profile name is populated automatically.

Figure 10-68 Migration wizard target profile for node

The migration wizard then runs the WASPreUpgrade script.

Until now, the application servers on the node have continued to run in order to maximize
availability. Before starting the next step in the migration wizard, which runs the
WASPostUpgrade script, you must stop the application servers and the node agent on the node
being migrated. If you forget to do this, the migration wizard stops the node agent and
application servers if they are not already stopped. Once the migration wizard completes
WASPostUpgrade, as shown in Figure 10-69 on page 209, you should look at the migration logs
to see what warnings or errors were generated during the migration.

208

WebSphere Application Server V6 Migration Guide

Figure 10-69 Migration wizard completion for node

As you can see, the migration has completed with warnings. It is important that you examine
the warnings to determine if you need to take any corrective action before proceeding. In this
example, we see the following messages:
MIGR0404W: Do not use the node agent in the old configuration. It has been disabled.
PLGC0020E: No valid server definitions are found for the server cluster
dmgr_sonomaManager_Cluster. It is ignored.
None of these messages requires any corrective action.
At this point, we are ready to start the node agent with the startNode command:
cd /d c:\WAS60\AppServer\profiles\SonomaCustom01\bin
startNode

Once the node agent is started, you can return to the administrative console and start the
application servers on the node that are part of the server cluster. This is shown in
Figure 10-70.

Figure 10-70 Version 6 console showing servers migrated to Version 6

At this point, you are ready to test the applications running on the application servers to make
sure that they are functioning correctly. We do so by invoking the Web application directly on
the Web container HTTP port and validating that the application is functioning correctly. Once
this is done, we are ready to place this node into service. Since the WasPostUpgrade script

Chapter 10. Runtime application migration examples

209

already regenerated the plug-in for us, all we need to do is to distribute the plugin-cfg-xml file
to the HTTP servers in order to allow client requests to flow to our newly upgraded V6 node,
application servers and application.
Depending on whether or not you have chosen to create managed nodes for your HTTP
servers, the mechanism for distributing the updated plug-in configuration file varies. Your
three options are:
Install WebSphere Application Server Version 6 and create a custom profile so that you
have a node agent to manage your HTTP server, plug-in configuration file and plug-in file
distribution.
Install IIBM HTTP Server Version 6, which provides the noted HTTP server and plug-in
maintenance without a node agent.
Continue to manually manage your HTTP server and plug-in maintenance.
At this point, you have successfully completed migration of your deployment manager and
one of your managed nodes. In a multi-node environment you would repeat the managed
node migration steps for each node in your deployment.

10.6 Manual migration: installation of J2EE 1.3 Enterprise

Application on V6 Application Server
This example uses the same application as discussed in 10.3, Automatic migration:
Application Server V5 to Express V6 on page 175. That example shows a migration using
the automatic migration utilities. It shows how to install and configure that same application
manually. In other words, we do not start with the application already installed on a system.
We instead take the application EAR file and install it using the administrative console. We
then configure the required resources with the administrative console.

10.6.1 Preparing the V6 installation

A V6 application server is created using the profile creation wizard. This example uses an
installation of WebSphere Application Server Network Deployment Version 6 and creates an
application server profile using the default ports. This example should work equally well on
any of the WebSphere server types, including a deployment manager. We do not show the
details of installing and configuring the profile. See 7.2.3, Profiles on page 101 for an
overview of these steps.
Before getting to the basics of configuration in the administrative console, you first need to
start the server and administrative console if you have not already done so.
Start the application server.
cd /d e:\WebSphere_V6\profiles\olepaint\bin
startServer server1

Start the administrative console in your Web browser.

http://localhost:9060/ibm/console

Log in using any name you wish. Figure 10-71 on page 211 shows the login to the
administrative console. The name is an arbitrary string that tracks the changes you make
before you commit and save.

210

WebSphere Application Server V6 Migration Guide

Figure 10-71 Administrative Console Login

10.6.2 Configuring JMS resources

1. Create an SI Bus.
a. Navigate to the Service Integration section and open Buses as shown in Figure 10-72.

Figure 10-72 Creating SI Bus - Service Integration - Buses

b. Create a new bus with the New button as shown in Figure 10-73.

Figure 10-73 Creating SI Bus - New bus

c. Specify these fields in the new bus window, shown in Figure 10-74 on page 212, and
accept defaults for the remainder of the fields. Select OK when done.

Name: MDBbus
Secure: Deselect

Chapter 10. Runtime application migration examples

211

Figure 10-74 Creating SI Bus - General Properties

d. Reselect MDBbus to specify further attributes, as shown in Figure 10-75.

Figure 10-75 Creating SI Bus - New bus MDBbus

e. Select Bus Members under Additional Properties as shown in Figure 10-76.

Figure 10-76 Creating SI Bus - Bus Members

f. Add a new member with the Add button. Specify Server as the member type and
select the server name, as shown in Figure 10-77 on page 213. Our example only has
212

WebSphere Application Server V6 Migration Guide

server1 available to select. Accept defaults for the remaining fields on that screen.
Select Next when done.

Figure 10-77 Create SI Bus - Select Server

g. Select Finish on the next screen.

h. Reselect MDBbus and then Destinations under Additional Properties. Then create a
new destination with the New button, as shown in Figure 10-78.

Figure 10-78 Create SI Bus - New Destination

i. Select Queue as the destination type as shown in Figure 10-79.

Figure 10-79 Creating SI Bus - Selecting Destination Type

j. In the Set Queue Attributes, specify BankJSQueue as the Identifier, as shown in

Figure 10-80 on page 214. Note that this name must match the Queue name shown in
Figure 10-86 on page 216.

Chapter 10. Runtime application migration examples

213

Figure 10-80 Creating SI Bus - Adding Queue Destination ID

k. Assign the queue to the existing bus members, as shown in Figure 10-81. This
example only has server1 available as a bus member.

Figure 10-81 Creating SI Bus - Assign Queue to Bus Member

l. Select Next when done. On the next screen, select Finish.

That concludes creating the SI bus resources. Once you have an SI bus created, you can
attach multiple destinations and associate multiple JMS resources to those destinations.
We show you how to create JMS resources in the next step.
2. Create a JMS Queue Connection Factory.
a. Navigate to the Resources section, then JMS Providers, then Default Messaging, as
shown in Figure 10-82.

Figure 10-82 Creating JMS Connection Factory - Default Messaging

b. Under Connection Factories, select JMS Queue Connection Factory, as shown in

Figure 10-83.

Figure 10-83 Creating JMS Connection Factory - Connection Factories

c. In the next screen, select the New button. Specify the following fields and accept the
defaults for the remaining fields. Select OK when done.
214

WebSphere Application Server V6 Migration Guide

Name

BankJMSQCF

JNDI Name

MyBank/QCF

Bus Name

MDBbus

Note that the JNDI name must match the name used by the application.

Figure 10-84 Creating JMS Queue Connection Factory - General Properties

3. Create a JMS Queue.

a. Navigate to Default Messaging Providers, then select JMS Queue under Destinations.

Figure 10-85 Creating JMS Queue - Destinations

b. In the next screen, select the New button. Specify the following fields, as shown in
Figure 10-86 on page 216, and accept the defaults for the remaining fields. Select OK
when done.
Name

BankJMSQueue

JNDI Name

MyBank/Q1

Bus Name

MDBbus

Queue Name

BankJSQueue

Note that the JNDI Name must match the name in Figure 10-88 on page 217. Also, the
Queue Name must match the name in Figure 10-80 on page 214.

Chapter 10. Runtime application migration examples

215

Figure 10-86 Create JMS Queue - General Properties

4. Create a JMS Activation Specification

a. Navigate to Default Messaging Providers and select JMS Activation Specification
under Activation Specifications, as shown in Figure 10-87.

Figure 10-87 Create JMS Activation Specification - Navigation

b. Create a new specification with the New button. In the new activation specification
screen, as shown in Figure 10-88 on page 217, specify these fields and default the
remaining fields. Select OK when done.
Name

MyBankAS

JNDI Name

MyBank/AS

Destination type

Queue

Destination JNDI Name

MyBank/Q1

Bus Name

MDBbus

Note that the Destination JNDI name must match the JNDI Name of the JMS queue
destination that you configured in Figure 10-86.

216

WebSphere Application Server V6 Migration Guide

Figure 10-88 Create JMS Activation Specification - General Properties

c. Save the configuration by selecting the Save link at the top of the screen. Then select
the Save button again to confirm the save, as shown in Figure 10-89.

Figure 10-89 Saving Configuration

10.6.3 Configuring JDBC resources

1. Create an authentication alias.
a. Navigate to Global Security under Security in the left navigation bar. On the Global
Security screen, select J2C Authentication Alias under Authentication, as shown in
Figure 10-90.

Figure 10-90 Creating Authentication Alias - Navigation

b. Create a new alias with the New button and specify the following fields, as shown in
Figure 10-91 on page 218. Select OK when done.

Chapter 10. Runtime application migration examples

217

Alias

db2user

User ID

Specify your own DB2 user

Password

Specify the matching password for the DB2 user

Figure 10-91 Creating Authentication Alias - General Properties

2. Create a JDBC Provider.

a. Navigate to Resources, then JDBC Providers in the left navigation bar, as shown in
Figure 10-92.

Figure 10-92 Creating JDBC Provider - Navigation

b. Create a new JDBC provider with the New button. Select these settings from the
selector fields, as shown in Figure 10-93. Select OK when done.
Database type

DB2

Provider type

DB2 Universal JDBC Driver Provider

Implementation type

XA data source

Figure 10-93 Creating JDBC Provider - Type Selection

c. On the next screen, as shown in Figure 10-94 on page 219, specify a unique provider
name and the correct classpath for your DB2 JDBC drivers. Do not rely on the settings
you see defaulted in the classpath. The variables identifying the DB2 driver location
may or may not be correct, depending on what order you installed DB2 in relation to
the application server. You should specify a full path name for all the concerned files,
as shown below. You do not have to worry about which direction the slash file
delimiters are pointing. You can use either forward or reverse slashes, regardless of
the operating system you are using.
D:/Db2_8.1/SQLLIB/java/db2jcc.jar
D:/Db2_8.1/SQLLIB/java/db2jcc_license_cu.jar
D:/Db2_8.1/SQLLIB/java/db2jcc_license_cisuz.jar

218

WebSphere Application Server V6 Migration Guide

For this example, we specify a provider name of Bank JDBC and the correct JDBC
driver path.

Figure 10-94 Creating JDBC Provider - General Properties

3. Create a data source.

a. Select the Bank JDBC provider you just created. In the next screen, shown in
Figure 10-95, select Data sources.

Figure 10-95 Creating Data Source - Navigation

b. On the next screen, shown in Figure 10-96 on page 220, specify the following fields
and default the remaining fields.
Name

BankDS

JNDI Name

jdbc/MyBank

Use this Data Source in container managed persistence

Checked

Container managed authentication alias

db2user

Database Name

BankData

Chapter 10. Runtime application migration examples

219

Figure 10-96 Creating Data Source - Properties

c. Save the configuration again, as we did in a previous step in Figure 10-89 on

page 217.
You are not strictly required to perform intermediate saves of the configuration, but we
recommend saving at periodic intervals. Once you get in the habit of saving your
configuration work, you will be less likely to forget to save at the end of the task.

10.6.4 Installing the application

The application installation wizard presents you with several steps in which you can override
default information. The number of steps varies with the exact configuration of your
application. We show you the screens where this particular example needs customization.
We also show screens that you may need to change for your own particular application.
For a more complete tutorial on application installation, consult the IBM Education Assistant
for the application installation topic. This topic has both charts and browser animation for
application installation. You can find this topic here:
ftp://ftp.software.ibm.com/software/eod/WAS_6-0/SystemManagement/index.html

For all these steps, you can navigate backward and forward by either selecting the Previous
or Next buttons, or selecting the explicit step number on the left side of the screen.
Figure 10-97 on page 221 shows a list of all the steps we encounter for this application. You
may encounter a different number of steps with a different application. By selecting the step
number, you can select steps in any order. The summary step is the last step where you finish
and commit all your answers.

220

WebSphere Application Server V6 Migration Guide

Figure 10-97 Application Install - Navigation though steps

1. Start the application installation wizard by selecting Install New Applications under the
Applications section of the left navigation bar, shown in Figure 10-98.

Figure 10-98 Application Installation - Starting Wizard

2. Specify the EAR file for the application, as shown in Figure 10-99.

Figure 10-99 Application Installation - Specify File

3. On the preparations page, do not check Generate Default Bindings, as shown in

Figure 10-100. This effectively ignores the remaining fields on that page. Generating
default bindings for this application is not necessary because the EAR file we use already
has explicit bindings assigned. If your application was not previously bound, you could
generate default bindings automatically.

Figure 10-100 Application Installation - Default Bindings

Chapter 10. Runtime application migration examples

221

4. On the Select Installation Options page, shown in Figure 10-101, accept the defaults,
which are usually correct.

Figure 10-101 Install Application - Options

5. On the Map Modules to Servers page, shown in Figure 10-102, accept the defaults. In the
topology we use, there is only one server and therefore only one choice can be made. If
you were installing on a deployment manager, you would have multiple servers from which
to choose.

Figure 10-102 Application Install - Map Servers

6. On the EJBDeploy Options page, shown in Figure 10-103, specify the data base type,
which in this case is IBM DB2 8.1.

Figure 10-103 Application Installation - EJB Deploy Options

222

WebSphere Application Server V6 Migration Guide

7. On the MDB Listener Bindings page, shown in Figure 10-104, specify either a Listener
port or an Activation Specification. This example specifies the activation specification with
a JNDI name MyBank/AS. Note that this name must match the name specified in
Figure 10-88 on page 217.

Figure 10-104 Application Installation - Specify Activation Specification

8. On the JNDI Names for Beans page, shown in Figure 10-105, accept the default
assignments.

Figure 10-105 Application Installation - Specify JNDI Names

9. On the Default Data Sources page, shown in Figure 10-106, select a data source to apply
to all the EJBs in the application. Scroll to the bottom of the page and select the EJB
modules you want to apply a data source for. This example only has one EJB to choose.

Figure 10-106 Application Install - Default Data Source - step a

10.On the same page, scroll up to the top and select the data source which you want to apply
as the default data source. This is shown in Figure 10-107 on page 224. Then click the
Apply button. For this example, we had already configured jdbc/MyBank; therefore, it can
be selected in the pull-down menu. It is also possible to key the JNDI name value in case
the data source has not yet been defined. You can scroll back down to the EJB modules
and see that the JNDI name has been applied.

Chapter 10. Runtime application migration examples

223

Figure 10-107 Application Install - Default Data Source - step b

11.The remainder of the steps are omitted because the default values are acceptable for this
exercise.
12.Select the last summary step and click Finish. The installation begins. Observe the output
and confirm that the installation wizard was successful.
13.Save the configuration as shown in Figure 10-89 on page 217.
14.Log out from the administrative console.
15.Restart the application server:
cd /d e:\WebSphere_V6\profiles\olepaint\bin
stopServer server1
startServer server1

10.6.5 Verifying the application operation

The example application MyBankMDB is tested by exercising the account create and transfer
beans from the Web interface, thus proving the data source is configured correctly. The
transfer bean is also accessed through the MDB interface, thus proving the JMS resources
are configured correctly.

224

WebSphere Application Server V6 Migration Guide

Appendix A.

Prerequisite software
Before you can upgrade IBM Rational Developer or WebSphere Application Server to V6, you
need to do additional planning regarding other software packages that may need to be
updated. This appendix is a summary of the various versions of software that are supported.

Copyright IBM Corp. 2005. All rights reserved.

225

Prerequisites for IBM Rational Developer

IBM Rational Developer has dependencies on the host operating system, but is otherwise
independent. Consult this document for the most recent information about prerequisites for
IBM Rational Developer:
http://www-306.ibm.com/software/awdtools/developer/application/sysreq/index.html

Operating systems
Table A-1 shows which operating systems are supported for the Rational Developer product
line. This table also applies for WebSphere Application Server Toolkit.
Table A-1 Supported operating system levels
Microsoft Windows 2000 Professional
Microsoft Windows 2000 Advanced Server
Microsoft Windows 2000 Standard Server
Microsoft Windows XP Professional
Microsoft Windows 2003 Standard Server
Microsoft Windows 2003 Enterprise Server
Red Hat Enterprise Linux WS 3.0 IA32 architecture
SUSE Linux Enterprise Server 9.0 IA32 architecture

Prerequisites for WebSphere Application Server

Consult this document for the most recent information about prerequisites for WebSphere
Application Server Version 6:
http://www-306.ibm.com/software/webservers/appserv/doc/v60/prereqs/prereq60.html

Operating systems
Table A-2 shows which operating systems are supported. The operating systems which are
marked X in the column title Supported for development only are intended by the operating
system vendor to be a workstation operating system rather than a server operating system.
Operating systems intended for workstations may not have the capability to perform to the
same capacity and robustness as would an operating system for a server. Therefore,
operating systems intended for workstations are not supported for production server
environments. Such a configuration is supported for development use for development
testing and prototyping.
Table A-2 Supported operating system versions
Operating System

226

Supported
for
development
only

Supported
for
production
and
development

AIX 5L 5.1 with maintenance 5100-05

AIX 5L 5.2 with maintenance 5200-03

WebSphere Application Server V6 Migration Guide

Operating System

Supported
for
development
only

Supported
for
production
and
development

AIX 5L 5.3 with quality pack June 2004

HP-UX 11i

Red Hat Enterprise Linux AS 3.0 Update 2 or 3

Red Hat Enterprise Linux 3.0 WS/ES Update 2 or 3

SuSE Linux Enterprise Server 8 SP3

SuSE Linux Enterprise Server 9

Solaris 8 / Recommended Patch Cluster of June 2004

Solaris 9 / Recommended Patch Cluster of June 2004

Windows 2000 Advanced Server SP4

Windows 2000 Server SP4

Windows 2000 Professional SP4

Windows Server 2003, Datacenter

Windows Server 2003, Enterprise

Windows Server 2003, Standard

Windows XP Professional SP1a

Database servers
Table A-3 shows the supported database servers necessary to perform Enterprise Java Bean
persistence.
Table A-3 Supported database servers
Cloudscape 5.1.60.17
IBM DB2 for z.OS v7 or v8
IBM DB2 for iSeries 5.2 or 5.3
IBM DB2 Connect 8.1 FP7a or 8.2
IBM DB2 Enterprise Server Edition 8.1 FP7a or 8.2
IBM DB2 Express 8.1 FP7a or 8.2
IBM DB2 Workgroup Server Edition 8.1 FP7a or 8.2
IBM DB2 Information Integrator 8.1 FP7a or 8.2
IBM Informix Dynamic Server 9.3 or 9.4
Oracle 8i Standard or Enterprise Release 3 8.1.7.4
Oracle 9i Standard or Enterprise Release 2 9.2.0.4
Oracle 10g Standard or Enterprise Release 1 10.1.0.3

Appendix A. Prerequisite software

227

Microsoft SQL Server Enterprise 2000 SP 3a

Sybase Adaptive Server Enterprise 12.0.0.8, 12.5.1 or 12.5.2

JDBC driver managers

Table A-4 shows the supported JDBC drivers.
Table A-4 Supported JDBC drivers
JDBC Driver

Which Database Connects

JDBC Driver type

DataDirect Sequelink 5.4

Microsoft SQL Server

DataDirect Connect 3.4

Microsoft SQL Server

IBM WebSphere embedded

Sequelink 5.4

Microsoft SQL Server

IBM WebSphere embedded

Connect3.4

Microsoft SQL Server

Microsoft SQL Server 2000

JDBC Driver 2.2.0037

Microsoft SQL Server

IBM DB2 Universal JDBC 2.2.

or 2.3

IBM DB2

2 or 4

IBM DB2 Legacy CLI JDBC

IBM DB2

IBM Informix JDBC 2.21 JC6

IBM Informix

Oracle 9i JDBC OCI

Oracle 8i and 9i

Oracle 9i JDBC Thin

Oracle 10g JDBC OCI

4
Oracle 9i and 10g

Oracle 10g JDBC Thin

Sybase jConnect 5.5 EBF

11656

Sybase Adaptive Server

OS/400 Java Toolbox JDBC

Driver 4.3

DB2 on iSeries

Web servers
Table A-5 shows the supported Web servers.
Table A-5 Supported Web servers
Apache Server 2.0.49
IBM HTTP Server 2.0.47.1
IBM HTTP Server 6.0
Internet Information Services 5.0 or 6.0
Lotus Domino Enterprise Server 6.0.3 or 6.5.1
Sun Java System Web Server 6.0 SP7 and 6.1 SP1

228

WebSphere Application Server V6 Migration Guide

Appendix B.

Bibliography
The following references were used as sources for much of the work we have done here. You
should consider consulting these references to gather more detail on the subject matter you
need to explore.

IBM Redbooks
For information on ordering these publications, see How to get IBM Redbooks on page 231.
Note that some of the documents referenced here may be available in softcopy only.
Migrating to WebSphere V5.0 An End-to-End Migration Guide, SG24-6910
You should consult this redbook if you are considering a migration directly from V3.5 to V6.
Migrating Applications from WebSphere for z/OS V4 and V3.5 to V5, SG24-7044
You should consult this redbook if you use the WebSphere Application Server on the
z/OS operating system and intend to migrate.
WebSphere Application Server V6 Technical Overview, REDP-3918
WebSphere Application Server V6 System Management and Configuration Handbook,
SG24-6451
This redbook has considerably more detailed information about the system administration
of V6. It also covers new V6 functionality which takes you beyond the realm of migration of
existing applications.
WebSphere Application Server V6 Scalability and Performance Handbook, SG24-6392
WebSphere Application Server V6: Web Services Development and Deployment,
SG24-6461
WebSphere Application Server V6 Security Handbook, SG24-6316
WebSphere Application Server V6: High Availability Solutions, REDP-3971

Copyright IBM Corp. 2005. All rights reserved.

229

WebSphere Application Server Version 6 Information Center

A great deal of the technical information in this redbook is based on information found in the
online documentation guide WebSphere Application Server Version 6 Information Center. We
also refer to this guide as the InfoCenter. You can find the guide at this address:
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp

We cite URLs in the book text that take you directly to the specific article. We hope that the
URL will remain accurate and not change. In the event that the URL changes, you can search
for the article by pasting the article title in the Search bar in the upper left part of the Web
browser window.

Online resources
These Web sites and URLs are also relevant as further information sources:
IBM developerWorks - Technical resources for the WebSphere software platform
The top level address for searching articles is:
http://www.ibm.com/developerworks/websphere

These are articles on the IBM developerWorks site that we cite in the text and we
otherwise recommend:
Meet the Experts: Wayne Beaton on WebSphere Application Server migration
http://www.ibm.com/developerworks/websphere/library/techarticles/0403_beaton/beaton.
html

The Ideal WebSphere Development Environment

http://www.ibm.com/developerworks/websphere/techjournal/0312_beaton/beaton.html

The top 10 (more or less) J2EE best practices

http://www.ibm.com/developerworks/websphere/techjournal/0405_brown/0405_brown.html

Get the message: Messaging in J2EE 1.4

http://www-106.ibm.com/developerworks/java/library/j-getmess/

Plants by WebSphere Sample

http://www.ibm.com/developerworks/websphere/library/samples/WASV501/plantsby.html

Sun J2EE and J2SE documentation

J2EE 1.4 compatibility issues
http://docs.sun.com/source/819-0077/J2EE.html

J2SE 1.4 compatibility issues

http://java.sun.com/j2se/1.4/compatibility.html

J2EE 1.4 specification

http://java.sun.com/j2ee/j2ee-1_4-fr-spec.pdf

J2EE Deprecated APIs

http://java.sun.com/j2ee/1.4/docs/api/deprecated-list.html

JSEE Deprecated APIs

http://java.sun.com/j2se/1.4.2/docs/api/deprecated-list.html

JDBC 3.0 specification

230

WebSphere Application Server V6 Migration Guide

http://java.sun.com/products/jdbc/download.html

J2EE Servlet 2.4 specification

http://java.sun.com/j2ee/1.4/download.html#platformspec

IBM WebSphere Support and downloads

http://www.ibm.com/software/websphere/support/

Supported Hardware and Software for WebSphere Application Server Version 6

http://www.ibm.com/software/webservers/appserv/doc/v60/prereqs/prereq60.html

WebSphere MQ Family support

http://www.ibm.com/software/integration/mqfamily/support/summary/

How to get IBM Redbooks

You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft
publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at
this Web site:
ibm.com/redbooks

Appendix B. Bibliography

231

232

WebSphere Application Server V6 Migration Guide

Index
A
access intent
bean level 34
method level 34
activation specification 48, 58, 216, 223
addNode 114, 139, 143
Administration - other tasks
Disable local OS security 165
Enable security 165
Install JDBCDrivers 165
Ping node and AppServers for current status 166
Regenerate the plug-in configuration 167
Setting the Trace specification 164
Test connections to data sources 166
Administration of configured objects
Display help 162
List actions available on configured objects 163
List the configured server groups 162
Modifying attributes of application server 161
Modifying attributes of enterprise applications 161
Administration of runtime objects 161
administration server 137
administrative console 9, 4849, 94, 96, 101, 109110,
114, 138139, 210, 224
Apache SOAP 22, 32
Apache Struts 31
application extensions 118
Application management
Enterprise Application - edit 161
Enterprise Application - install 159
Enterprise Application - uninstall 161
application server 98
Application Server Toolkit 75
ASTK 7576
asynchronous messaging 9495, 109
automatic migration 109110, 121, 136, 143

B
backup 138
bus
member 52, 55
name 5758

C
C++ 37
capabilities
enabling 7
team 64
cell 96, 114, 139141
cell configuration 85
cell name 104
class
ChainedRequest 33

Copyright IBM Corp. 2005. All rights reserved.

ChainedResponse 33
ChainerServlet 33
ServletChain 33
class loader 114
delegation 115
mode 115
settings 37
classpath 37, 65, 118, 138, 165, 193, 196, 218
ClearCase LT 14
client 7577
clientUpgrade 121, 132
Cloudscape 40, 44
Cluster administration
Clone a ServerGroup 163
Create a server group 163
Remove a clone 164
Start a ServerGroup 163
Stop a ServerGroup 164
Common Connector Framework 35, 85
compatibility 15, 66
backward 15, 67
removing 67
components 74
configuration editor 8
connection factory 56, 95
constraints
authentication 25
security 25
convertScriptCompatibility 121
CORBA 37
CVS 14, 63, 65
repository 63
support 64

D
Data Access Beans 34
Data Direct 7576
data location 150
Data Replication Services 146
data source 110, 171, 174, 179, 219, 223
definition 44
helper class 46
databaseName 47
DB2 7576
debugger 16
default bindings 221
default messaging 109
provider 57
deploy code
generating 48
deployment descriptor 4748
editor 48
ejb-jar.xml 23
web.xml 26

233

webservices.xml 2324, 27
webservicesclient.xml 23
deployment manager 73, 85, 94, 96, 98, 114, 138139,
141, 146
deprecated interface
ConnectionEventListener 34
LazyEnlistableConnectionManager 34
SingleThreadModel 25
deprecated method
addProduct 33
computeProductDirName 33
getAllPoolContents 34
getPoolContents 34
getProductByFilename 33
getProductById 33
getProductDirName 33
getProductNames 33
getProducts 33
loadVersionInfoAsXMLString 33
productPresent 33
removeProduct 33
deprecated package
com.ibm.websphere.j2c 34
com.ibm.websphere.j2c.ConnectionManager 34
com.ibm.websphere.product.buildInfo 33
com.ibm.websphere.product.product 33
com.ibm.websphere.product.WASProduct 34
com.ibm.websphere.security.auth.WSPrincipal 36
com.ibm.websphere.security.auth.WSSecurityContext 36
com.ibm.websphere.security.auth.WSSecurityContextException 36
com.ibm.websphere.security.auth.WSSecurityContextResult 36
com.ibm.websphere.servlet.error.ServletErrorReport 34
com.ibm.websphere.servlet.filter 33
com.ibm.ws.management.descriptor.xml.ConnectionFactory.xml 34
deprecated type
getCredential 36
deprecation 1819, 30
Destinations, 57
development environment 72, 81
development integration 82
development test 81
DOM level 2 37
downtime 81, 8384
Dynamic Web 65

E
EAR 19, 132
EJB 110, 115, 117
EJB 2.1 26
EJBDeploy 222
Enterprise Access Builders 85
exception
MalformedURLException 31
export 4041, 63

234

WebSphere Application Server V6 Migration Guide

F
failover 73

G
getResource 120
getResourceAsStream 120

H
HDRDQX1TMGPROBLEMS 15
HDRDQX1TMGV6NOSHARE 14
HDRDQX1TMGV6REMBKCOMP 15
HDRDQX1TMGV6SERVTARG 14
HDRDQX1TMGV6TACITENG 15
help 9
horizontal migration 89
host name 99, 104
HTTP server 86
HTTP transport 151

I
IBM 4
IBM HTTP Server Version 6 185
IBM Rational Application Developer 4, 14
IBM Rational Web Developer 4
IDE 72
Import 6465
import 41
incompatibility 20, 30
inconsistency 18
incremental migration 18
InfoCenter example 5
installableApps 139
installation 9697, 106, 111, 220221
silent 106
interface
ServletRequest 24
interoperability 85, 87
ISO-8859-1 26

J
J2C Authentication Alias 217
J2EE 18, 86
J2EE Connector Architecture 34
J2EE Connector Architecture 1.5 34
J2EE Hierarchy 40
J2EE Migration Wizard 43
J2EE Perspective 42
JAAS 36
Java Management Extension 34
Java Message Service 28
Java Server Faces 16
JAXP 1.2 37
JAX-RPC 20, 22
JCA adapter 4748
JDBC 30, 7576, 173, 175, 179, 217
provider 45, 138, 218
JDBC 3.0 30

JMS 95, 144

destination 54
provider 56, 109, 176, 181
queue 152
queue connection factory 56, 152, 214
resources 50, 109110, 144, 152153, 171
JMS 1.1 29
JMX 34
JNDI name 49, 5759, 215216, 219, 223
-BindJndiForEJBNonMessageBinding 161
change 161
destination 48
JSF 16
JSP
EL expressions 26
isELIgnored 26
pageEncoding 26
JSP 1.2 25
JSP 2.0 25
JSP tsx tag 35
JSR 109 22
JSR-101 22
JSR-109 22
JSTL 1.0 26

L
launchpad 97, 100, 111, 185
license 72, 98
Listener port 223
ListenerPort 47
local 186

M
mail
provider 49
session 49
maintenance windows 81
MalformedURLException 120
Mapping
wscp 4.0 to wsadmin 5.0 157
MDB
listener bindings 223
listener port 183, 185
Message Driven Beans 26, 28
messaging provider 58
method
getLocalAddr 24
getLocalName 24
getLocalPort 24
getRemotePort 24
getResource 31
getResourceAsStream 31
getStackTrace 34
sessionDestroyed 24
migratewsgw 145
migrating
workspaces 14
Migrating from Version 4.0 to 5.0
wscp 157

MIME filtering 33
mixed version 85
cell 140, 142143, 146
module visibility 116
multi-broker 146
multiple 117
MyBank 171
MyBankMDB 175, 178

N
nd_content 77
ndprod 73
newpme 74
node 139, 141
node agent 98, 114, 141
node name 99, 104, 137, 139, 141
node scope 56

O
OASIS 145
object
AuthenticationMechanism 29
ConfigurationProperties 29
ConnectionDefinition 29
ContextParam 25
customAuthMechType 29
OutboundResourceAdaptor 29
ParamValue 25
ResourceAdaptor 29
SecurityPermission 29
org.apache.xalan 37
org.apache.xerces 37

P
PARENT_LAST 115
perspective 6
switcher 6
pkover 74
Plants By WebSphere 40
plug-in 7577, 94, 96, 101, 141, 143, 185186
configuration file 101, 111, 187189
PMI Client 34
port 99100, 104, 109
preferences 6465
prependSlashToResource 120
pre-production 84
process definition 151
prodfeats 73
prodoffer 72
production 81
profile 73, 96, 98, 101, 103
creation wizard 99, 102, 210
custom 114
deployment manager 101
Programming Model Extensions 36, 74
project
interchange 15
navigator 63

Index

235

property 65
prependSlashToResource 31

Q
Queue 213, 215
queue connection factories 182
queue connection factory 176, 181
queue destination 176, 181, 183
queue destinations 182
Queue Name 215

R
Redbooks Web site 231
Contact us xii
Remote 186
Remote Agent Controller 9
response file 106, 108
risk 8081

S
SAAJ 20
SAX 2.0 37
SCM 81
SDO 16, 34
security 35, 217
SEI 27
server
group 139
targeting 14, 42
view 48
Server administration
Connect to remote server 159
Create a new application server 158
Remove an application server 159
Start an application server 158
Stop an application server 158
server configuration 8
editor 49
server overview 8
service 105
Service Data Objects 16, 34
service integration 50, 145, 211
bus 95
service-level agreements 84
Services 100
services 100
Servlet 2.3 24
Servlet 2.4 24
shared library 118119, 138
SI Bus 95, 180, 183, 211
destination 183
SIBJMS 152
silos 86, 88
single 117
SOAP 22, 145
SOAP Message Security 145
startManager 112
startNode 113

236

WebSphere Application Server V6 Migration Guide

startServer 112
Stateless Session Beans 26
stopManager 113
stopNode 113
stopServer 112
superceding interface
LazyAssociatableConnectionManager 34
superceding method
getBuildDate 34
getBuildLevel 34
getName 34
getStackTraceAsString 35
getVersion 34
getWasLocation 33
getWASProductInfo 33
getWASProductInfoInstances 33
isThisProductInstalled 33
showPoolContents 34
whoAllPoolContents 34
superceding package
com.ibm.websphere.product.WASDirectory 33
com.ibm.websphere.security.auth.WSSubject 36
javax.servlet.filter 33
superceding type
getCallerSubject 36
getRunAsSubject 36
synchronize 63
System Integration Bus 95, 152

T
tag library 25
test environment 48, 60
testing
performance 81, 83
system 8283
Tivoli Access Manager 77
Tivoli Directory Server 77
transaction isolation level 119
transaction log 150
TRANSACTION_READ_COMMITTED 119
TRANSACTION_REPEATABLE_READ 119

U
UDDI 146
UDDI Registry 32
UDDI Utility 32
UDDI Version 2 146
UDDI Version 3 146
UDDI4J 32
unified connection factory 95

V
V5 default messaging 109
v6opmodel 73
validator 25
validators 43
visibility 116
Visual Java GUI 4

W
WAR 117
WASPostUpgrade 121, 124, 136137, 173, 178
compatibility 151
WASPreUpgrade 121122, 136137, 172173, 177
wasprofile 105
WDO 16
web container 120
web module 117
web server 94, 100101, 141, 143, 186
configuration 188
web services 22
secure 24
Security Draft 13 33
Web Services Gateway 144
WebSphere Bindings 48
WebSphere MQ 5.3 144
WebSphere Studio Application Developer Version 5 4
WebSphere Studio Site Developer 4
WebSphere test server 5
workload
balancing 73
management 87
workspace 15, 41, 64
wsadmin 144, 150
AdminConfig 150151
HTTPTransport 151
processDef 151
processDefs 151
recoveryLogs 150
securityoff 165
securityon 165
ServerEntry 150
TransactionService 150
wscp
ApplicationServer 158159
DrAdmin 164
EnterpriseApp 161
help 162
JDBCDriver 165
Node 167
SecurityConfig 165
ServerGroup 162
set 159
wscp.hostname 159
wsinstance 101
WS-Security 145

service-endpoint-interface 27
service-impl-bean 27
service-qname 23
service-ref 23
soap-header 23
subscriptionDurablity 28
web-app 23
webservice-description 24
wsdl-port 23
XSLT 37

X
Xerces 37
XML element
acknowledgeMode 28
activation-config 28
component-scoped-refs 23
destinationType 28
jaxrpc-mapping-file 24
localpart 23
messageSelector 28
namespaceURI 23

Index

237

238

WebSphere Application Server V6 Migration Guide

WebSphere Application Server V6

Migration Guide

WebSphere Application Server V6

Migration Guide
WebSphere Application Server V6 Migration Guide

WebSphere Application Server V6 Migration Guide

(0.2spine)
0.17<->0.473
90<->249 pages

WebSphere Application Server V6

Migration Guide

WebSphere Application Server V6

Migration Guide

Back cover

WebSphere Application
Server V6 Migration Guide
Application developer
migration tasks
System administrator
migration tasks
Migration examples

This IBM Redbook has been written to assist you in the migration of
your WebSphere Application Server installation. The end-to-end
migration path includes the migration of the development environment,
the test/integration environment, and the production environment
using software engineering methodologies. This guide presents the
best practices in migration strategy and planning, migration tools, and
practical migration examples.

INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION

The following Version 6 products are covered:

IBM Rational Application Developer for WebSphere Software
IBM Rational Web Developer for WebSphere Software
WebSphere Application Server
WebSphere Application Server Express
WebSphere Application Server Network Deployment

BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL 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
SG24-6369-00

ISBN 0738492450