null null

Front cover
Migrating WebLogic
Applications to WebSphere
Advanced Edition V4
Understanding migration issues and
preparing a migration strategy
Guidelines for writing portable
applications
Completing and implementing
a migration
Bill Moore
Wayne Beaton
Kiran Gawde
Leigh Power
Marcos Serrano Timonet
Hai Tao Wang
ibm.com/redbooks
International Technical Support Organization
Migrating WebLogic Applications to WebSphere
Advanced Edition V4
July 2002
SG24-6179-00
Take Note! Before using this information and the product it supports, be sure to read the
general information in “Notices” on page ix.
First Edition (July 2002)
This edition applies Version 4 of WebSphere Application Server, Advanced Edition for use with
Windows NT and Windows 2000 Server.
Comments may be addressed to:
IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 662
P.O. Box 12195
Research Triangle Park, NC 27709-2195
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2002. All rights reserved.
Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is subject to
restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Our objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Practical migration guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2 More adaptable applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.3 Future guidance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.4 Major update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Our focus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.1 J2EE applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.2 Java technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2.3 Application artifacts and dependencies. . . . . . . . . . . . . . . . . . . . . . . . 9
1.2.4 Migration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.2.5 Migration tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.3 How to use this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Chapter 2. Features comparison and migration strategy . . . . . . . . . . . . . 17
2.1 WebSphere and WebLogic servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2 Feature comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.2.1 J2EE 1.2 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.2 J2EE 1.3 preview technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2.3 J2EE 1.3 and beyond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.2.4 Non-J2EE dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.3 Migration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.3.1 The basic steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.3.2 Project planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Chapter 3. Installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.1 Platform used for migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.1.1 Development machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.1.2 Testing machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.2 Products installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.2.1 IBM UDB V7.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
© Copyright IBM Corp. 2002
iii
3.2.2 BEA WebLogic Server V6.1 SP2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.2.3 WebSphere Application Server V4 . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.2.4 WebSphere Studio Application Developer V4.0.2. . . . . . . . . . . . . . . 62
Chapter 4. Development and migration tools . . . . . . . . . . . . . . . . . . . . . . . 67
4.1 WebSphere Studio Application Developer . . . . . . . . . . . . . . . . . . . . . . . . 68
4.1.1 Overview of WebSphere Studio Application Developer . . . . . . . . . . 68
4.1.2 J2EE perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4.1.3 Setup test server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
4.2 Tools shipped with WebSphere. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.2.1 Application Assembly Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.2.2 EJBDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
4.3 VisualAge for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
4.4 WebSphere Studio (classic) and other JSP editors . . . . . . . . . . . . . . . . 107
4.5 Other tools from third parties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.5.1 Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.5.2 JUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Chapter 5. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
5.1 Elements of security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
5.2 What does J2EE specify? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
5.3 Security differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.3.1 Authentication mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.3.2 Data integrity and privacy. Configuring SSL . . . . . . . . . . . . . . . . . . 117
5.4 WebSphere Studio Application Developer approach . . . . . . . . . . . . . . . 120
5.5 AAT approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5.6 Deploying the secure EAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Chapter 6. Transaction management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.1.1 Non JTA transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6.1.2 JTA transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.2 Migrating WebLogic extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.3 The future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Chapter 7. Naming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
7.1 J2EE JNDI naming context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
7.1.1 Java code for JNDI lookups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
7.1.2 Standard deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.2 Local and global JNDI names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
7.3 Extended deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
7.3.1 WebLogic extended descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
7.3.2 WebSphere extended descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 158
7.4 JNDI migration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
iv
Migrating WebLogic Applications to WebSphere Advanced Edition V4
7.4.1 Name overloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.2 Portable EJB and resource references . . . . . . . . . . . . . . .
7.4.3 Conversion of WebLogic deployment descriptors . . . . . . .
7.4.4 Conversion of WebLogic RMI . . . . . . . . . . . . . . . . . . . . . .
7.4.5 The ejb-link alternative . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5 Future importance of JNDI . . . . . . . . . . . . . . . . . . . . . . . . . . . .
......
......
......
......
......
......
.
.
.
.
.
.
160
161
164
165
170
171
Chapter 8. Java Servlets and JavaServer Pages . . . . . . . . . . . . . . . . . . . 173
8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
8.2 Differences in deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 174
8.2.1 Strict servlet-mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
8.2.2 Validation of web.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
8.2.3 Proprietary deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . 175
8.3 Migration examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
8.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
8.3.2 Java Servlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
8.3.3 JavaServer Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
8.4 JSP migration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.4.1 Tag libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.4.2 JSP expression tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
8.4.3 Parameter settings for JavaServer Pages . . . . . . . . . . . . . . . . . . . 184
8.5 Deploying the Web application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
8.5.1 WebSphere Studio Application Developer approach . . . . . . . . . . . 187
8.5.2 AAT approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
8.5.3 Deploying the EAR resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
8.6 Future specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
8.6.1 Java Servlets 2.3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
8.6.2 JavaServer Pages 1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Chapter 9. Enterprise JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
9.1 EJB 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
9.2 Coding differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
9.2.1 Type narrowing with PortableRemoteObject. . . . . . . . . . . . . . . . . . 198
9.2.2 T3 protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
9.2.3 InitialContext constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
9.3 Deployment descriptor differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
9.4 Application Assembly Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
9.5 WebSphere Studio Application Developer . . . . . . . . . . . . . . . . . . . . . . . 214
9.5.1 WebSphere Studio Application Developer projects . . . . . . . . . . . . 214
9.6 Entity beans with container-managed persistence . . . . . . . . . . . . . . . . . 218
9.6.1 CMP field mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
9.6.2 BEA WebLogic Server CMP EJB finder queries . . . . . . . . . . . . . . . 219
9.6.3 Modified property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Contents
v
9.7 Mapping CMP entity bean fields with WebSphere Studio Application
Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Chapter 10. Database connectivity and persistence . . . . . . . . . . . . . . . . 229
10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
10.2 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
10.3 DataSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
10.3.1 Binding a DataSource to a naming service . . . . . . . . . . . . . . . . . . 233
10.3.2 Connecting to a DataSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
10.3.3 Connection pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
10.3.4 Available drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
10.3.5 Migration issues when changing JDBC drivers or databases . . . . 237
10.3.6 Summary: Writing portable JDBC applications . . . . . . . . . . . . . . . 238
10.4 jDriver (jdbcKona) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
10.5 dbKona . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
10.6 Business objects - persistence frameworks . . . . . . . . . . . . . . . . . . . . . 241
10.6.1 Container-managed persistence (CMP) entity beans . . . . . . . . . . 242
10.6.2 Bean-managed persistence (BMP) entity beans. . . . . . . . . . . . . . 243
10.6.3 TopLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
10.6.4 Other persistence managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Chapter 11. Application assembly and deployment . . . . . . . . . . . . . . . . 245
11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
11.2 Application assembly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
11.2.1 Packaging components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
11.2.2 Packaging an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
11.3 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
11.4 Migrating deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
11.4.1 Application deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . 257
11.4.2 EJB deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
11.4.3 Web deployment descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Chapter 12. Migration examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
12.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
12.2 Pet Store example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
12.2.1 Syntax problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
12.2.2 Classpath problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
12.2.3 Conversion to DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
12.2.4 Complete deployment descriptors. . . . . . . . . . . . . . . . . . . . . . . . . 283
12.2.5 Deploy to test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
12.2.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
12.3 Trade2 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
12.3.1 Trade2 in WebSphere Studio Application Developer . . . . . . . . . . 289
12.3.2 Using WebLogic deployment descriptors . . . . . . . . . . . . . . . . . . . 292
vi
Migrating WebLogic Applications to WebSphere Advanced Edition V4
12.3.3 Top-down RDB mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
12.3.4 Create finder methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
12.3.5 Deploy and run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
12.3.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
12.4 Banking example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
12.4.1 Deploying on BEA WebLogic Server . . . . . . . . . . . . . . . . . . . . . . 302
12.4.2 Importing into WebSphere Studio Application Developer . . . . . . . 305
12.4.3 Error analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
12.4.4 Migrating deprecated and proprietary features . . . . . . . . . . . . . . . 307
12.4.5 Writing deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
12.4.6 Meet-in-the-middle RDB mapping . . . . . . . . . . . . . . . . . . . . . . . . . 310
12.4.7 Generating RMI stubs and ties . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
12.4.8 Testing application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
12.4.9 Deploying banking EAR on WebSphere . . . . . . . . . . . . . . . . . . . . 313
12.4.10 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
12.4.11 Additional materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
System requirements for downloading the Web material . . . . . . . . . . . . . 320
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Related publications . . . . . . . . . . . . . . . . . . . . . .
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . .
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . .
IBM Redbooks collections . . . . . . . . . . . . . . . . .
......
......
......
......
......
.......
.......
.......
.......
.......
......
......
......
......
......
.
.
.
.
.
323
323
323
325
325
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Contents
vii
viii
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area.
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However, it is the user's
responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may
make improvements and/or changes in the product(s) and/or the program(s) described in this publication at
any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm
the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on
the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrates programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the
sample programs are written. These examples have not been thoroughly tested under all conditions. IBM,
therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to IBM's application
programming interfaces.
© Copyright IBM Corp. 2002
ix
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Redbooks(logo)™
BookMaster®
CICS®
DB2®
DB2 Connect™
DB2 Universal Database™
e Strategy™
IBM®
Informix®
MQSeries®
Netfinity®
Perform™
Redbooks™
SecureWay®
SP™
SP2®
TXSeries™
VisualAge®
WebSphere®
The following terms are trademarks of International Business Machines Corporation and Lotus Development
Corporation in the United States, other countries, or both:
Lotus®
Domino™
Notes®
The following terms are trademarks of other companies:
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United
States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure
Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service marks of others.
x
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Preface
This redbook will help you plan and execute the migration of Java 2 Platform,
Enterprise Edition (J2EE) applications developed for BEA WebLogic Server, so
that they will run on WebSphere Application Server, Advanced Edition V4. This
redbook is an update of the redbook Migrating WebLogic Applications to
WebSphere Advanced Edition, SG24-5956.
Since the previous redbook was published, new versions of both WebLogic and
WebSphere have been released and both products have been certified as
complying with the Java 2 Platform, Enterprise Edition specification. We discuss
the major differences between these new implementations of WebLogic and
WebSphere, provide guidance to developers on how to deploy existing WebLogic
applications on WebSphere, and discuss how to design new J2EE applications
that will be portable for deployment on WebSphere or WebLogic.
The team that wrote this redbook
This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, Raleigh Center.
Bill Moore is a WebSphere Specialist at the International Technical Support
Organization, Raleigh Center. He writes extensively and teaches IBM classes on
WebSphere and related topics. Before joining the ITSO, Bill was a Senior AIM
Consultant at the IBM Transarc lab in Sydney, Australia. He has 17 years of
application development experience on a wide range of computing platforms and
using many different coding languages. He holds a Master of Arts degree in
English from the University of Waikato, in Hamilton, New Zealand. His current
areas of expertise include application development tools, object-oriented
programming and design, and e-business application development.
Wayne Beaton is a Senior Software Consultant with Software Services for
WebSphere, part of the IBM Software Group. Wayne’s diverse roles involve him
in a wide range of activities, from the WebSphere skills transfer and migration
programs to general consulting.
Kiran Gawde is a Senior Software Engineer at Object Edge, Inc, a custom
software development company based in Walnut Creek, CA. Kiran has over six
years’ experience developing distributed systems using various technologies
including Java, Smalltalk, Lotus Domino, XML, relational databases and
application servers. Kiran has been a key player in many successful large-scale
© Copyright IBM Corp. 2002
xi
projects, and he has extensive experience in object-oriented technologies and
e-business applications, especially in component-based and services-oriented
solutions. His latest focus has been the application of object-oriented design
solutions to Web-enabled applications. Kiran holds a Bachelor of Engineering
(B.E.) in Computer Science from Bombay University, India.
Leigh Power is an independent Java training consultant. He has over 30 years of
experience in software research and development, specializing in programming
languages and object-oriented systems. He has been a research staff member at
both the T.J. Watson Research Center and the MCC Research Consortium. He
currently runs his own company, Power Assist, Inc. in Coupeville, WA, USA.
Marcos Serrano Timonet is an I/T Specialist with IBM Global Services in Spain.
He designs and implements Web-based e-business solutions, including banking
applications and customer relationship management systems (CRM) solutions
for the telecommunications industry. Marcos has three years of application
experience developing and administering applications for Web application
servers. Marcus holds a degree in mathematics from UNED Spain.
Hai Tao Wang is an Advisory I/T Specialist with the IBM Software Group in
Beijing, P. R. China. He joined IBM after graduation from university and has four
years of experience in application integration and middleware, focusing on J2EE
and transaction processing systems. He currently provides technical support for
WebSphere Application Server, TXSeries, CICS, and MQSeries in China.
The authors: Kiran Gawde, Leigh Power, Hai Tao Wang, Marcos Serrano Timonet, Bill
Moore. Absent: Wayne Beaton
xii
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Thanks to the following people for their invaluable contributions to this project:
Roman Kharkovski
IBM Pittsburgh
Tom Musta
IBM Rochester
Notice
This publication is intended to help developers migrate Java 2 Platform,
Enterprise Edition applications from BEA WebLogic Server to WebSphere
Application Server, Advanced Edition V4. The information in this publication is
not intended as the specification of any programming interfaces that are provided
by WebSphere Application Server, Advanced Edition V4. See the
PUBLICATIONS section of the IBM Programming Announcement for WebSphere
Application Server, Advanced Edition V4 for more information about what
publications are considered to be product documentation.
Comments welcome
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Send us your comments
about this or other Redbooks in one of the following ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an Internet note to:
[email protected]
򐂰 Mail your comments to the address on page ii.
Preface
xiii
xiv
Migrating WebLogic Applications to WebSphere Advanced Edition V4
1
Chapter 1.
Introduction
This chapter describes our objectives, our focus, and who can benefit from the
content of this book. We outline the structure of a Java 2 Platform, Enterprise
Edition (J2EE) application and introduce issues encountered during migration.
© Copyright IBM Corp. 2002
1
1.1 Our objectives
The IBM WebSphere Application Server, Advanced Edition, and the BEA
WebLogic Server are the leading, high-end, Java-based, enterprise application
server products on the market. Both of these products offer robust support for
complex Web-based enterprise applications. Both products comply with Java 2
Platform, Enterprise Edition (J2EE) specifications. As the J2EE specification
evolves, IBM and BEA will continue to support future versions of this important
industry standard.
Application portability is a major goal of the J2EE standard. Ideally, an enterprise
application written according to the J2EE specification is portable to any
compliant server supporting the same version of the J2EE specification. This is
an enormous advance over the early days of proprietary transaction monitors
where applications were completely non-portable between vendors. However,
the fact that an application runs on one compliant J2EE server does not
guarantee that it will run on other compliant servers without modification.
Application portability involves many issues. We address these issues in the
context of a pragmatic guide to the migration of enterprise applications from BEA
WebLogic Server to WebSphere Application Server, Advanced Edition V4.
Although adhering to the J2EE standard conveys a high degree of portability, the
migration of a large enterprise application is still an expensive undertaking.
Moreover, the typical enterprise application will be modified and migrated
multiple times throughout its life. The cost of these migrations, upgrades, and
modifications can be substantially reduced by making your applications more
adaptable to future changes. We provide some guidance on making J2EE
applications more adaptable. We cannot predict the future, but we do provide
guidance on expected changes to the J2EE specifications and their future
support.
Our three major objectives are as follows:
1. Provide a practical guide for migrating from BEA WebLogic Server to
WebSphere Application Server, Advanced Edition V4
2. Promote more adaptable applications
3. Give guidance on future J2EE servers
If some of this sounds familiar, you may have seen our previous redbook,
Migrating WebLogic Applications to WebSphere Advanced Edition, SG24-5956.
This is the second in a series. The current book is a major update to this earlier
redbook.
2
Migrating WebLogic Applications to WebSphere Advanced Edition V4
1.1.1 Practical migration guide
An enterprise application is a collection of several different kinds of artifacts.
These include Java source, class, and JAR files, deployment descriptors, and
generated code. These artifacts use a wide variety of Java technologies. These
include Java Servlets, Enterprise JavaBean (EJB), Java Naming and Directory
Interface (JNDI), and JavaServer Pages (JSP). In general, a migration issue is
something that may require an artifact to be changed as part of the migration
effort. Each kind of artifact and each Java technology has its own set of potential
migration issues. One migration issue may be resolved by a source code change,
while another may require reconstructing deployment descriptors with a new tool.
As a practical guide, we have collected together migration issues you are likely to
encounter in a typical migration project. We show how to identify each issue, offer
one or more alternative solutions, and guide you through the migration process.
Since different tools are useful for solving different kinds of migration issues, we
also recommend the tools best suited to each task. We have collected migration
issues based on the authors’ collective experience, and from the examples used
to write this book. We believe that examples are particularly effective in
explaining the details of migration issues and their resolution.
1.1.2 More adaptable applications
It is common to have some vendor dependencies in an enterprise application.
However, an application that has no obvious vendor dependencies, and that
follows the J2EE specification precisely, may still require source code
modifications. There are a surprising number of ways to write non-portable code
even while following the specification. See 1.2.4, “Migration issues” on page 10
for more details. Given that you have to change the source code for migration,
this is an excellent time to invest a little more effort and make the same piece of
code more adaptable to future changes.
Instead of attempting to write portable applications, we encourage writing
adaptable applications. An application is considered to be adaptable if it is written
in anticipation of future changes. Writing adaptable code admits to the fact that
future source modifications are inevitable, so attempt to reduce their impact,
whatever they may be. By comparison, the writing of a portable application
simply focuses on carefully conforming to current specifications in the hope that it
will not have to change. Adaptability goes beyond simple J2EE portability.
Adaptable applications are discussed under “Best practices” on page 32.
Chapter 1. Introduction
3
1.1.3 Future guidance
The J2EE and related Java standards are evolving at a rapid pace. Even if you
are not planning a migration project, it may be important to become aware of
future standards developments. To help you prepare for the future, each chapter
in this book includes a preview of expected changes to the relevant technologies.
You can expect server products to support the new specifications after a modest
lag time.
Be cautious when tracking draft specifications. They sometimes change
significantly by their final release, making it imprudent to invest heavily in early
drafts. The new EJB query language (EJB QL), for example, changed radically
late in the EJB 2.0 specification cycle, making earlier implementations obsolete.
1.1.4 Major update
We do not assume that you have read our earlier guide, Migrating WebLogic
Applications to WebSphere Advanced Edition, SG24-5956, but we may refer you
to sections that are still relevant. We do assume that you are familiar with BEA
WebLogic Server, V5.1 or V6.1. We assume you are somewhat familiar with
WebSphere Application Server, Advanced Edition V4. We also assume that you
are familiar with the J2EE and related Java specifications, but do provide specific
details as they relate to particular migration issues.
A lot has changed since we wrote Migrating WebLogic Applications to
WebSphere Advanced Edition, SG24-5956. Its migration target was WebSphere
Application Server, Advanced Edition V3.5. Neither BEA WebLogic Server V5.1
nor WebSphere Application Server, Advanced Edition V3.5 were fully compliant
with J2EE 1.2 at that time. Today, both BEA WebLogic Server V6.1 and
WebSphere Application Server, Advanced Edition V4 have been certified as
J2EE compliant products.
The major technical issues of the first migration guide were:
򐂰 Deployment in the absence of EAR files
򐂰 Retrofitting V1.1 EJBs, and their deployment descriptors, to the V1.0 level
With full J2EE 1.2 compliance, these are no longer issues. For this guide, we
have added chapters on additional J2EE technologies and enhanced our preview
of future changes. The tools set has changed also. VisualAge for Java,
Enterprise Edition V3.5 was used in the first migration guide, but WebSphere
Studio Application Developer V4 is a more effective tool for WebSphere
Application Server, Advanced Edition V4.
As you will discover, the major technical issues in this migration guide are:
򐂰 Learning to use the new WebSphere tools set
4
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 Migrating vendor-specific deployment descriptors
򐂰 Constructing and deploying EAR files
1.2 Our focus
This guide is intended for developers and system administrators tasked with
migrating applications from BEA WebLogic Server V6.1 to WebSphere
Application Server, Advanced Edition V4. We use the latest release,
Version 4.02, of WebSphere Application Server, Advanced Edition. This guide is
also useful for migrating from BEA WebLogic Server V5.1. This guide may also
be useful for other technical professionals who wish to evaluate, plan, and
manage migration projects in the near future. In this book, we focus specifically
on migration tasks and do not cover general server configuration, optimization,
and maintenance issues. See the redbook IBM WebSphere V4.0 Advanced
Edition Handbook, SG24-6176 for details on server configuration and
management.
Our primary focus is on applications that are compliant with the J2EE 1.2
specification. Since the J2EE 1.2 standard specifies, in detail, the structure and
interfaces of enterprise applications, it significantly reduces the need for major
code modifications during migration. It is assumed that you are familiar with this
specification and related Java technologies.
Most applications also have some pieces that fall outside the scope of the J2EE
1.2 specification. Some of these may require changes during migration. We try to
address those incompatibilities that are commonly encountered in applications
running on BEA WebLogic Server V6.1 and V5.1. See Migrating WebLogic
Applications to WebSphere Advanced Edition, SG24-5956 for information on the
degree of J2EE 1.2 compliance of BEA WebLogic Server V 5.1.
The focus of any migration project is to discover and fix software artifacts that are
incompatible with the target environment. The bulk of this guide is devoted to
helping you identify and resolve incompatibilities that arise during migration.
Since using the best available tools significantly reduces this effort, we also focus
on those tools.
Finally, we provide a road map for staging a migration project. Learning how to
use tools and doing things in the right order reduces cost and improves quality.
When modifying application source code, the overall quality of the finished
product also improves with the use of best practices, along with knowledge about
future J2EE features.
Chapter 1. Introduction
5
1.2.1 J2EE applications
J2EE applications have a lot of parts. Figure 1-1 on page 7 depicts a four-tier
application, typical of WebSphere Application Server and BEA WebLogic Server:
1. A browser-based tier for user interface using the HTTP protocol.
Java applications can also interact directly with the Enterprise JavaBean
server.
2. A server-side front-end tier that manages user sessions and translates HTTP
requests into method calls on business objects in the enterprise server.
Java Servlets and JavaServer Pages are used to implement this component
in conjunction with a traditional Web server. One or more firewalls (not shown)
are typically present for system security.
3. An object-oriented business logic tier implemented using Enterprise
JavaBeans.
The Enterprise JavaBeans are mapped onto the underlying database and
legacy systems. Multiple Enterprise JavaBeans servers may be
interconnected, both locally or remotely, to form complex distributed
object-oriented systems. These servers support distributed transactions to
maintain data integrity across remote databases. EJBs and their databases
are located by means of JNDI lookups.
4. A back-end database tier, sometimes including legacy systems.
J2EE uses the concept of containers to separate application business logic from
server-provided services such as security, database mapping, transactions, load
balancing, and network communications. There are four kinds of containers:
applet, application, Web, and EJB. Your application implements just the business
logic. All other services are handled for you by the vendor-provided J2EE
server’s containers. Application components are organized into EAR files, which
are deployed into containers using deployment descriptors and deployment tools.
6
Migrating WebLogic Applications to WebSphere Advanced Edition V4
EAR
WAR
HTML
Servlet
JSP
JAR
EJB
Home
Remote
J2EE Application
Server
Client
Tier 1
Browser
Applet
Deployment
Tools
Web
Container
HTML/XML
Enterprise
Info Tier 4
2
JDBC DataSource
Tag
Lib
JSP
Servlet
R
M
I
I
I
O
P
T
r
a
n
s
a
c
t
i
o
n
EJB
Container
M
o
n
i
t
o
r
Database
System
3
Legacy
Java
Application
RMI-IIOP
Session
Bean
Entity
Bean
JDBC DataSource
Lookup properties, resources,
EJBs
env
Context
JNDI
DataSource
Server
EJB Home
Figure 1-1 Typical J2EE enterprise application architecture
1.2.2 Java technologies
The J2EE 1.2 specification depends on a collection of other Java technologies.
Table 1-1 on page 8 lists these technologies, along with their minimally required
specification levels. Compliant products may actually support later versions of
these technologies. See Chapter 2, “Features comparison and migration
strategy” on page 17 for the actual version levels supported in the WebSphere
Application Server, Advanced Edition and BEA WebLogic Server products. A
Chapter 1. Introduction
7
preview of the J2EE 1.3-dependent specifications is also shown in Table 1-1.
Note that Java 2 Platform, Standard Edition (J2SE) includes JDBC Core and
Java IDL in both J2SE 1.2 and 1.3. As you can see, both J2SE and EJB have
major upgrades in J2EE 1.3. Look for additional preview information in the
relevant chapters of this guide.
Looking ahead even further to J2EE 1.4, expect to find support for Web services,
and possibly client-side deployment: Java API for XML Messaging (JAXM and
JAX-RPC), and Java Network Launching Protocol (JNLP), respectively.
A J2EE application server must support the minimal release level for each
technology. Moreover, J2EE restricts the way in which some of its dependent
technologies can be used. For example, even though threads are a part of the
J2SE technology, you cannot use threads in EJBs. Although violating one of
these restrictions may not cause a problem on your current server, it is not legal
and is likely to cause future migration problems.
Table 1-1
Java APIs required by the J2EE specification
Technology
J2EE 1.2
J2EE 1.3
Java 2 Platform, Enterprise Edition (J2EE)
1.2
1.3
Enterprise JavaBeans (EJB)
1.1
2.0
JavaServer Pages (JSP)
1.1
1.2
Java Servlets
2.2
2.3
Java Authentication and Authorization
Service (JAAS)
8
1.0
Java Activation Framework (JAF)
1.0
1.0
JavaMail
1.1
1.2
Java API for XML Parsing (JAXP)
1.1
J2EE Connector Architecture (JCA)
1.0
JDBC Standard Extension (JDBC)
2.0
2.0
Java Message Service (JMS)
1.0
1.0
Java Naming and Directory Interface (JNDI)
1.2
part of J2SE 1.3
Java Transaction API (JTA)
1.0
1.0
RMI/IIOP
1.0
part of J2SE 1.3
Migrating WebLogic Applications to WebSphere Advanced Edition V4
1.2.3 Application artifacts and dependencies
One of the first steps in a migration effort is to identify all of the software artifacts
needed by your application. There usually turns out to be more artifacts and
dependencies than you first expect. Identifying the dependencies is often an
iterative process, so be prepared for the fact that you may miss some
dependencies the first time around. If you do not find all of the dependencies,
they will eventually find you. We can classify migration artifacts into the following
categories:
1. J2EE artifacts
These are usually pretty obvious and easy to find.
– Java source code for Java Servlets, EJBs, client applets and applications,
and various support packages that make up the application itself. It is a
good idea to collect both the Java source and class files, and of course,
include the javadoc files and any other documentation that you can find.
– JavaServer Pages, tag libraries, and HTML files for the Web server.
– You should also identify the specific J2EE services and other Java
technologies that your application depends upon. Java include statements
and JAR files provide clues for these dependencies.
2. Application configuration artifacts
These include the information needed to configure your application in the
server. Much, but not all, of this is captured by standard J2EE deployment
descriptors.
– J2EE deployment descriptors for EJBs and Web components. These are
the XML files inside EAR and WAR archives. They specify the
configuration of an application’s parts, along with its DataSources,
environment variables, and security roles.
– Vendors typically need additional deployment information to manage JNDI
names, database access, security details, and classpaths for their servers.
Since the J2EE specification is silent on this information, vendors can
provide it any way they choose. Adding XML style deployment descriptors
to EAR archive files has become common practice, but some of this
information may be provided through properties files and the like.
– Since the Java code generated from deployment descriptors is server
dependent, it will be completely replaced during the migration effort.
Chapter 1. Introduction
9
3. Non-J2EE artifacts
Many applications depend on features and components provided by the
server vendor or a third party. Such support is generally outside of the scope
of the J2EE specification. The software artifacts supporting these features
may not be available in your target environment, but they should be noted as
dependencies.
– Server vendor dependencies
These can often be identified by the use of vendor-specific class libraries
and Java include statements. Server properties files may also hold clues
to these dependencies.
– Third-party dependencies
Similarly, look for class libraries and Java include statements. A third party
may only provide class (or object) libraries with no source code.
– Third-party or vendor plug-ins, such as browser or security plug-ins
These may be more difficult to find. Look in configuration and initialization
files.
4. Databases
Applications usually depend on one or more databases or network-based
services. Their artifacts include:
– Vendor-provided drivers
– Communication protocol support
– Database engines
5. Tools
In addition to runtime artifacts, your application depends on the tools used to
develop and maintain it and its databases.
– Tools provided by the vendor of your server product
– Third-party tools used to build and maintain your application
– Application-specific scripts and programs used to build your application
and maintain its databases
1.2.4 Migration issues
Each of the different types of artifacts mentioned in 1.2.3, “Application artifacts
and dependencies” on page 9 has its own way of being incompatible with a new
target server environment. A few common examples of incompatibilities are
mentioned here. In general, an artifact’s incompatibilities are limited only by the
10
Migrating WebLogic Applications to WebSphere Advanced Edition V4
creativity of its developer. To the extent that your application follows the J2EE
standards, migration issues will be reduced. Deviating from the standards, or
exploiting vendor-specific packages or features, will make the migration effort
more complex.
1. J2EE artifacts
– Version mismatch
Different vendors may support different versions of the Java technologies,
even though they support the same J2EE version. This may be a problem
if your application takes advantage of newer features that are not
supported in the target vendor’s server. For example, as a J2EE 1.2
compliant server, BEA WebLogic Server V6.1 supports JSP 1.1. As a
preview technology, it also supports a draft version of the JSP 1.2
specification. If your JSPs depend on JSP features introduced with JSP
1.2, they are incompatible with the standard JSP 1.1 support of
WebSphere Application Server, Advanced Edition V4, even though it is
also a J2EE 1.2 compliant server.
– Java technology restrictions
Some J2EE programming restrictions are not required to be enforced by
the vendor. Invalid code that happens to work on one server may become
a migration issue.
– J2EE openness
Many things are left unrestricted in the J2EE specifications. This allows
vendors flexibility, but it also causes unexpected incompatibilities. For
example, the case of the names returned by the
HttpServletRequest.getHeaderNames method is not specified. If your
application relies on mixed case, for example, it may work on BEA
WebLogic Server V1.6, but will be incompatible with the all lowercase
implementation found in WebSphere Application Server, Advanced Edition
V4.
– Minor differences in interpretation
Differences in the J2EE specifications, which may not be explicitly covered
by J2EE compliance testing, occasionally result in application
incompatibilities.
2. Application configuration artifacts
– Since vendor-specific deployment discriptors are not governed by the
J2EE specification, they are incompatible between different vendor
products. Some of their contents may be similar, but the detailed formats
are different.
Chapter 1. Introduction
11
3. Non-J2EE artifacts
– Use of vendor-specific features cause incompatibilities.
– Third-party packages and licensing may or may not be available for your
target server.
4. Databases
– Although appropriate drivers exist for all major database products,
migrating from one database product to another can require significant
revisions to database structure and maintenance procedures.
– The JDBC interfaces are particularly flexible, allowing developers to exploit
many vendor-specific details. This is a major cause of application
incompatibilities.
5. Tools
– Custom development and build tools, built specifically for your application,
may not run on the target environment. Their dependent components may
not be available. They may make detailed assumptions about the target
environment, such as directory structure or the format of vendor-specific
configuration information.
1.2.5 Migration tools
While tools are essential for building a J2EE application, they are even more
important for migrating a J2EE application. This is because:
򐂰 The migration team is less likely to know the original structure and detailed
design of the application.
򐂰 Since the target J2EE server is unfamiliar, reliance on its tool set is
particularly important.
We have observed that a major aspect of a migration effort is learning to use the
new tool set. Using unfamiliar tools, even very good ones, slows progress and
can cause errors, confusion, and rework. And this can negatively impact
developer morale and application quality.
Taking a look at the tools we used for our migration examples, they fall into the
following categories:
1. Standard Java platform tools
These include the J2SE toolkit along with the various standard extensions
required by the J2EE specifications. Provided that version levels are the
same, these tools are the same for both WebLogic and WebSphere. They
introduce no new migration issues.
12
Migrating WebLogic Applications to WebSphere Advanced Edition V4
2. Third-party tools
Ant and JUnit are examples of open source tools mentioned in this book.
These tools may introduce migration issues if they are not familiar to the
migration team. Since Ant is used industry-wide, it is likely to be familiar to a
WebLogic developer. Even if these tools are familiar, learning how to use
them with WebSphere artifacts may require training.
3. Vendor-specific J2EE tools
The major tools in this category are WebSphere Studio Application Developer
and AAT. Learning how to use these tools can be a challenge. Without training
and a positive attitude, migrating to the WebSphere tool set can be a
migration issue in itself.
Among other things, these tools are used to create vendor-specific
deployment descriptors. Creating vendor-specific deployment descriptors is
one of the major sources of migration issues. Understanding how to use these
tools is important.
As a full-featured IDE, WebSphere Studio Application Developer also
provides the full array of features for J2EE application development. It is also
a powerful tool set for migrating J2EE applications. It serves the same role in
this book that VisualAge for Java, Enterprise Edition served in Migrating
WebLogic Applications to WebSphere Advanced Edition, SG24-5956.
Depending on their background, some developers have strong preferences
regarding IDEs in general, and WebSphere Studio Application Developer in
particular.
– VisualAge developers may find some of Studio’s features less mature or
less elegant than they are used to.
– Developers accustomed to the hands-on style of command line-oriented
IDEs may take a while to adjust to Studio’s integration and automation.
4. Custom tools and scripts
Sometimes the most effective tool is a special-purpose, custom-made tool
using scripts and command lines. Indeed, a special-purpose Ant script may
fall into this category. These tools are special-purpose because they take
advantage of the structure of your application, the J2EE server, and the
operating system. They often become part of the application itself. Although
custom tools are likely to be different on each system, their use is usually
minimal, causing only minor migration issues.
Two of the chapters in this book include details about tools:
򐂰 Chapter 3, “Installation and configuration” on page 35
򐂰 Chapter 4, “Development and migration tools” on page 67
Chapter 1. Introduction
13
Because of the importance of tools in the migration effort, most other chapters
also contain instructions on the use of tools. In particular, the migration examples
in Chapter 12, “Migration examples” on page 265 offer many examples of how to
use the WebSphere tool set.
1.3 How to use this guide
The chapters in this book are organized around the following general topics:
򐂰 J2EE features and migration strategy
– Chapter 2, “Features comparison and migration strategy” on page 17
This chapter covers two distinct topics. The first topic provides details on the
J2EE features offered by the WebLogic and WebSphere servers. It also
provides a look at future versions of the J2EE specifications. The second
topic outlines a general strategy for migration projects.
򐂰 Tools
– Chapter 3, “Installation and configuration” on page 35
– Chapter 4, “Development and migration tools” on page 67
– Chapter 11, “Application assembly and deployment” on page 245
Different kinds of tools are covered in each of these three chapters. The first
of these chapters covers the WebLogic and WebSphere servers themselves.
The second focuses on the WebSphere tool set. The third goes into technical
details of the tools and process used for application assembly and
deployment. If also covers the migration of this task from WebLogic to
WebSphere.
򐂰 Specific J2EE technologies
–
–
–
–
–
–
Chapter 5, “Security” on page 111
Chapter 6, “Transaction management” on page 135
Chapter 7, “Naming” on page 147
Chapter 8, “Java Servlets and JavaServer Pages” on page 173
Chapter 9, “Enterprise JavaBeans” on page 195
Chapter 10, “Database connectivity and persistence” on page 229
Each of these chapters examines a specific J2EE technology. Each identifies
migration issues, makes recommendations, and outlines future J2EE
features.
򐂰 Migration examples
– Chapter 12, “Migration examples” on page 265
14
Migrating WebLogic Applications to WebSphere Advanced Edition V4
This chapter uses the tools, processes, and recommendations of the other
chapters to perform three mini-migration exercises from beginning to end.
Each of these examples is quite different from the others. Special emphasis is
placed on the tools used to accomplish these migrations.
As you can see, this book covers a wide range of migration topics. You are
encouraged to read it from cover to cover. However, if your time is limited, you
may wish to choose one of the following paths, depending on your interests:
1. J2EE features and future standards
a. Review the short introduction to J2EE technologies in this chapter.
b. Read 2.1, “WebSphere and WebLogic servers” on page 18 and 2.2,
“Feature comparison” on page 19.
c. Depending on your interests, scan the introduction and J2EE future
standards sections of the J2EE technology chapters.
2. Migration process
a. Read 2.3, “Migration process” on page 26.
b. Read Chapter 12, “Migration examples” on page 265 for some examples.
3. Migration tools
a. Read the tools chapters.
b. Read Chapter 12, “Migration examples” on page 265 for more specific
details.
c. Depending on your interests, you will find additional examples in the J2EE
technology chapters.
4. Migration and portability issues
a. For general issues, first review this introduction and then read 2.3,
“Migration process” on page 26.
b. For specific examples, read Chapter 12, “Migration examples” on
page 265 or selected J2EE technology chapters.
5. Beginning-to-end migration examples (learn by example)
a. Read Chapter 12, “Migration examples” on page 265.
b. This may pique your curiosity to examine some of the tools and J2EE
technology chapters.
Chapter 1. Introduction
15
16
Migrating WebLogic Applications to WebSphere Advanced Edition V4
2
Chapter 2.
Features comparison and
migration strategy
In the chapter, we give a brief outline of the J2EE features of BEA WebLogic
Server and of WebSphere Application Server, Advanced Edition. We then
discuss a strategy for migrating applications from WebLogic to WebSphere.
© Copyright IBM Corp. 2002
17
2.1 WebSphere and WebLogic servers
The primary focus of the book is the migration of J2EE applications from BEA
WebLogic Server V6.1 to WebSphere Application Server, Advanced Edition V4.
Our recommendations apply equally well for migrating from BEA WebLogic
Server V5.x. Both WebLogic V6.1 and WebSphere V4 are J2EE 1.2 compliant
servers. This means that they have passed the J2EE Compatibility Test Suite
(CTS) developed by Sun Microsystems. You can see the latest tested
configurations at http://java.sun.com/j2ee/1.2_compatibility.html. The CTS
program is one more step toward ensuring portability of J2EE applications.
The J2EE specifications and J2EE compliant servers continue to advance at a
rapid pace. As of the writing of this book, both BEA and IBM have announced
servers that have passed the CTS for the J2EE 1.3 specification. See
http://java.sun.com/j2ee/compatibility.html for the full list of J2EE 1.3
compliant servers. We include a survey of J2EE 1.3 technologies in this chapter
for several reasons:
1. WebLogic V6.1 and WebSphere V4 both contain previews of some of the
J2EE 1.3 technologies
2. Relying on preview technologies can be a source of migration problems
3. Understanding J2EE 1.3 will help you plan future upgrades and migrations
Table 2-1 on page 19 lists implementation levels of the J2EE technologies in the
WebLogic and WebSphere servers. The version information in this table is based
primarily on vendor documentation. For comparison purposes, the order of this
table is the same as Table 1-1 on page 8. In addition to tabulating WebSphere V4
and WebLogic V6.1, we also show the next generation of these servers —
WebSphere Technology for Developers and WebLogic V7.0. These servers have
passed the CTS for J2EE 1.3.
In the next section, we examine the details of this table with regard to:
1. Required J2EE 1.2 features for WebSphere V4 and WebLogic V6.1
2. Preview J2EE1.3 features in WebSphere V4 and WebLogic V6.1
3. Future J2EE standards
We identify potential migration problems for J2EE technologies. We also take a
brief look at non-J2EE technologies that may cause migration problems.
18
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Table 2-1
J2EE technology support levels
WebSphere
V4
WebSphere
Technology
for Developers
WebLogic
V6.1
WebLogic
7.0
J2EE
1.2
partial 1.3
1.3
1.2
1.3 preview
1.3
J2SE
1.3
1.3.1
1.3.1
1.3.1
EJB
1.1
2.0
1.1
2.0 preview
2.0
JSP
1.1
1.2
1.1
1.2 preview
1.2
Java
Servlets
2.2
2.3
2.2
2.3 preview
2.3
1.0 preview
1.0
1.0
1.0
JAF
1.0.1
1.0.1
1.0.1
1.0.1
JavaMail
1.1.3
1.2
1.1
1.1.3
JAXP
1.1
1.1
1.1
1.1
JCA
J2C preview
1.0
1.0 preview
1.0
2.0
2.0
2.0
2.0
JMS
1.0.2
1.0.2
1.0.2
1.0.2
JNDI
part J2SE 1.3
JTA
1.0.1
Technology
JAAS
JDBC
RMI/IIOP
part J2SE 1.3
part J2SE 1.3
1.0.1
part J2SE 1.3
part J2SE 1.3
1.0.1
part J2SE 1.3
part J2SE 1.3
1.0.1
part J2SE 1.3
2.2 Feature comparison
This book is limited to identifying migration issues. You should refer to published
specifications for information about using J2EE technologies. For many J2EE
technologies, there is little difference between WebSphere and WebLogic
because they support the same levels of the specifications. There should be no
migration issues in these cases, so we say little about them.
In general, migration issues concerning J2EE technologies arise in the following
situations:
Chapter 2. Features comparison and migration strategy
19
򐂰 Servers support different levels of the specifications.
򐂰 Server vendors have interpreted the specifications differently.
A variation of this is strict vs. lenient implementations. We found that
WebSphere is more strict, while WebLogic is more lenient in enforcing various
standards. An application with minor deviations from a standard may be
accepted by WebLogic and rejected by WebSphere. This may cause a
migration problem.
򐂰 The specifications explicitly or implicitly leave important details to the vendors.
This is especially true for extended deployment descriptors. Each vendor has
taken its own approach to the form and content of extended deployment
descriptors. This results in migration problems.
In addition, the J2EE specifications do not cover details of most of the required
tools support. Tools support is an area where vendors are encouraged to provide
added value. Consequently there are wide differences among tools. This
becomes a migration issue in that developers often find themselves learning new
tools at the same time they are performing a migration to a new server. Guidance
for using tools for WebSphere is provided in most of the other chapters of this
book, especially in Chapter 4, “Development and migration tools” on page 67 and
Chapter 12, “Migration examples” on page 265.
2.2.1 J2EE 1.2 features
Compare the WebSphere V4 and WebLogic V6.1 columns of Table 2-1 on
page 19 with the required J2EE 1.2 support levels shown in Table 1-1 on page 8.
Ignoring the preview technologies for now, we see the following differences:
򐂰 Both servers support J2SE 1.3, while the J2EE 1.2 specification only requires
J2SE 1.2.
WebLogic V6.1 supports the J2SE 1.3.1 maintenance release. This release
– Fixes many minor bugs.
– Includes the HTML converter instead of requiring that it be downloaded
separately.
See http://java.sun.com/j2se/1.3/relnotes.html for complete details. If
your application just happens to be affected by one of these bugs, it may
cause a migration problem.
򐂰 The J2EE 1.2 specification requires JNDI 1.2 and RMI/IIOP 1.0. Since these
technologies are included as part of J2SE 1.3, both of the servers exceed the
required specification level.
20
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 As required, WebLogic V6.1 supports JavaMail 1.1, while WebSphere V4
supports the newer JavaMail 1.1.3 maintenance release. (Note that JAF is
required by JavaMail.)
򐂰 Both servers support the same maintenance releases of the JAF, JMS, and
JTA 1.0 specifications — no J2EE migration issues there.
򐂰 All other required technologies are at the level required by the J2EE 1.2
specification.
Migration issues
The bottom line is that the minor support level differences outlined above are
unlikely to result in significant migration issues. In our previous migration guide,
Migrating WebLogic Applications to WebSphere Advanced Edition, SG24-5956,
differences in J2EE and EJB support levels accounted for most of the migration
issues. By comparison, most of the migration issues in this book have to do with
things that are not covered directly by the J2EE specifications. These include
vendor-specific deployment descriptors and learning how to use the new
WebSphere Application Server, Advanced Edition tools set. Some specific
examples of these migration issues are:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Construction and use of EAR files
Assembly and deployment
Assignment of JNDI names
Deployment of CMP entities
Security configuration
Database conversion
2.2.2 J2EE 1.3 preview technologies
Both WebSphere V4 and WebLogic V6.1 offer preview versions of J2EE 1.3
technologies. These are not required by the J2EE 1.2 compliant servers, but will
be required by the J2EE 1.3 compliant servers. Although these technologies are
included in Table 2-1 on page 19, please note that the preview technologies were
not covered by the J2EE 1.2 CTS certification process. Indeed, since these
technologies are usually developed before final specifications are available, they
may differ from the official specification. The following warning from BEA
emphasizes this point:
“The J2EE 1.3 feature implementations use non-final versions of the
appropriate API specifications. Therefore, application code developed for
BEA WebLogic Server V6.1 that uses the new features of J2EE 1.3 may be
incompatible with the J2EE 1.3 platform supported in future releases of BEA
WebLogic Server.”
Similar warnings hold for WebSphere preview technologies.
Chapter 2. Features comparison and migration strategy
21
WebLogic provides more preview releases, while WebSphere adheres closely to
the official standards. From a migration perspective, the use of preview
technologies is likely to cause migration problems beyond those indicated in the
above warning. The preview technology may not be available in the target server.
WebLogic preview of core technologies
WebLogic V6.1 includes previews of:
򐂰
򐂰
򐂰
򐂰
J2EE 1.3
EJB 2.0
JSP 1.2
Servlet 2.3
If your application depends upon the new features of any of these technologies,
you will have a migration problem. Although it is beyond the scope of the current
book, one way to solve this migration issue is to migrate to WebSphere for
Developers. It supports the official releases of these technologies.
Preview technologies are based on non-final releases of specifications. These
are called Proposed Final Drafts (PFD) and may differ significantly from the final
specification. The contents of non-final releases can usually be determined by
examining the draft specifications and specification histories available from Sun
Microsystems.
If your application uses WebLogic V6.1 preview technologies, expect the
following migration issues:
򐂰 J2EE 1.3 preview applications use new DTDs for deployment descriptors and
depend on the new JCA technology.
An EAR created with this J2EE 1.3 preview is incompatible with WebSphere
V4, but is compatible with WebSphere for Developers.
򐂰 The EJB 2.0 preview is based on PFD#2, which differs only in minor ways
from the final specification.
The final release of EJB 2.0 is supported in WebSphere Technology for
Developers.
򐂰 The JSP 1.2 preview is based on the original PFD, so it does not include the
XML and TLD cleanups, nor the jsp:id mechanism added in PFD#1 and
PFD#2.
The final release of JSP 1.2 is supported in WebSphere Technology for
Developers.
򐂰 The Servlet 2.3 preview is based on PFD#1. Since then, there have been a
few new or renamed methods and only minor changes to the new servlet
filtering feature.
22
Migrating WebLogic Applications to WebSphere Advanced Edition V4
The new filters and events of Servlet 2.3 are fully supported in WebSphere for
Developers. In addition, these features are also supported by proprietary (and
thus incompatible) WebSphere V4 packages.
Preview of other J2EE 1.3 technologies
The J2EE 1.3 specification adds three new technologies to the list of
technologies that a server must support. Although these are not required by
J2EE 1.2, both WebSphere V4 and WebLogic V6.1 offer previews of them in
preparation for the future.
򐂰 JAAS 1.0 supports authentication and authorization from within EJB
containers, following the standard Pluggable Authentication Model (PAM)
framework.
– Support for JAAS 1.0 is provided as part of the WebLogic V6.1
– JAAS is only available for WebSphere as a preview technology for
Windows 2000 and Windows NT. For more information, see
http://www7b.boulder.ibm.com/wsdd/wspvtext-info.html.
򐂰 JAXP 1.1 for XML parsing.
JAXP 1.1 specifies factory objects and interfaces in support of XML parsers.
The most popular implementations of JAXP 1.1 are the XML parsers provided
by the Apache XML Project — Xerces is the XML parser and Xalan is the
XSLT stylesheet processor.
– WebLogic V6.1 supports JAXP 1.1 with Xerces 1.3.1 and Xalan 2.0.1.
Since internal versions have been modified by BEA, you cannot freely
substitute other versions of Xerces and Xalan.
– WebSphere V4 supports JAXP 1.1 with XML 4J (Xerces) 3.2.1 and XSL
(Xalan) 2.2.
It is easy to plug your own XML parser into WebSphere V4.
򐂰 J2EE Connector architecture (JCA) 1.0 for connecting to external servers and
legacy systems.
The JCA technology supports the integration of heterogeneous Enterprise
Information Systems (EIS) by means of standard resource adapters. Adapter
vendors provide factory objects for JNDI lookup, while server providers
support required transactioning, authentication, and deployment descriptors.
JCA depends on J2SE 1.3, JAAS, JNDI, and JavaIDL.
– The JCA 1.0 preview support in WebLogic V6.1 is based on PFD#2. The
specification has since been modified slightly to disallows manual
transactioning.
Chapter 2. Features comparison and migration strategy
23
– The JCA 1.0 preview support in WebSphere V4 is also based on PDF#2,
but it goes by the name of J2C for Java 2 Connection. WebSphere V4
comes with a set of J2C adapters for testing purposes.
2.2.3 J2EE 1.3 and beyond
In this section, we take a quick look at the features of future releases of the J2EE
technologies. As mentioned above, WebLogic and WebSphere have already
released servers that have passed the CTS for J2EE 1.3. Taking advantage of
the new features in these releases will represent a different kind of migration
effort — from one release level to the next instead of from one server to the next.
Here is a short list of the new features in the core technologies of J2EE 1.3. See
the appropriate specifications for the details of these new features.
򐂰 J2EE 1.3
– J2EE Connector Architecture
– JMS point-to-point messages and the publish-subscribe model
Although JMS 1.0 is required in J2EE 1.2, the ConnectionFactory and
Destination objects that support these features were not required to be
implemented. These objects must be implemented in J2EE 1.3 servers.
Both WebLogic V6.1 and WebSphere V4 implement these objects.
WebLogic uses WebLogic JMS and WebSphere uses MQSeries.
– Enhanced XML capabilities, including JAXP
– Ability to write and manipulate JavaServer Pages in XML
򐂰 EJB 2.0
– Message-driven beans, integrating EJB and JMS
– Container-managed relationships
– EJB QL, a portable query language supporting portable finders
– Local interfaces for entity and session beans
– Improved inter-server application interoperability
򐂰 JSP 1.2
– New flush attribute for jsp:include. This fixes the flush before the include
limitation of JSP 1.1
– TryCatchFinally interface for a JSP tag
– IterationTag class
– Define XML syntax for JSP pages
– Translation-time validation of JSP pages with Tag Library Validator
24
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 Java Servlets 2.3
– Application events
– Application filters
Future J2EE specifications
Although J2EE 1.4 has not been defined yet, there are two sources of
information providing guidance as to what you can expect to find in future J2EE
specifications.
1. The future directions chapter of the J2EE 1.3 specification lists the following
features (partial list)
–
–
–
–
–
Web services
XML Data Binding API
Java Network Launch Protocol (JNLP)
JDBC RowSets for database-independent manipulation of tabular data
Deployment tool APIs to support vendor-neutral deployment tools
2. A more dynamic way to track future specifications is through the Java
Specification Requests (JSR) process. See http://www.jcp.org for details.
There are almost 200 JSRs listed at the time of writing this book. In particular,
JSR 151 is for the J2EE 1.4 specification. It currently contains the following
topics (partial list), in the form of references to other JSRs.
– Web services using SOAP/HTTP
– Management specification to provide tool vendors with a standard model
for managing the J2EE Platform
– Deployment API
– JNLP
– Java Connector Architecture 2.0
– JSP 1.3
– Servlet 2.4
– EJB 2.1
– JAXP 1.2 — XML Schema support
– JMS 1.1 — queue/topic unification
J2SE 1.4 has been defined and will certainly be required by J2EE 1.4. A review
of the new features in J2SE 1.4 goes beyond the scope of this book. However,
you will find that both JAAS and JAXP have been folded into J2SE 1.4.
Chapter 2. Features comparison and migration strategy
25
2.2.4 Non-J2EE dependencies
A major benefit of adhering to the J2EE specifications is that it significantly
reduces migration problems. Although the focus of this book is the migration of
J2EE applications, real-world migrations often have to address non-J2EE
dependencies. There is no simple approach to the migration of non-J2EE
dependencies. Obvious alternatives include:
򐂰
򐂰
򐂰
򐂰
Convert to an equivalent J2EE feature.
Find the same or similar non-J2EE support in the target server environment.
Build bridging software between J2EE compliant and non-J2EE components.
Redesign to use the services available in the target environment.
Since some source code modifications are inevitable, this is a good opportunity
to make your application more compliant with current and future J2EE standards.
This will reduce future migration and upgrade costs.
WebLogic provides a variety of proprietary features. Many are in the form of
simple convenience classes that can easily be re-coded to more standard
equivalents. Other chapters in this book deal with the migration of some of these
more common WebLogic extensions. These include WebLogic extensions to JTA
and proprietary JSP taglibs.
Some WebLogic applications use third-party components such as COM, Jolt for
WebLogic, and TopLink. The specific advice we offered for these dependencies
in our first migration guide is still relevant. Please refer to Migrating WebLogic
Applications to WebSphere Advanced Edition, SG24-5956 regarding these
extensions and third-party components.
2.3 Migration process
In this section, we present the basic ingredients needed for any migration
process. Every migration project is different. The process you use will evolve to fit
your applications and your organization. We start with the assumption that you
have decided to migrate from WebLogic to WebSphere. The reasoning behind
this decision is beyond the scope of this book. Our goal is simply to help make
the migration process successful.
We assume your application runs on WebLogic and that you have collected the
relevant software artifacts as outlined in 1.2.3, “Application artifacts and
dependencies” on page 9. Your task is to modify this set of artifacts to run on
WebSphere. The process you choose will depend on a variety of factors,
including the size of your migration project and the experience and culture of your
26
Migrating WebLogic Applications to WebSphere Advanced Edition V4
developers, organization, and management. We start with the basics that are
needed in every migration process. Then we outline some additional options for
training and project staging. Finally, we suggest how to expand migration to
encompass the use of best practices to build more adaptable applications.
1. Basic migration steps and tools
This is the bare minimum that must be done to get an application migrated
and running on the target system. You achieve the basic level of portability
provided by the J2EE standards, while keeping changes to a minimum. By
itself, this approach is only recommended for small, well-written applications.
2. Project planning alternatives
Larger migration projects require scoping, staging, and training. Sometimes
risk can be reduced by dividing a larger migration effort into several smaller
efforts. In particular, we recommend that database migrations be done as
separate projects.
3. Make the application more adaptable
Instead of implementing the minimum changes required to migrate an
application, this approach argues for making additional changes to improve
the adaptability of the application. When the life-cycle costs of a complex
application are considered, this approach can reduce overall cost and
improve quality at the same time.
A small project can suffice with the basics. Larger projects should do some
planning and consider pilot projects or several smaller efforts. As another
alternative, you may also want to consider outsourcing.
2.3.1 The basic steps
The basic steps of a migration are more or less determined by the J2EE artifacts
themselves. Every migration must do the following:
1. Import code
This usually just means source code, but can include object code as well. It
also includes manifest files and existing deployment descriptors. The WAR
and JAR structure of the application is also required.
2. Modify code
Non-J2EE code needs to be upgraded. As described in 1.2.4, “Migration
issues” on page 10, even J2EE-compliant applications can require a
surprising number of changes. If database migration is also included, the
JDBC code will probably have to be changed.
Chapter 2. Features comparison and migration strategy
27
3. Create vendor deployment descriptors
The standard J2EE deployment descriptors should not require changes.
However, WebLogic and WebSphere have different vendor-specific
deployment descriptors, and they use different tools to create and edit them.
4. Test and verify
Every change needs testing. Testing sometimes exposes missing or
incompatible artifacts, possibly causing you to revisit the import step above.
5. Iterate until correct execution
Just as with any development project, the problems exposed by testing must
be fixed and retested.
6. Export EAR
Now you are ready to move from the test environment to production or, as is
the case in a large development shop, from the test environment to product
test. The EAR file is the formal delivery artifact for a J2EE application.
7. Deploy on server
While the EAR file is the deployment vehicle, the production server also
needs additional configuration for application databases and any other
runtime services.
We follow variations on this process in each of the examples in Chapter 12,
“Migration examples” on page 265. In general, these variations are determined
by the migration issues encountered and the tools selected for use.
1.2.4, “Migration issues” on page 10 outlines different kinds of migration issues.
The next section addresses tool selection.
Tools strategy
Each of the above steps is supported by several different tools. You will have to
make some choices. We recommend using WebSphere Studio Application
Developer as the primary migration environment, but we also present several
alternatives:
1. WebSphere Studio Application Developer
2. Standard Java tools with conventional program editor
3. WebGain or VisualCafe style environments
28
Migrating WebLogic Applications to WebSphere Advanced Edition V4
WebSphere Studio Application Developer
WebSphere Studio Application Developer provides a rich environment for all of
the steps outlined in 2.3.1, “The basic steps” on page 27. Once your code is
imported, you do not need to use other tools. If you have a well-formed EAR file
with JARs containing all necessary source code, then just import the EAR
directly into WebSphere Studio Application Developer. Otherwise, use one of the
following strategies to import the application. They are listed in descending order
of desirability.
1. Write an Ant script to create an EAR file with source code and then import it
into WebSphere Studio Application Developer.
2. Create the required projects in WebSphere Studio Application Developer and
then import one module at a time from the staging directories for these
modules.
3. Write an Ant script to create staging directories for individual modules and
then import each module from its staging directory.
4. Import all the code into a temporary project and move the files around in
WebSphere Studio Application Developer. This option is not recommended.
The WebSphere Studio Application Developer test environment supports rapid
changes and retesting without having to restart the test server. You may prefer
one of the following variations on this WebSphere Studio Application Developer
tool strategy:
1. Use JUnit instead of the WebSphere Studio Application Developer test server.
2. Use AAT to edit the deployment descriptors generated by WebSphere Studio
Application Developer.
3. Special needs may require that small tasks be performed outside of
WebSphere Studio Application Developer, and the resulting files imported
into Studio.
As an example, the rmic command was required in 12.4, “Banking example”
on page 302. WebSphere Studio Application Developer import and export
features support this variation.
Standard Java tools with conventional program editor
If you do not have WebSphere Studio Application Developer or prefer to use the
standard Java tools and a conventional program editor, then the following tools
strategy may be preferred:
1. Use AAT to package the application to get the initial structure and EAR.
2. Make code changes using the conventional Java tool set.
3. Use AAT to:
a. Bring in new and modified code
Chapter 2. Features comparison and migration strategy
29
b. Change deployment descriptors
c. Generate deployment code
d. Export EAR
As variations, Ant can be used to create the initial EAR, and EJBDeploy can be
used to generate deployment code.
WebGain or VisualCafe
If you are familiar with WebGain or VisualCafe, the following tools strategy may
be more suitable:
1. Use WebGain or VisualCafe as the primary migration environment.
2. Use WebGain or VisualCafe to export the source code EAR, JAR, and class
files to the file system.
3. Use AAT to assemble source code into an EAR file and generate deployment
descriptors and binding information.
4. Use AAT to export the final EAR file.
2.3.2 Project planning
Although the steps in 2.3.1, “The basic steps” on page 27 are required for every
migration project, a realistic migration project involves much more than just fixing
the code. Migration projects are generally expensive, complex, and potentially
risky undertakings. As with any software development project, there will be
unforeseen complications. The same tried-and-true management techniques
should be employed for migration projects. These include the following project
management issues:
1. Do developers have the required skills?
It is best to deal with this issue early in the project’s preparation phase, when
there is often some slack time. Investing in the following activities will greatly
improve the quality and productivity of your staff:
– Training
– A pilot or trial mini-migration project
– Tool evaluation
By the time the real migration effort starts, your staff should be familiar with
the new tools environment and the target J2EE server.
2. How should the work be staged?
The staging issue should be considered at two different levels. In both cases,
the goal is to reduce risk by a divide-and-conquer strategy.
30
Migrating WebLogic Applications to WebSphere Advanced Edition V4
– Project level staging
Often, a large project can be divided into smaller projects that can run
sequentially or in parallel. We have already recommended separating
database migration into a separate project. In addition, the loosely coupled
nature of a J2EE application may allow different application layers or slices
to be migrated separately. For example, consider migrating a Web module
while the EJBs continue to run on the original system, or vice versa. This
may require some adjustments to JNDI use. We discuss this topic in more
detail in Migrating WebLogic Applications to WebSphere Advanced
Edition, SG24-5956.
– Incremental delivery
The following idea is central to many software management processes.
Deliver your product as a series of small incremental improvements. Each
delivery is managed as a separate, small project with a very short cycle
time. Extreme programming promotes the latest incarnation of this idea
with small, incremental releases, symbolized by its mantra of “make it run,
make it run right, make it run fast”.
3. What sort of quality controls are needed?
Again, traditional software processes recommend using:
–
–
–
–
An independent product test group
Automated testing
Reviews
Source control
JUnit is an open source testing tool, available at http://www.junit.org. The
extreme programming folks take this technology a step further by
recommending that you write your test cases before writing your application.
A migration project offers an excellent opportunity to exploit a variation on this
recommendation. Most likely your WebLogic application does not have a
comprehensive, automated test suite. During the early stages of your
migration project, while the old system is still up and running, why not produce
this test suite? Not only will it provide a baseline for quality control of the
migrated application, but your development team will gain valuable, detailed
knowledge of the application that can be used for future improvements.
An in-depth treatment of these topics is beyond the scope of this book. For more
details as they relate to migration projects, see the short paper by Wayne
Beaton, Migrating to IBM WebSphere Application Server - Part 2: Stages of
Migration available at
http://www7b.boulder.ibm.com/wsdd/techjournal/0110_beaton/beaton.html.
This paper outlines the following major activities for a migration project:
򐂰 Scoping
򐂰 Skills migration
Chapter 2. Features comparison and migration strategy
31
򐂰 Code migration
򐂰 Runtime migration
򐂰 Runtime performance tuning
For more information on extreme programming, visit
http://www.extremeprogramming.org.
Best practices
A migration effort is an excellent opportunity to improve an application’s quality.
Although counterintuitive to some, making more than the minimum set of
changes may actually result in improved quality at less cost. There is an apparent
conflict between the following two pieces of advice:
1. Quality control tells us that fewer changes means fewer defects
Up to now, we have promoted the goal of making the minimum code changes
needed to accomplish a migration. The resulting migrated application will be
portable within the scope of the J2EE specification, but when measured by
industry-standard best practices, it may fall far short in terms of adaptability.
2. Implementing best practices claims to improve quality, even if it requires
additional code changes
As a large application evolves, its original architecture becomes obscured and
outdated. The application becomes brittle and harder to modify. Restoring or
introducing clean and simple design requires at least some local re-coding.
The payoff is better quality and lower cost for future upgrades and migrations.
The topic of best practices is beyond the scope of the book, but includes
general design recommendations such as:
–
–
–
–
–
–
–
Use layered structuring
Use patterns such as MVC and the Model 2 architecture
Use abstraction
Reduce coupling
Follow industry standards
Use encapsulation — no public variables
Design clean object-oriented semantics
We recommend making more than minimal changes, provided they improve
application quality and adaptability as measured by best practices. However, a
migration project should not be an excuse for wholesale redesign. We
recommend the following criteria to select candidates for local redesign during
the course of a migration:
32
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 Improve design only as a result of actual migration issues.
This places a limit on redesign and keeps the project focused on the migration
effort. Other redesign possibilities should be noted for possible future
improvements, but not added to the migration project itself.
򐂰 The same code must be changed in multiple places.
This is a candidate for refactoring (sometimes called an extract method).
WebSphere Studio Application Developer provides support for refactoring.
The idea is to replace the repeated code by a method call that encapsulates
it. This isolates the code changes to one place, making future migrations
easier. This kind of modification actually reduces the risk of new defects
caused by simple keying errors.
򐂰 A large, complex method or class obscures required migration changes.
Best practices encourage small classes and small methods with simple
designs. If you have trouble understanding a large, complex piece of code
during a migration effort, it is likely to be a problem to others in the future. Fix
the problem now while you understand it.
Taking the time to restructure your application into more independent
components can help with your current migration effort and the future
scalability of your application.
򐂰 Code that replicates standard features or services.
When the application was written, the corresponding standard feature may
not have been available. So, it may have been designed from scratch at that
time. We recommend that you use standard features and services whenever
possible.
򐂰 Remove dead code.
For more details on best practices as they relate to migration projects, see the
short paper by Wayne Beaton, Migrating to IBM WebSphere Application Server,
Part I: Designing Software for Change, available at
http://www7b.boulder.ibm.com/wsdd/techjournal/0107_beaton/beaton.html.
The services alternative
IBM provides excellent source materials to help architects to design e-business
applications. For basic architectural advice, look at the IBM Software Strategy for
e-business at http://www.ibm.com/software/ebusiness. This work closely
parallels the J2EE architectural work. For more in-depth advice on application
design within this framework, take a look at the Patterns for e-business site at
http://www.ibm.com/software/developer/web/patterns/. These techniques
can be helpful in a migration project.
Chapter 2. Features comparison and migration strategy
33
As an alternative to doing your own migration project, you may prefer to hire
experts to help you and your staff. IBM WebSphere Application Server Migration
Services Program offers a variety of migration services tailored specifically for
WebSphere. Visit
http://www-3.ibm.com/software/ad/vaws-services/websphere.html for more
information.
34
Migrating WebLogic Applications to WebSphere Advanced Edition V4
3
Chapter 3.
Installation and
configuration
In this chapter we provide an overview and recommendations for installing and
configuring the WebLogic and WebSphere products used during our redbook
migration testing. This is not intended to be a detailed installation guide, but
provides an overview of the needed products and skills from the perspective of
installing and configuring environments used to do a migration. We cover both
the tools and runtime environments that you will need to do a migration. Both
development and testing environments are considered. We describe how we set
up our ITSO lab environment. It is not intended that our environment be used for
production migration, but the details we provide should allow you to follow our
redbook examples. We also explain where our test environment deviates from a
recommended ideal environment.
© Copyright IBM Corp. 2002
35
3.1 Platform used for migration
In this sector we summarize the platforms used for migrating application from
BEA WebLogic Server to WebSphere Application Server. These platforms are
divided into two parts:
1. The development machine is for developing and testing each part of the
whole program.
2. The testing machine is the in-production machine that will actually run the
whole program or example.
3.1.1 Development machine
Our environment was as follows:
򐂰 IBM Netfinity 5100 with Pentium III 933 MHz processor, 1 GB RAM and 17
GB HDD
򐂰 Microsoft Windows 2000 Server with SP2 Build 2195
򐂰 Microsoft Internet Explorer V5.50.4522
We installed the following products:
򐂰
򐂰
򐂰
򐂰
IBM Universal Database Enterprise Edition V7.2 FP5
BEA WebLogic Server V6.1 SP2
IBM WebSphere Application Server, Advanced Edition V4.0.2
IBM WebSphere Studio Application Developer V4.0.2
Note: IBM WebSphere Application Server, Advanced Edition is not required
when you do not do an integration test. IBM WebSphere Studio Application
Developer has built-in debugger tools that can help you test migration code
before deploying to the real application server. For more details, see
Chapter 4, “Development and migration tools” on page 67.
3.1.2 Testing machine
We used two dedicated machines when testing our migration examples.
WebLogic test machine
We had the following environment:
򐂰 IBM Netfinity 5100 with Pentium III 933 MHz processor, 1 GB RAM and 17
GB HDD
򐂰 Microsoft Windows 2000 Server with SP2 Build 2195
򐂰 Microsoft Internet Explorer V5.50.4522
36
Migrating WebLogic Applications to WebSphere Advanced Edition V4
We installed the following products:
򐂰 IBM Universal Database Enterprise Edition V7.2 FP5
򐂰 BEA WebLogic Server V6.1 SP2
WebSphere Application Server test machine
We had the following environment:
򐂰 IBM Netfinity 5100 with Pentium III 933 MHz processor, 1 GB RAM and 17
GB HDD
򐂰 Microsoft Windows 2000 Server with SP2 Build 2195
򐂰 Microsoft Internet Explorer V5.50.4522
We installed the following products:
򐂰 IBM Universal Database Enterprise Edition V7.2 FP5
򐂰 IBM WebSphere Application Server, Advanced Edition V4.0.2
3.2 Products installation and configuration
In this sector, we describe the installation and basic post-configuration for each
product used in our migration work. This is a summary of the major steps
involved. For detailed installation instructions we recommend that you refer to the
official installation guides for each product
3.2.1 IBM UDB V7.2
In this section, we show you how to install and configure IBM UDB DB2 for our
migration work.
Install IBM UDB DB2
1. Make sure that you have sufficient rights for the installation. As described in
the installation documentation, the account you are logged in must:
– Be defined locally
– Belong to the Local Administrator’s group
– Have the following advanced user rights:
• Act as part of the operating system
• Create token object
• Increase quotas
• Replace a process level token
2. We installed the DB2 UDB Enterprise Edition V7.2 with the custom
installation options as shown in Figure 3-1.
Chapter 3. Installation and configuration
37
Figure 3-1 DB2 installation - Select Installation Type window
3. On the Select Components window as shown in Figure 3-2, deselect Data
Warehousing Tools, Data Warehouse ISV Toolkit and DB2 OLAP Starter
Kit and change the installation directory to C:\SQLLIB.
Note: In our migration work, DB2 UDB was used as a simple database, so we
did not need to install the Data Warehouse and OLAP server functions
shipped with DB2.
38
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-2 DB2 installation - select components
4. To save time, at the end of DB2 installation, we directly apply the latest fix
pack (FP5) without rebooting the system. After successfully adding the fix
pack, reboot your system.
5. After rebooting, the window shown in Figure 3-3 should appear. We created
the DB2 sample database that is used as the sample database in our
redbook. Click Create sample database on the welcome window to create a
DB2 UDB sample database.
Chapter 3. Installation and configuration
39
Figure 3-3 Welcome window - Create sample DB2 database
DB2 UDB installation verification
Open a DB2 command window, enter the following commands to connect to the
Sample database, retrieve a list of all the employees that work in department 10,
and reset the database connection, see Example 3-1.
Example 3-1 Command to verify DB2 installation
db2cmd
db2 connect to sample
db2 “select * from staff where dept = 10”
db2 connect reset
The output will be the same as shown in Figure 3-4.
40
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-4 DB2 Installation verify
DB2 UDB configuration
The JDBC driver 2.0 is used by the WebSphere Application Server V4
administrative server to connect to DB2. By default, DB2 is configured with JDBC
1.1, so, we upgraded the JDBC driver as follows:
1. Stop all the DB2 services in the Windows services control panel.
2. Run the usejdbc2.bat file in the \SQLLIB\java12 directory.
3. Restart the DB2 services.
For more information about IBM Universal Database, refer to the product
information center shipped with the product or visit the IBM Universal Database
Web site at:
http://www-3.ibm.com/software/data/db2/udb/
3.2.2 BEA WebLogic Server V6.1 SP2
In this section, we show how to install and configure the BEA WebLogic Server
used for our migration work.
Install WebLogic server
We downloaded the installation code of BEA WebLogic Server V6.1 SP2 we
used in our migration work from the BEA Web site at:
Chapter 3. Installation and configuration
41
http://commerce.bea.com/downloads/weblogic_server.jsp
The basic installation of WebLogic is quite simple. All you need to do is confirm
the license agreement, choose the home and installation directories, and enter a
system password at the end of the installation. One thing you must be careful
about is to choose Server with Examples in the install set window, as shown in
Figure 3-5. In the following chapters we need some examples provided by
WebLogic to demonstrate how to migrate code from WebLogic to WebSphere
Application Server.
Figure 3-5 WebLogic Installation - choose install set
WebLogic installation verify and configuration
In this section, we start the default server created by WebLogic as an
administration server and create a new machine and a new managed server. The
steps are:
1. Start the default server.
42
Migrating WebLogic Applications to WebSphere Advanced Edition V4
You can start the default server with the command
<weblogic>\wlserver6.1\config\mydomain\startWebLogic.cmd. After
entering the system password, you should see a window similar to the one
shown in Figure 3-6.
Figure 3-6 WebLogic configuration - start WebLogic server
2. Start the default administration console.
Start the default console by running Programs -> BEA WebLogic
E-Business Platform ->WebLogic Server 6.1 -> Start Default Console.
Figure 3-7 will appear.
Chapter 3. Installation and configuration
43
Figure 3-7 WebLogic configuration - create a new machine
3. Create a new machine.
From the WebLogic Server Console page, expand mydomain and click
Machines. From the right pane, click Configure a new Machine..., as shown
in Figure 3-7, and create a new machine named ITSOMachine.
4. Create a new managed server.
From the WebLogic Server Console page, expand mydomain and click
Servers. From the right pane, click Configure a new Server..., as shown in
Figure 3-8, and create a new managed application server named “itsoserver”.
The values we used to create the server are shown in Table 3-1.
44
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-8 WebLogic configuration - create a new managed server
Table 3-1 Values for creating a managed server
Name
Value
Name
itsoserver
Machine
ITSOMachine
Listen Port
8001
3.2.3 WebSphere Application Server V4
In this section, we show you how to install and configure WebSphere Application
Server for our migration work.
Install WebSphere Application Server
Before installing the WebSphere Application Server, Advanced Edition, we
recommend that you check the latest prerequisite information for WebSphere
Application Server at:
http://www.ibm.com/software/webservers/appserv/doc/latest/prereq.html
Chapter 3. Installation and configuration
45
Make sure that your platform operating system level supports WebSphere
Application Server, Advanced Edition V4.0.2 and also that you have the correct
version of DB2 UDB installed.
1. We installed WebSphere Application Server with Typical Installation options
as shown in Figure 3-9, which includes all the basic components and some
auto-configurations for WebSphere Application Server and database.
Figure 3-9 WebSphere installation options
2. On the Security Options window, shown in Figure 3-10, we chose the same
user ID/password as we used for install and administration of DB2 UDB. You
can choose an alternative user ID/password as long as you make sure that
the user ID has administrative privileges, has Act as the advanced user right
as part of the operating system, and is a local user ID. If the user ID you
selected has insufficient user rights to install WebSphere Application Server,
the install process will not successfully register the WebSphere Administrative
Server to the Windows services database.
46
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-10 WebSphere installation security options
3. On the Database Options window, shown in Figure 3-11, enter the values
(default values in most cases) shown in Table 3-2. If you want to alter these
values after installation, you can edit the file
<websphere>\appserver\bin\admin.config file and change the fields such as
dbdatabaseName, dbuser and dbpassword.
Table 3-2 Values for database options
Name
Value
Database Type
DB2
Database Name
was40
Database User ID
db2admin
Password
db2admin
Path
C:\SQLLIB (just as we defined in DB2 installation)
Chapter 3. Installation and configuration
47
Figure 3-11 WebSphere installation - database options
4. At the end of WebSphere Application Server installation, you may see a
warning message about the DB2 JDBC driver version as shown in
Figure 3-12. It means that you have not enabled the JDBC 2.0 driver for DB2.
You can click OK and proceed with the install, since you can change the
JDBC driver after WebSphere Application Server is installed. For instructions
of enabling JDBC 2.0 see “DB2 UDB installation verification” on page 40 for
details.
Figure 3-12 WebSphere installation - Warning about JDBC driver version
48
Migrating WebLogic Applications to WebSphere Advanced Edition V4
5. When the WebSphere Application Server setup program prompted us to
restart the system we did not reboot, but to save time we applied the fix pack
2 without rebooting the system.
Note: Use the following URL to check the latest fix pack for WebSphere
Application Server or download the fix pack:
http://www-3.ibm.com/software/webservers/appserv/support.html
6. Install fix pack 2 for WebSphere Application Server V4.0.
To install the fix pack extract all the files from the fix pack ZIP to a temporary
directory, change to this directory and run the install.bat file. When prompted
input the installation path of WebSphere Application Server you have installed
and the HTTP Server installation path. Note that the default WebSphere
Application Server installation path is <websphere>\appserver. Enter Yes to
confirm that you want to upgrade all the components that are provided with fix
pack 2.
7. After successfully adding the fix pack, reboot your system.
By default, WebSphere Application Server will run the database configuration
script (<websphere>\appserver\bin\createdb2.bat) after the first system
reboot following installation. See the log file
(<websphere>\appserver\logs\wasdb2.log) to check the results of the
database configuration. If errors occur, consult the WebSphere
documentation and try to manually run the database configuration script.
WebSphere installation verification
1. Start the WebSphere Admin server by choosing Start -> Programs -> IBM
WebSphere ->Application Server V4.0 AE -> Start Admin Server or use
the Windows services control panel to start the IBM WS AdminServer 4.0
service. See the log file (<websphere>\appserver\logs\tracefile) to check the
status of starting the administration server.
Tip: You can start and stop the WebSphere administration server by entering
the commands:
net start “IBM WS AdminServer 4.0”
net stop “IBM WS AdminServer 4.0”
2. Start the WebSphere Administrative Console by choosing Start -> Programs
-> IBM WebSphere ->Application Server V4.0 AE -> Administrator’s
Console.
The WebSphere Administrative Console is shown in Figure 3-13.
Chapter 3. Installation and configuration
49
Select WebSphere Administrative Domain -> Nodes -> <machine name>
-> Application Servers to see the Default Server that is created by
WebSphere installation. The Default Server is used to demonstrate features
of WebSphere Application Server and to verify application server installation.
You can start the Default Server from its context menu or by clicking the Start
icon.
Figure 3-13 WebSphere Administrative Console
3. After starting the default server, you can launch a Web browser and enter the
URL:
http://127.0.0.1/webapp/examples/showCfg
If the WebSphere installation is correct you should see the output page shown
in Figure 3-14.
50
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-14 WebSphere show configuration
WebSphere configuration
In this section, we describe several configuration tasks in WebSphere that were
necessary for our migration work.
Create a new application server
Although WebSphere Application Server has provided a Default Server for
demonstration and testing, we created a new application server named “ITSO
Server” for our migration testing.
1. From the WebSphere Administrative Console, click WebSphere
Administrative Domain ->Nodes.
2. Select your node (shown as your computer’s name), right-click the
Application Servers folder and choose New... from the pop-up menu.
Figure 3-15 shows the window used to create a new application server.
Chapter 3. Installation and configuration
51
Figure 3-15 WebSphere configuration - Create a new application server
3. Enter ITSO Server for the Application Server name and c:\itso for the
working directory. Note that WebSphere Application Server would not
automatically create the working directory you specified, so you must create
the directory before you click OK on the Create Application Server window.
Figure 3-16 shows the successful creation of our new application server.
Tip: It’s a good practice to create a separate working directory for each
application server, so you will know where to find the standard/error output
messages and JVM core dump of your application server.
52
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-16 WebSphere configuration - Successfully create a application server
Regenerate the plug-in’s XML configuration file
The WebSphere plug-in is a module that runs in the Web server process. It
decides which HTTP requests should be processed by WebSphere and which
requests are for the Web server to handle. The WebSphere plug-in works based
on the plug-in’s XML configuration file (located in
<websphere>/appserver/config/plug-in.xml).
By default, WebSphere Application Server V4 does not automatically regenerate
the plug-in’s XML configuration file. For example, after you deploy a new
enterprise application to WebSphere, you must regenerate the plug-in file
manually, which lets the WebSphere plug-in module know that there is a new URI
which will be handled by WebSphere Application Server.
There are two ways to regenerate the WebSphere plug-in configuration file.
1. Manually generate the plug-in configuration file:
a. From the WebSphere Administrative Console, select WebSphere
Administrative Domain -> Nodes, as shown in Figure 3-17, right-click
your node (shown as your computer’s name) and choose Regen
Webserver Plugin from the pop-up menu. Wait for the command to
Chapter 3. Installation and configuration
53
complete by monitoring the Event Message window on the bottom of the
Administrative Console.
Figure 3-17 WebSphere configuration - manually regenerate plug-in file
2. Automatically generate the plug-in configuration file:
a. Select ITSO Server, the application server we created for testing the
migration.
b. Click the Custom tab, select the Automatic Generation of Plugin
Configuration and click Edit.
c. A new window is displayed. Click Enabled and then click OK.
d. Click Apply.
54
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-18 WebSphere configuration - automatically regenerate plug-in file
Note: To make any changes persistent in the WebSphere Administrative
Console, do not forget to click Apply. Without applying, your configuration
work will not be saved.
Chapter 3. Installation and configuration
55
Figure 3-19 WebSphere configuration - Automatic generation of plug-in
From now on, the plug-in’s XML file will be automatically regenerated every time
the application server, ITSO Server, is restarted.
Define a JDBC driver and DataSource
Now we create a new database in DB2 named ITSO, and create two JDBC
drivers and two DataSources for it in WebSphere Application Server:
1. One DataSource is for non-JTA support and has a JNDI name of jdbc/itsods.
2. The other DataSource is JTA enabled, and has a JNDI name of jdbc/xaitsods.
The steps to create the required database and DataSources are:
1. Create a new database in DB2 UDB.
This can be done quite simply by entering the following commands:
db2cmd
db2 create db ITSO
2. Define non-JTA support JDBC driver and DataSource.
56
Migrating WebLogic Applications to WebSphere Advanced Edition V4
a. From the WebSphere Administrative Console, select WebSphere
Administrative Domain -> Resources, as shown in Figure 3-20,
right-click JDBC Providers and choose New... from the pop-up menu.
Figure 3-20 WebSphere configuration - Define a new JDBC driver step 1
b. A new window, JDBC Provider properties, shown in Figure 3-21 will be
displayed. Enter the values shown in Table 3-3. You can choose the
Implementation class from the list box of available classes.
Chapter 3. Installation and configuration
57
Figure 3-21 WebSphere configuration - Define a new JDBC driver step 2
Table 3-3 Values for JDBC provider properties - non-JTA
Name
Value
Name
DB2 non-JTA JDBC Driver
Implementation class
COM.ibm.db2.jdbc.DB2ConnectionPoolD
ataSource
c. Switch to the Nodes tab on the JDBC Provider Properties window, as
shown in Figure 3-23. Click Install New, select your node name (same as
your machine name), and specify where the JAR file containing your JDBC
driver is located. Click OK.
58
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-22 WebSphere configuration - Define a new JDBC driver step 3
The message shown in Figure 3-24 will confirm that the JDBC driver was created
successfully.
Chapter 3. Installation and configuration
59
Figure 3-23 WebSphere configuration - Define a new DataSource step 1
d. In the WebSphere Administrative Console, expand the DB2 non-JTA
JDBC Driver which you have just created, as shown in Figure 3-23, select
Data Sources, right click and choose New... from the pop-up menu.
e. The Data Source Properties window will be shown as in Figure 3-24. Enter
the values shown in Table 3-4, and click OK.
60
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-24 WebSphere configuration - Define a new DataSource step 2
Table 3-4 Values for DataSource properties - non JTA
Name
Value
Name
itsods
JNDI name
jdbc/itsods
DatabaseName
ITSO
user
db2admin
password
db2admin
3. Define a JTA-enabled JDBC driver and DataSource.
Repeat the same steps used to create the previous JDBC Driver as discussed
in 2 on page 56. At step b on page 57, use the data in Table 3-5 for the input
values.
Chapter 3. Installation and configuration
61
Table 3-5 Values for JDBC Provider properties - JTA enabled
Name
Value
Name
DB2 JTA enabled JDBC Driver
Implementation class
COM.ibm.db2.jdbc.DB2XADataSource
At step e on page 60, use the data in Table 3-6 for the input values.
Table 3-6 Values for DataSource properties - JTA enabled
Name
Value
Name
xaitsods
JNDI name
jdbc/xaitsods
DatabaseName
ITSO
user
db2admin
password
db2admin
3.2.4 WebSphere Studio Application Developer V4.0.2
In this section, we show how to install and configure WebSphere Studio
Application Developer for our migration work.
Install WebSphere Studio Application Developer
Installing WebSphere Studio Application Developer is straightforward:
1. Start the WebSphere Studio Application Developer setup program.
2. Accept the license agreement.
3. Choose an installation directory. We suggest that you use x:\WSAD, where x
is your preferred installation drive.
4. On the Primary User Role window, shown in Figure 3-25, select J2EE
Developer, then click Next.
62
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-25 WebSphere Studio Application Developer installation - Primary User Role
5. On the Select Version Control Interface window, ensure CVS is selected, as
shown in Figure 3-26, and click the Next button.
Chapter 3. Installation and configuration
63
Figure 3-26 WebSphere Studio Application Developer Installation - select CVS
64
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 3-27 WSAD Installation - InstallShield Wizard completed
6. When you see the InstallShield Wizard Completed window, shown in
Figure 3-27, it means that WebSphere Studio Application Developer has been
installed successfully.
Note: WebSphere Studio Application Developer does not have a built-in team
development environment, but it ships with support for two underlying team
products, CVS and Rational ClearCase LT, which will be installed separately
by the customer. In our migration work, the team development feature is not
used, so we did not install CVS or ClearCase LT. If team development is
important to your work, please refer to
http://www-3.ibm.com/software/ad/studioappdev/support/ for detailed
information.
Installation verification and configuration
To verify that WebSphere Studio Application Developer has been installed
correctly:
1. Start WebSphere Studio Application Developer by clicking Programs -> IBM
WebSphere Studio Application Developer -> IBM WebSphere Studio
Chapter 3. Installation and configuration
65
Application Developer. The workbench window of WebSphere Studio
Application Developer, as shown in Figure 3-28, will appear.
Figure 3-28 Start WebSphere Studio Application Developer
Please refer to Chapter 4, “Development and migration tools” on page 67 for
detailed information on configuration of WebSphere Studio Application
Developer.
66
Migrating WebLogic Applications to WebSphere Advanced Edition V4
4
Chapter 4.
Development and migration
tools
This chapter is focused on the tools that we used to support the migration of an
application from BEA WebLogic Server to WebSphere Application Server,
Advanced Edition. Information provided in this chapter is not intended to be a
detailed handbook of those development tools. We give an overview of each tool
and cover some important topics that are relevant to our migration activities.
The main tools we used for our migration work were the WebSphere Studio
Application Developer and the Application Assembly Tool.
© Copyright IBM Corp. 2002
67
4.1 WebSphere Studio Application Developer
WebSphere Studio Application Developer is built on the WebSphere Studio
Workbench, which is an integrated platform designed to provide a common set of
services and frameworks for development tool integration and tool construction.
WebSphere Studio Application Developer
WebSphere Studio
Site Developer
HTML/JSP Tooling
Servlet Tooling
Web Services Tooling
XML Tooling
+
J2EE Tooling
Data Tooling
Performance Tooling
Trace Tooling
Enterprise
Connectors
JCA Connectors
CCF Connectors
Enterprise Access
Builders
WebSphere Studio Workbench
Universal Tooling Platform
Provides frameworks, services,
and tools for tool builders to focus
on tool building
Will become basis for an open source
(not a product IBM sells)
Core Workbench technology basis for
all IBM Tooling
Figure 4-1 WebSphere Studio platform
WebSphere Studio Workbench is based on a Java open source community
project called the Eclipse Platform. For more information about WebSphere
Studio and the Eclipse platform, please refer to the following Web sites:
򐂰 IBM WebSphere Studio Workbench product overview:
http://ibm.com/software/ad/workbench/
򐂰 Home page of Eclipse.org:
http://www.eclipse.org
4.1.1 Overview of WebSphere Studio Application Developer
WebSphere Studio Application Developer is next-generation technology for Java
2 Platform, Enterprise Edition developers. It combines many popular features of
VisualAge for Java Enterprise Edition and WebSphere Studio Advanced Edition
(classic). Figure 4-2 shows some features provided by the Application Developer
configuration of WebSphere Studio.
68
Migrating WebLogic Applications to WebSphere Advanced Edition V4
WebSphere Studio Application Developer
Server Side Development
Client Side Development
Typical Activities
Typical Activities
Build EJBs
Develop XML Components
Build W eb Services
Generate Enterprise Access
Unit Testing/Debugging
Generate W eb Application
Templates
Customize Generated HTML, JSP
Customize Srevlet
Unit Testing/Debugging
Perspectives Typically Used
Perspectives Typically Used
J2EE, Data, Java, XML,
W eb
W eb, Java
Output
Output
Interfaces exposed as JavaBeans
for Client Side Activities
JAR Files
W eb Archives (WAR)
Testing/Debug
Application Assembly
Output
Enterprise Archives (EAR)
Deployment
Figure 4-2 Overview of WebSphere Studio Application Developer
WebSphere Studio Application Developer integrates various Web application
development roles into one integrated development environment for building,
testing and deploying J2EE applications. WebSphere Studio Application
Developer supports:
򐂰 Building J2EE applications with HTML pages, Java Servlets, JavaServer
Pages and Enterprise JavaBean components
򐂰 Creating Web services applications with open standards
򐂰 Generating XML documents from DTDs, schemas
򐂰 Enabling a collaborative team environment
򐂰 Optimizing application performance
򐂰 Enabling end-to-end local and remote testing
򐂰 Increasing productivity and creating high-quality applications using wizards
and code generators
Chapter 4. Development and migration tools
69
WebSphere Studio Application Developer has a number of features that make it
particularly useful for application migration projects designed for WebSphere
Application Server. These features include:
򐂰 JavaServer Pages, Java Servlets and Enterprise JavaBeans development
environment
򐂰 Create or edit deployment descriptor information and binding information
򐂰 Built-in WebSphere Application Server, supporting end-to-end local unit
testing
Compared with VisualAge for Java, WebSphere Studio Application Developer is
more focused on J2EE application development. It also has many similar
features to VisualAge for Java, such as incremental compilation, code formatter
and code assistant.
The main window in WebSphere Studio Application Developer is the workbench
window. The workbench provides an integrated development environment with
customized perspectives that support role-based development, providing a
common way for all members to create, manage, and navigate resources easily.
In migration work, it is possible for one team member to work on JSP and
servlets in the Web perspective, while others work in the server perspective for
testing and debugging. All the work related to migration can be done in the one
unified platform from end to end, such as importing source code, correcting the
errors, testing, changing/editing deployment descriptors, and exporting the
migrated enterprise application.
There are some terms used in WebSphere Studio Application Developer that you
should be familiar with before using the IDE. They include:
򐂰 Projects are the top level of organization of resources. A project contains files
and folders that are grouped into buildable units. A project is always related to
a specific task. Here are some typical projects related to our migration work:
– Enterprise Application project
As defined in the J2EE specification, an enterprise application project
corresponds to a J2EE application module. It contains the resources
needed for a J2EE application and may contain a combination of Web
modules, EJB modules, related JAR files, application client modules and
component deployment descriptors.
– Web project
As defined in the J2EE specification, a Web project corresponds to the
J2EE Web module. It contains servlets, JSPs, related JAR files, static
documents (such as HTML files or images), and component deployment
descriptors.
70
Migrating WebLogic Applications to WebSphere Advanced Edition V4
– EJB project
The EJB project contains all the resources needed for J2EE EJB module.
– Server project
This contains necessary information to describe the test environments
used in WebSphere Studio Application Developer.
򐂰 Views provide different ways of looking at the resources you are working on.
򐂰 Editors allow you to create and modify code.
򐂰 Perspectives are combination of views and editors that show various aspects
of the project resource, and are organized by developer role or task.
A perspective defines an initial set and layout of views and editors for
performing a particular set of development jobs. One or more perspectives
can be open in a single workbench window, as shown in Figure 4-3. You can
switch between perspectives in the same window.
Figure 4-3 Perspectives of WebSphere Studio Application Developer
Tip: It’s very useful to keep the Help perspective open in a separate window.
When you open the Help perspective, press the Shift key until the new
perspective window appears.
Chapter 4. Development and migration tools
71
WebSphere Studio Application Developer is based on WebSphere Studio
Workbench, which is an open tools development framework, so it is easy to plug
third-party products, such as JUnit and Apache Tomcat, into a comprehensive
WebSphere Studio Application Developer environment. You can also choose
different JDK versions for different Java projects within WebSphere Studio
Application Developer if necessary.
For more detailed information about how to use JUnit in WebSphere Studio
Application Developer, please refer to “JUnit” on page 109.
The J2EE and server perspectives are the two perspectives we used most
frequently in our migration work.
4.1.2 J2EE perspective
The J2EE perspective is the main perspective we used for migration work. In the
J2EE perspective, WebSphere Studio Application Developer provides an
integrated working environment where we can import or export enterprise
application EAR files, find out error codes, and edit or change deployment
descriptors.
When we started WebSphere Studio Application Developer, the J2EE
perspective automatically opened because we chose the J2EE perspective as
the primary user role when installing Studio.
Import EAR file
Migration work usually begins with importing the source code of WebLogic
application into the WebSphere Studio Application Developer workbench.
WebSphere Studio Application Developer supports several ways of importing
source code, such as EAR files, EJB JAR files, file systems and Zip files. We
suggest using an EAR file, which includes source code as the import source,
because WebSphere Studio Application Developer will automatically create the
projects and structures corresponding to the EAR file. If the source code is in file
system format, please use Ant or other tools to create the EAR file. For more
detailed information about Ant, please refer to 4.5.1, “Ant” on page 108.
Here are the steps for importing an EAR file into the WebSphere Studio
Application Developer J2EE perspective:
1. Choose File -> Import. An import window will appear, as shown in Figure 4-4.
72
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-4 Importing options for WebSphere Studio Application Developer
2. Choose EAR file and click Next.
3. On the Import EAR window, shown in Figure 4-5, enter the path to the EAR
file and a name for your new enterprise application project. Click Next if you
wish to modify the EAR manifest or specify your own project names.
Otherwise, click Finish.
Chapter 4. Development and migration tools
73
Figure 4-5 Import EAR file
4. An example of the Manifest Class-Path window is shown in Figure 4-6. This
window allows you to set up dependencies among the modules. This updates
the classpath in the manifest file. Select the dependent JARs for each module
and click Next or Finish.
74
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-6 Set module dependencies
5. An example of the EAR Modules window is shown in Figure 4-7. This window
allows you to name the projects for individual modules. Project names default
to the module names. Double-click a project name to change it. Click Finish.
Chapter 4. Development and migration tools
75
Figure 4-7 Name EAR projects
Note: WebSphere Studio Application Developer will automatically create
several projects corresponding to the type of modules contained in the
imported EAR file, based on the J2EE specification.
Locate errors
Here we import the Bank example into WebSphere Studio Application Developer,
See 12.4, “Banking example” on page 302 for details of this example application.
A very useful feature of WebSphere Studio Application Developer is that you can
immediately see how many code incompatibilities or errors you will have to fix to
get the application running under the WebSphere Application Server. Figure 4-8
shows how these errors will be displayed on the Tasks pane in the J2EE
perspective after importing the WebLogic application. You can jump into the
source code that contains the error or just double-click the task that you wish to
edit.
76
Migrating WebLogic Applications to WebSphere Advanced Edition V4
click here for filters
Figure 4-8 Problems shown in Tasks console
Filter by type
On the Tasks window, WebSphere Studio Application Developer provides a
useful function, called a filter. You can show the tasks you want, such as Java
problems, XML schema problems, build path problems. As shown in Figure 4-8,
you can activate the filter function on the tools bar in the Tasks window. As shown
in Figure 4-9, filters are very flexible. In this figure, we selected Java Problem
with severity of Error. This filter filters the error list, shown in Figure 4-8, to just 18
Java errors.
Chapter 4. Development and migration tools
77
Figure 4-9 Filter by type
Filter by resource
You can also filter the Tasks list to an individual project, module, or file. For
example, we often use the filter settings shown in Figure 4-10 to analyze error
messages by resource. Select On selected resource and its children. With this
filter, select a project to see just its messages, or select an individual file for its
messages. This helps you zoom in on resources with the most errors.
78
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-10 Filtering by project and children
EJB editors
According to the J2EE specification, each J2EE module has its own deployment
descriptor to describe the module. Editing these descriptors is a task left to J2EE
application programming tools. For our migration purposes, we used two ways to
edit and change the deployment descriptors:
򐂰 One is using the Application Assembly Tool shipped with WebSphere
Application Server. For details refer to 4.2.1, “Application Assembly Tool” on
page 101.
򐂰 The other way is through the WebSphere Studio Application Developer.
As with WebLogic, a WebSphere-created J2EE application usually provides two
deployment descriptors for each module: one is the J2EE standard deployment
descriptor, and the other is the IBM extended deployment descriptor. For
example, in the application module, there are two deployment descriptors: one is
application.xml that follows the J2EE standard and the other is
Chapter 4. Development and migration tools
79
ibm-application-ext.xmi, which is IBM extended deployment descriptor. Please
refer to Chapter 11, “Application assembly and deployment” on page 245 for
more information about the differences between the deployment descriptors
used by WebLogic and WebSphere.
Figure 4-11 shows how to use WebSphere Studio Application Developer tools to
edit a J2EE deployment descriptor.
Figure 4-11 Edit deployment descriptor
The steps to edit a descriptor using WebSphere Studio Application Developer
are:
1. From the J2EE perspective, expand the module that you want to edit.
2. Click the component that you want to edit.
3. Right click Open with from the context menu.
4. On the sub-context menu, click the right editor for the deployment descriptor,
for example, click EJB Editor for ejb-jar.xml, or click EJB Extension Editor
for ibm-ejb-jar-ext.xmi and ibm-ejb-jar-bnd.xmi.
80
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Tip: Initially we had trouble distinguishing between tasks performed using the
J2EE view pane and the Navigator pane of the J2EE perspective. We found
that you use the Navigator pane when you want see detailed resource
information, and you use the J2EE pane when you work with J2EE modules.
The J2EE pane gives a view of your project showing J2EE module
relationships, while the Navigator pane gives a view based on the file system
structure.
The EJB Extension editor supports the vendor-specific binding of deployed JNDI
names. These are for EJBs, EJB references, and DataSources. It also supports
the configuration of CMP finders. These operations are described in the next
three sections.
Bind ejb, ejb-ref, and resource-ref
Figure 4-12 shows the assignment of the JNDI named “home/Account” to the
EJB named TheAccount. Since this is a vendor-specific deployment descriptor,
we use the EJB Extension Editor. The assignment is made as follows:
1. Right click the ejb-jar.xml file in the ejbModule/META-INF folder.
2. Click Open With -> EJB Extension Editor.
3. Click the Bindings tab.
4. Expand all of the folders.
In this case there are three EJBs, three EJB references, and two resource
references that must be bound to JNDI names. You will notice that
WebSphere Studio Application Developer suggests that you use the EJB
home name as a JNDI name. Since overloaded names can lead to confusion,
we recommend that you use some other unique naming convention.
5. Just fill in the JNDI name at the top of Figure 4-12. Leave the DataSource
fields empty, even for the resource references.
6. Save when you are done.
If the META-INF/ibm-ejb-jar-bnd.xmi file did not previously exist, it is created by
this operation.
Chapter 4. Development and migration tools
81
leave these fields
empty
Figure 4-12 Bind JNDI names with EJB Extension Editor
Bind web.xml references
Web components also have references to EJBs and resources. You use the
web.xml editor to bind these JNDI names, following a procedure similar to that in
“Bind ejb, ejb-ref, and resource-ref” on page 81.
1. Select the WEB-INF/web.xml file.
2. Click Open With -> Web.xml editor.
3. Click the References tab. Figure 4-13 shows a partially completed list the
EJB references.
4. Enter the appropriate JNDI names in the JNDI Name column.
5. Toggle to the Resource references to assign JNDI names to the DataSource
references.
6. Save the results.
82
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-13 BInd JNDI names with Web.xml editor
Create finders
To complete the deployment of a CMP entity bean, you must provide the
appropriate SQL for its finder methods. This is done through the Finders tab of
the EBJ Extension Editor.
1. Select the ejb-jar.xml file.
2. Right click Open With -> EJB Extension Editor.
3. Click on the Finders tab.
4. Expand each of the entity beans to expose their finder methods. See
Figure 4-14.
5. For each method, select the Where clause radio button and enter the
appropriate SQL fragments.
6. Save the results.
Chapter 4. Development and migration tools
83
Figure 4-14 Create finder methods
Meet-in-the-middle RDB mapping
For migration projects, you will usually need to create the schema and mapping
information for EJB to database mapping. WebSphere Studio Application
Developer provides several ways to create a new EJB/RDB mapping, such as
bottom up, top down and meet in the middle. A migration project is more apt to
need the meet-in-the-middle approach in order to preserve the CMP beans and
the underlying database.
Here are the steps to create a meet-in-the-middle EJB/RDB mapping:
1. On the J2EE View pane, select the module or CMP bean for which you want
to create the mapping.
2. Right click Open With -> Mapping Editor as shown in Figure 4-15 on
page 85.
84
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-15 Mapping EJB to database
3. On Create new EJB/RDB Mapping window, select Meet In The Middle and
click Next.
4. On Database Connection window, fill in all the information needed for
connecting to the database that contains the table you want to mapping for.
Click Next. See an example in Figure 4-16.
Chapter 4. Development and migration tools
85
Figure 4-16 EJB to RDB Mapping (Creating connection)
5. On the Selective Database Import window, check the tables you want to map
and click Next. See an example in Figure 4-17.
86
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-17 EJB to RDB Mapping (Importing tables)
6. On the Create new EJB/RDB Mapping window, choose either Match by
Name and Type for automatic mapping, or None for manual mapping. See
Figure 4-18.
Figure 4-18 EJB to RDB Mapping (mapping option)
7. Click Finish.
See 12.4.6, “Meet-in-the-middle RDB mapping” on page 310 for a detailed
example of the manual mapping option.
This procedure creates or updates the following vendor-specific deployment
descriptors:
򐂰 META-INF/Map.mapxmi file
򐂰 META-INF/Table.ddl file
򐂰 META-INF/Schema folder
Chapter 4. Development and migration tools
87
Generate deployment code
Before testing the application on WebSphere Studio Application Developer, you
must generate the deployment code for your EJB modules, as follows:
1. On the J2EE View pane, expand the EJB modules, right-click ejb-jar, select
Generate, then click Deploy and RMIC Code... as shown in Figure 4-19.
Figure 4-19 Generate deployment code
2. On the Generate Deploy and RMIC Code for the Selected Enterprise Beans
window, check the EJBs that you want to generate deploy code and click
Finish.
4.1.3 Setup test server
There are two ways to setup a new WebSphere test server in WebSphere Studio
Application Developer: the one-step approach and the two-step approach. Both
approaches create the same new server and server configuration folders. The
one-step approach gives the same name to both folders, whereas the two-step
approach gives them different names. We prefer the two-step approach because
the distinct names make it easier to understand and describe the results.
88
Migrating WebLogic Applications to WebSphere Advanced Edition V4
The two-step procedure is as follows:
1. Open Server Perspective.
2. On the Server Configuration pane, right-click Server Instances.
3. Select New.
This is where you choose between the one-step and the two-step
approaches. See Figure 4-20. Server Instance and Server Configuration is
the one-step option.
Figure 4-20 Two ways to create server and configuration instances
4. Create the server configuration — see Figure 4-21.
Chapter 4. Development and migration tools
89
Figure 4-21 Create server configuration
a. Click New -> Server Configuration.
b. Enter a distinct Configuration name, such as Banking Server
Configuration .
c. Enter Servers as the folder name.
d. Expand the WebSphere Servers folder and select WebSphere v4.0
Configuration.
e. Click Next if you want to specify an HTTP port number other than 8080.
f. Click Finish.
5. Create the server instance. See Figure 4-22.
90
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-22 Create server instance
a. Click New -> Server Instance.
b. Enter a distinct Server instance name, such as Banking Server Instance.
c. Expand WebSphere Servers folder and select WebSphere v4.0 Test
Server.
d. Click Finish.
6. Add project to Configuration.
a. Expand the Server Configurations folder and select your newly created
configuration.
Chapter 4. Development and migration tools
91
b. Right click Add Project -> BankingApp, or whatever your application
project is called.
7. Associate configuration with the server.
a. Expand the Server Instances folder and select your newly created server
instance.
b. Right-click Set Configuration -> Banking Server Configuration, or
whatever you named your new configuration.
Now your server configuration window should look something like Figure 4-23.
Figure 4-23 Server configuration
Configure database
The test server must be configured for any databases that are used by your
application. This involves defining a JDBC driver and its DataSource. See
Figure 4-24.
92
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-24 Bind DB2 database to DataSource JNDI name
Follow these steps:
1. Expand the Server Configurations and double-click the name of your server
configuration — WebSphere Administrative Domain in this case.
2. Select the Data source tab in the resulting configuration editor.
3. Select the DB2sdbcDriver.
4. Click Edit... to verify the classpath setting; click OK to return to the editor.
5. Click Add to the right of the DataSource list (this is the second editor pane).
6. Complete the fields in the resulting Edit a Data Source window.
a. The Name field is required, but it is just a display name — enter a
descriptive name.
b. The JNDI name must be the JNDI name bound in the deployment
descriptors of your EJB and Web components.
c. The DB2 database name, user ID, and password must also be entered.
d. Click OK to configure the DataSource.
7. Save your modified server configuration.
Chapter 4. Development and migration tools
93
Note: Press Ctrl + S to save any changes you have made before switching to
any other window or pane.
Start/stop the test server
If you have not already added your application to the test server, you will have to
do it before starting the server.
Before starting the test server, you must first install the application that you want
to test or debug into the testing server. On the Server Configuration pane,
right-click your server configuration, select Add Project, then select the project
that you want to debug or test, as shown in Figure 4-25.
Figure 4-25 Add Project to test server
You can choose to start the test server in WebSphere Studio Application
Developer either in normal running mode, which means that breakpoints will not
be active, or in debug mode which supports active breakpoints.
In the Server perspective, switch to the Servers pane, right-click the test server,
and choose either Debug or Start, to start the test server running in debug mode
or normal mode, as shown in Figure 4-26.
94
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-26 Start the test server
Switch to the console window to see the output messages of the test server. If
the test server starts successfully, you will get the following message:
Default Server Open for e-business.
The built-in WebSphere test environment for WebSphere Studio Application
Developer is based on a WebSphere Application Server single server. The
resources used by the test server is the same as a real WebSphere Application
Server, such as ORB bootstrap port and service daemon port. You will get an
error message window, as shown in Figure 4-27, when you try to start test server
in WebSphere Studio Application Developer without stopping the real
WebSphere Application Server running on your platform.
Figure 4-27 Error window for starting test server
Chapter 4. Development and migration tools
95
The procedure to stop the test server is the same as starting the server. In the
Servers perspective, switch to the Servers pane, right-click the test server, and
choose Stop.
Run on server
To run your application on the WebSphere Studio Application Developer test
server, do as follows:
1. Select your J2EE application project.
2. Right-click the Run on Server operation — this may take a while, so be
patient.
3. Check the resulting server console to make sure everything initialized
properly.
Your application will be published to and loaded into the test server, and the
server will start.
You can even perform this operation if you have not yet defined and configured a
test server according to the instructions in “Setup test server” on page 88. In this
case, a default test server, server configuration, and Servers project will be
created for you automatically. This is often the easiest way to start testing a new
application. You can perform any needed database configuration later, according
to the steps in “Configure database” on page 92.
Using the EJB test client
WebSphere Studio Application Developer provides a useful tool, called the IBM
EJB test client. It is a browser-based tool, and you do not need to code any EJB
test client. Just open a browser, as shown in Figure 4-28, and enter the following
URL:
http://127.0.0.1:8080/UTC/
With the IBM EJB Test Client, you can explore the JNDI name tree, and test each
individual method in your EJBs.
96
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-28 IBM EJB test client
Export EAR file
After using WebSphere Studio Application Developer to migrate a J2EE
application, you should export the final results as an EAR file. This is an easy
task.
1. Select your J2EE application project.
2. Click File -> Export.
3. Choose the EAR format and specify the file name and location.
4. It is a good practice to include source code, so select the Export source files
option.
5. Click Finish.
The resulting EAR file can be deployed on the WebSphere Application Server.
Chapter 4. Development and migration tools
97
Deploy on WebSphere
Deploy your J2EE application on WebSphere Application Server, Advanced
Edition V4 with the following steps:
1. Start the Windows NT service called “IBM WS Admin Server 4.0”, if not
already started.
2. Open the WebSphere Administrative Console.
3. Create an application server and add a JDBC provider and a DataSource as
explained in Chapter 3, “Installation and configuration” on page 35.
4. Select Enterprise Application, right-click, Install Enterprise Application —
see Figure 4-29.
Figure 4-29 Deploying EAR (Specifying the application)
5. Choose default settings for consecutive windows — for example, security
roles as shown in Figure 4-30.
98
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-30 Deploying EAR (mapping user to roles)
6. Specify where you want to install each module on the Selecting Application
Server window. See Figure 4-31.
Chapter 4. Development and migration tools
99
Figure 4-31 Deploying EAR (selecting application servers)
7. The next window will give the summary of where the application will be
installed. Click Finish.
8. The window shown in Figure 4-32 will appear. Click No if you generated
deploy code in the WebSphere Studio Application Developer, in which case
there is no need to regenerate it.
Figure 4-32 Deploying EAR (regenerate code window)
9. You need to regenerate the Web server plug-in as described in Chapter 3,
“Installation and configuration” on page 35.
100
Migrating WebLogic Applications to WebSphere Advanced Edition V4
4.2 Tools shipped with WebSphere
Basically, the tools shipped with WebSphere can be split into two categories: one
for assembly and building the enterprise application, EAR file or JAR file, and the
other for deploying and installing the enterprise application.
The administration console of WebSphere Application Server is used as the tool
for deployment and installation. The tools that deal with assembly and building
are the Application Assembly Tool (AAT) and EJBDeploy. In this sector, we will
introduce some features of the Application Assembly Tool and EJBDeploy that
will be relative to our migration work.
4.2.1 Application Assembly Tool
The tools shipped with WebSphere Application Server are the ones that have
undergone major changes in WebSphere Application Server V4. In WebSphere
V4, IBM has provided full support for the J2EE specification with the new
WebSphere tool, Application Assembly Tool, which is used for packaging and
assembling the enterprise application package required by the J2EE
specification.
The Application Assembly Tool is a graphical user interface tool that allows you to
do the following:
򐂰 Create or edit a J2EE application, EAR file from other J2EE modules, EJB
JAR file, or Web application WAR file.
򐂰 Create or edit the J2EE modules:
– Web application modules
– EJB modules
– Application Clients modules
򐂰 Create or edit deployment descriptor and binding information.
򐂰 Generate deployed code.
Your can start AAT by selecting Programs -> IBM WebSphere -> Application
Server V4.0 AE -> Application Assembly Tool or using the command line,
such as C:\WebSphere\Appserver\bin\assembly.bat.
When AAT starts, you can choose a new task by clicking File -> New, as shown
in Figure 4-33.
Chapter 4. Development and migration tools
101
Figure 4-33 AAT menu - New
Within the New submenu, you have several choices:
򐂰 Application
With this choice, AAT will present an empty framework, a tree view, containing
the various aspects of an enterprise application. Within the framework, you
can create one or more EJB modules, Web modules and application clients.
For example, you can right-click EJB Modules and you will get a context
menu for working with EJB modules, shown in Figure 4-34.
102
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 4-34 AAT menu - work on EJB modules
From the context menu, you can create a new EJB module from either a new
empty EJB module or from an existing EJB module JAR file.
򐂰 EJB module
AAT provides an empty EJB module framework.
򐂰 Web Module
AAT provides an empty Web module framework.
򐂰 Application Client
AAT provides an empty application client module framework.
The valuable feature on AAT that we use frequently in our migration work is the
create or edit deployment descriptor and binding information for each J2EE
module. With the GUI interface provided by AAT, it’s very easy to create or edit
deployment descriptor information (J2EE standard and IBM extension) and
binding information with any J2EE modules.
Chapter 4. Development and migration tools
103
Figure 4-35 AAT - edit deployment descriptor and binding information
Select any J2EE modules you want to edit, for example, an entity bean, shown in
Figure 4-35. On the right part of the window, you can choose deployment
descriptors on three tabs:
򐂰 General
The information in the General tab corresponds to the J2EE standard EJB
deployment descriptor ejb-jar.xml.
򐂰 IBM Extensions
The information in the IBM Extensions tab corresponds to the IBM extended
EJB deployment descriptor ibm-ejb-jar-ext.xmi.
򐂰 Bindings
The information in the Bindings tab corresponds to the IBM extended EJB
binding information ibm-ejb-jar-bnd.xmi.
Note: Click File -> Save or Save as before you want exit AAT, AAT will not
automatically save your work when you exit AAT.
104
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Another valuable feature of AAT is that it can automatically convert EJB JAR files
from 1.0 to 1.1 format. This feature is very useful when you choose VisualAge for
Java V4 as the main development IDE for migration work. By now, VisualAge for
Java only supports EJB 1.0. For detailed information, refer to 4.3, “VisualAge for
Java” on page 106.
Figure 4-36 AAT - convert from V1.0 to V1.1
When you open an EJB JAR file into AAT, AAT will detect the version of EJB. If it
found the EJB JAR file is Version 1.0, you will get the EJB 1.0 Dependent
Classpath window, shown as in Figure 4-36. On this window, specify any
dependent classpath if it is needed for conversion (commonly leave it blank),
then click OK and save the JAR file. An EJB module containing the converted
JAR file is automatically created by AAT.
For more detailed information about how to use the Application Assembly Tool,
please refer to section 6.6.0.5 in the WebSphere InfoCenter at:
http://www-3.ibm.com/software/webservers/appserv/infocenter.html
4.2.2 EJBDeploy
EJBDeploy is a tool shipped with the WebSphere Application Server, Advanced
Edition and is used to generate Enterprise JavaBean deployment code. The EJB
Deploy tool, EJBDeploy, provides a command line interface that you can invoke
from a command line, such as <websphere>\application\bin\ejbdeploy.
In fact, EJBDeploy is used by Application Assembly Tool and Administrative
Console also. When you try to generate Enterprise JavaBean deployment code
from Application Assembly Tool or the Administrative Console, those tools will
call EJBDeploy under their covers.
EJBDeploy is useful in our migration work. You may choose VisualCafe or some
other tool to migrate the EJB codes from WebLogic to WebSphere, then edit
those deployment descriptors and package the EJB JAR file by yourself. Then,
EJBDeploy will help you to generate deployment code for the packaged EJB JAR
file.
Chapter 4. Development and migration tools
105
When you invoke the ejbdeploy command, it will do the following:
򐂰
򐂰
򐂰
򐂰
򐂰
Code is imported from the input JAR file
Deployment code is generated
RMIC is run
The deployment code is compiled
Code is exported to the output JAR file
For more detailed information about how to use EJBDeploy tool, please refer to
Chapter 6, “Tools and resources quick reference”, in the WebSphere InfoCenter
at http://www-3.ibm.com/software/webservers/appserv/infocenter.html.
4.3 VisualAge for Java
In our previous redbook, Migrating WebLogic Applications to WebSphere
Advanced Edition, SG24-5956, VisualAge for Java is used as the main tool for
development and migration codes from WebLogic to WebSphere.
VisualAge for Java is an award-winning Java development environment. From
V3, VisualAge for Java has included features that fully support WebSphere
Application Server’s development. One is a powerful integrated debugger and
test environment named WebSphere Test Environment. WebSphere Test
Environment is a smooth integration of the WebSphere Application Server with
the VisualAge for Java IDE. With WebSphere Test Environment, you can test and
debug the Java Servlets, JavaServer Pages, Enterprise JavaBeans and other
server components and classes before you deploy the code into a real
WebSphere Application Server.
In WebSphere Application Server V4, there are some changes in the IBM
development tool strategy. IBM has announced a new tool, WebSphere Studio
Application Developer, based on WebSphere Studio Workbench. WebSphere
Studio Application Developer provides some excellent features for developing
and testing applications running in WebSphere. For more detailed information
about WebSphere Studio Application Developer, refer to “WebSphere Studio
Application Developer” on page 68.
The latest version of VisualAge for Java is Version 4. The WebSphere Test
Environment provided by VisualAge supports WebSphere Application Server
V3.5.3. This means you can debug and test Java Servlets with specification level
2.2, JavaServer Pages with level 1.1,and Enterprise JavaBeans with 1.0+. Also,
VisualAge for Java V4 would not support automatically generating or editing the
deployment descriptor. If you continue using VisualAge for Java V4 as a
development and testing tool for WebSphere Application Server V4, you may
106
Migrating WebLogic Applications to WebSphere Advanced Edition V4
face some problems in testing and debugging your server-side Java code. It
would be preferable to use WebSphere Studio Application Developer as the
Web-enabled enterprise applications development and testing IDE instead of
VisualAge for Java.
The VisualAge for Java V4 also provides some new features to continue to
support those who prefer this Java development IDE. One of these features
relative to our migration work is EJB 1.1 deployment support. VisualAge for Java
still uses the old (EJB 1.0) deployment descriptor approach inside the IDE, with
the uneditable serialized object stored in a file (.ser). You now have two choices
to migrate them to EJB 1.1 specified XML descriptors:
1. Using the new feature of VisualAge for Java, EJB 1.1 deployment support, at
the point when you want to export the whole EJB JAR file to the file system,
VisualAge for Java will automatically convert the serialized object to XML
deployment descriptors.
2. Directly exporting the EJB JAR file with a serialized object descriptor to the
file system. Using Application Assembly Tool to input the EJB 1.0 JAR file,
AAT will automatically convert the deployment descriptors to the EJB 1.1
standard.
For more detailed information about how to use VisualAge for Java, please refer
to http://www-3.ibm.com/software/ad/vajava/.
4.4 WebSphere Studio (classic) and other JSP editors
In our previous redbook, Migrating WebLogic Applications to WebSphere
Advanced Edition, SG24-5956, WebSphere Studio (classic) is not recommended
by the authors, partly because it does not support JSP 1.1.
At the time we wrote this redbook, the latest version of WebSphere Studio is V4
supports the visual layout of dynamic Web pages and support JavaServer Pages
1.1, Java Servlets 2.2, full HTML, JavaScript and DHTML.
For working convenience, we chose WebSphere Studio Application Developer as
our main migration tool for JavaServer Pages and Java Servlets, because in one
unified development IDE, we can develop and test all the J2EE modules. For
detailed information about WebSphere Studio Application Developer, refer to 4.1,
“WebSphere Studio Application Developer” on page 68.
For more detailed information about how to use WebSphere Studio (classic),
please refer to http://www-3.ibm.com/software/webservers/studio/.
Chapter 4. Development and migration tools
107
Some WebLogic JSP applications will probably be developed with WebGain
Studio, and some will prefer to use plain editors, such as UltraEdit, to develop
JSPs. In our migration work, we used Application Assembly Tool to assemble
and edit deployment descriptors for those codes that are not developed by
WebSphere Studio Application Developer. For more detailed information about
Application Assembly Tool, refer to “Application Assembly Tool” on page 101.
4.5 Other tools from third parties
In this section, we introduce some tools from third parties that are useful in our
migration work.
4.5.1 Ant
The task of building an application are generally simple but may be long-winded,
and during the course of our migration work will be repeated many times by each
developer. Ant is a tool that provides a framework that implements extensions in
Java to help developers to solve those issues. The base Ant package comes with
a comprehensive set of standard extensions (known as tasks in Ant) for
performing common actions such as compiling source code and manipulating
files.
Ant uses an XML build files, called build.xml, to describe what tasks must be
performed in order to build a project. Basically, the build files contain the following
components:
򐂰 Projects
A build file contains build information for a single project. It may contain one or
many targets.
򐂰 Targets
A target describes the tasks that must be performed to satisfy a goal. Targets
may depend upon other targets. Ant will resolve these dependencies.
򐂰 Tasks
A task is a single step that must be performed in order to finish a target.
򐂰 Properties
A property has a name and a value.
򐂰 Paths
A path is a set of directories or files. A path can be defined once and referred
to multiple times.
108
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Ant is a subproject of the Apache Jakarta project, part of the Apache Software
Foundation. You can find out more detailed information about Ant using the
following URL: http://jakarta.apache.org/ant/.
At the time we wrote this redbook, the latest release of Ant available was Version
1.4.1. You can download it from the Apache Web site at:
http://jakarta.apache.org/builds/jakarta-ant/release/v1.4.1/.
Configuring Ant is a very simple task. After unpacking the binary distribution file
to C:\ant, just set up the environment variables. Here, we use JDK V1.3 shipped
with WebSphere Application Server V4.
Example 4-1 Values for setup environment
set ANT_HOME=c:\ant
set JAVA_HOME=c:\WebSphere\Application\java
set PATH=%PATH%;%ANT_HOME%\bin
In our migration work, Ant is used as an automatic build tool that will build an
EAR file from the source code that we want to migrate, then import the EAR file
into WebSphere Studio Application Developer.
For detailed information about how to use Ant, refer to the Ant documentation at
http://jakarta.apache.org/ant/manual/index.html.
4.5.2 JUnit
JUnit is a useful tool when you want to do automatic unit testing. It’s an open
source testing framework that is used to develop and execute unit tests in Java.
At the time we wrote this redbook, the latest version of JUnit was Version 3.7.
You can download it from http://www.junit.org/index.htm, where you can also
find more information about JUnit.
At the time we wrote this book, WebSphere Studio Application Developer is
supported by JUnit. If you want to set up JUnit with WebSphere Studio
Application Developer V4, follow these steps:
򐂰 Download the plug-in org.junit and org.eclipse.jdt.junit from the JUnit Web
site.
򐂰 Stop WebSphere Studio Application Developer.
򐂰 Unpack the plug-ins you have downloaded into a WebSphere Studio
Application Developer plug-in directory, for example, C:\wsad\\plugins.
򐂰 Start WebSphere Studio Application Developer. You will find a new Run
Launcher, JUnit Tests, shown in Figure 4-37.
Chapter 4. Development and migration tools
109
Figure 4-37 JUnit work with WebSphere Studio Application Developer
110
Migrating WebLogic Applications to WebSphere Advanced Edition V4
5
Chapter 5.
Security
The Internet has many resources that can be accessed by many people, some of
whom may have malicious intentions. Before examining the Java 2 Platform,
Enterprise Edition specifications on security, we look at some of the aspects that
should be provided by a security infrastructure. A full description of a security
infrastructure is beyond the scope of this book, but our overview helps to position
the J2EE approach within the wider context of security requirements.
By security we mean the ability to protect sensitive business data and also
general protection against attacks, such as Denial of Service (DoS). Whenever
we connect to another computer using TCP/IP, the information will pass through
many intermediate computers and it is possible for someone to watch and even
change that transmission.
© Copyright IBM Corp. 2002
111
5.1 Elements of security
Our enterprise application will contain some resources that we may want to
restrict access to. To achieve this goal there are several issues that must be
considered. They share some of the following characteristics:
򐂰 Authentication
By authentication we mean the ability to determine the identity of the
communication parties, either client and/or server. A common way is to check
a user name and password against a names directory, even though this can
be accomplished in many different ways.
򐂰 Access control for resources
This is the ability to restrict access to some resources, depending on the
authenticated entity.
򐂰 Data integrity
This is the ability to assure the information exchanged between the client and
server has been sent in such a way that it cannot be altered by anyone.
Therefore, if the client or server notice that the information has been modified,
it can be discarded.
򐂰 Confidentiality or data privacy
By confidentiality we mean the ability to send the information in such a way
that any third party that may intercept it will not be able to understand it,
because the content of that transmission is encrypted. In most cases, if we
specify data integrity and privacy, we will use SSL.
򐂰 Non-repudiation
This is the ability to verify that the client has performed an operation and to
prevent the client from denying that the action took place.
򐂰 Auditing
This is the core of security. No system is likely to be so secure that it cannot
be breached so it is very important for the administrator to have a way to
regularly audit the security-related aspects of the application.
5.2 What does J2EE specify?
There are several requirements that have to be met by any J2EE-1.2 compliant
server. We discuss the most relevant in this section. If you need any further
information, refer to the J2EE specifications.
112
Migrating WebLogic Applications to WebSphere Advanced Edition V4
The goals of J2EE security are:
򐂰 Portability
The application must be deployable in any compliant application server.
򐂰 Transparency
The deployers should not need to know about security-related aspects in
order to have a secured application (security is the responsibility of the
administrators).
򐂰 Isolation
It is the deployer’s responsibility to specify the security policy using the
deployment descriptors.
򐂰 Extensibility
For those applications that need to perform some security checks, the
portability must not be compromised and therefore an API is defined.
򐂰 Flexibility
Security properties of applications should not impose a particular security
policy, but facilitate the implementation of security policies specific to the
particular J2EE installation.
򐂰 Security interoperability
This issue has been addressed with the latest J2EE 1.3 specification.
Application components must be able to invoke secured services provided by
another vendor.
There are different ways to achieve these goals. One is declarative, where we
specify in the deployment descriptors the security constraints. The other is
programmatic, where we access the security-related aspects of an application
through a common API.
5.3 Security differences
Both WebLogic and WebSphere application servers are compliant with the
security model of Java 2 Platform, Enterprise Edition 1.2. The newer J2EE
Version 1.3 is a super set of 1.2 and adds a requirement for security
interoperatibility as described in 5.2, “What does J2EE specify?” on page 112,
but neither WebLogic nor WebSphere currently supports this feature. The
security aspects that are addressed by both application servers are quite
complex, so we only discuss some of the more generic aspects. For more details
of the security infrasture provided by WebSphere Application Server, Advanced
Edition, refer to the redbook IBM WebSphere V4.0 Advanced Edition Security,
SG24-6520.
Chapter 5. Security
113
5.3.1 Authentication mechanism
When BEA WebLogic Server is installed, the authentication mechanism that is
installed is the FileRealm. The information is stored in a file called
fileRealm.properties located in the administration server directory. The
information stored in that file is about users and groups as well as ACLs, for the
resources provided by WebLogic. By default when installing WebSphere
Application Server, security is not enabled and we have to activate it
system-wide in order to use the J2EE security features.
There is no easy way to migrate fileRealm.properties file from WebLogic
because WebSphere Application Server does not use a similar mechanism.
Instead WebSphere may use the system registry or LTPA for its authentication
mechanism. We have two migration options if we use LTPA:
1. LDAP
We may use an LDAP registry. We can configure WebSphere for use with
Netscape, Domino 4.6, Domino 5.0, SecureWay and Active Directory. We
may also use a custom registry and use the advanced LDAP properties to
configure the connection.
2. Custom user registry
This is a user-defined registry that implements the
com.ibm.websphere.security.CustomRegistry interface.
WebLogic ships with built-in example configuration properties for Windows NT
Realm, UNIX Realm, RDBMS Realm, Custom Realm and the following LDAPs:
Netscape Directory Server, Novell Directory Services, OpenLDAP Directory
Services and Microsoft Site Server. If the authorization mechanism that is used
by the WebLogic application is one of the common ones, it will be quite
straightforward to migrate. If not, we will have to research the manufacturer
documentation of the authorization mechanism.
A WebLogic security realm is a logical grouping of Users, Groups, and ACLs. A
WebLogic server resource is protected under only one security realm and by a
single ACL in that security realm. In WebSphere Application Server, we cannot
define ACLs and therefore we will not be able to migrate that part.
To enable security in WebSphere Application Server we use the WebSphere
Administrative Console security center, as shown in Figure 5-1.
114
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 5-1 Invoking the Security Center
Click the Enable Security check box in order to enable global security for
WebSphere Application Server.
Click the Authentication tab to configure the authentication mechanism of our
choice. See Figure 5-2. We selected Local Operating System as the
authentication mechanism. We chose this because we will be defining operating
system users and groups as described in 5.4, “WebSphere Studio Application
Developer approach” on page 120, but we do not recommend this for production
environments, since you will not be able to take advantage of other features
provided by WebSphere Application Server such as clustering. If we have a
WebSphere node running on another box it will not be able to authenticate the
users against other machines’ user registries.
Chapter 5. Security
115
Figure 5-2 Authentication tab
Figure 5-2 shows where the security administration for WebSphere Application
Server is centralized. Click the Role Mapping tab in order to change the
mappings for a given enterprise application.
The information containing the mapping for the user roles and the authorization
mechanism entries are defined in a specific WebSphere Application Server file,
ibm-application-ext.xmi. We may modify this file when deploying our application.
Or we may modify the file at any time using the WebSphere Administrative
Console as described above.
From the window shown in Figure 5-2 we may specify system-wide values for
SSL configuration. These values are specified by clicking Default SSL
Configuration on the General tab.
116
Migrating WebLogic Applications to WebSphere Advanced Edition V4
We used the default values during our migration testing, but we recommend that
you change the default DummyServerTrustFile.jks key file and trust file for
production systems.
5.3.2 Data integrity and privacy. Configuring SSL
If the enterprise application deployed in WebLogic is accessed using SSL, we
have to configure the SSL settings for our application in WebSphere Application
Server.
Let’s assume for our sample purposes that we have the scenario shown in
Figure 5-3.
Figure 5-3 Security scenario
Chapter 5. Security
117
Configuring SSL between the browser and the Web server is a task that is Web
server specific, but it will be the same whether the target application server is
WebLogic or WebSphere. For a discussion on how to configure IBM HTTP
Server to enable HTTPS and SSL, refer to the redbook IBM WebSphere V4.0
Advanced Edition Security, SG24-6520. We will focus on the configuration of the
connection from the Web server to WebSphere Application Server. This
configuration is specific to the security implementation of WebSphere and a full
description of it is outside the scope of our redbook.
By default, communication between the Web server and WebSphere Application
Server is not secure, even if global security is enabled for WebSphere. Securing
this connection involves changes to both the Web server plug-in and to the
embedded HTTP server in the WebSphere Web container. As explained in the
redbook IBM WebSphere V4.0 Advanced Edition Security, SG24-6520, the high
level steps for configuring SSL between the Web server and WebSphere
Application Server are:
1. Create a self-signed certificate for the Web server plug-in.
2. Create a self-signed certificate for the embedded HTTP server in the
WebSphere Web container.
3. Exchange the public keys.
4. Modify the Web server plugin-cfg.xml to use SSL/HTTPS.
<WAS-install-dir>\config\plugin-cfg.xml must be edited uwing any text editor
of your choice, and the following directive groups must be configured as
specified in the InfoCenter section 6.6.18.1a.7:
– VirtualHostGroup
We define the virtual hosts.
– URIGroup
We specify those URIs that will be forwarded to WebSphere Application
Server.
– ServerGroups
We define the transports for the server groups.
– Route
We specify the relationships of the other three directives.
For more information about these directives, see the InfoCenter, section
6.6.18.1a.7.
118
Migrating WebLogic Applications to WebSphere Advanced Edition V4
5. We modify the embedded HTTP server in the WebSphere Web container to
use SSL/HTTPS.
For our purposes, we open the WebSphere Application Server, Advanced
Edition console and expand the WebSphere Adminstrative Domain. Then we
expand the Nodes folder and our node. After expanding the Application
Servers folder, we select our application server, called ITSO Server. In the
Services tab on the right side of the Administrative Console, we edit the
properties for the Web Container Service.
We will have to create a new HTTP transport connection. In order to do so, we
click Add and specify the properties, as shown in Figure 5-4.
Figure 5-4 HTTP Transport Properties
We will use the global system properties we specified in 5.3.1, “Authentication
mechanism” on page 114
Chapter 5. Security
119
5.4 WebSphere Studio Application Developer approach
This section describes how to deploy a secure EAR file to WebSphere
Application Server using WebSphere Studio Application Developer to generate
the specific deployment descriptors and to package the application.
We focus on declarative, not programmatic security, even though we will find the
user who logged in programmatically. For sample purposes, we are going to
migrate a servlet that performs a client call to a HelloWorld EJB we developed
and deployed on BEA WebLogic Server. We have secured the POST and GET
method of the servlet and the hello() method of the EJB.
We granted authorization to two groups for the servlet and to one of them for the
EJB: normalusers and powerusers for the Servlet, and powerusers for the EJB.
Therefore if we call the servlet as a normal user, we will get an exception from
the container when the servlet calls the remote method hello(). Actually we only
secured a remote method for the EJB, the hello() method, that will return to our
servlet the String Hello World.
The exception that the EJB container of BEA WebLogic Server V6.1 throws if the
user that called the remote method hello() doesn’t have the required rights is
java.rmi.AccessException, while WebSphere Application Server throws
java.rmi.ServerException. Therefore, any block prepared to catch
java.rmi.AccessException should be migrated.
First we import the EAR file from our WebLogic application into WebSphere
Studio Application Developer and configure the descriptors regarding security for
this particular Servlet and EJB. Since WebSphere Studio Application Developer
uses WebSphere Application Server, Advanced Developer Edition for a test
environment, we have to use the operating system as our names directory. It is
simple enough to map the user roles to an LDAP directory or any other
supported system once we deploy our application to WebSphere Application
Server, Advanced Edition. It is very important that if you are using Windows NT
your account user has the advanced user right to act as a part of the operating
system.
Our EAR file deployed to WebLogic is shown in Figure 5-5.
120
Migrating WebLogic Applications to WebSphere Advanced Edition V4
SecureSampleProject.ear\
.. This is the root of our application
META-INF\
application.xml
.. Descriptor for the application
SecureEJBProject.jar\
ejb-jar.xml
.. ejb deployment descriptors
weblogic-ejb-jar.xml
weblogic-cmp-rdbms-jar.xml
META-INF\
itso\
examples\
security\
ejb\
HelloWorld.java
HelloWorldBean.java
HelloWorldHome.java
SecureSampleWebModule.war\
META-INF\
web.xml
weblogic.xml
WEB-INF\
classes\
itso\
.. Web application deployment
descriptors
examples\
security\
SecuredServlet.java
lib\
Post.html
Figure 5-5 Directory structure
We copied the SecureSampleProject.ear file into a temporary directory and
erased the weblogic.xml file and weblogic-ejb-jar.xml since they are specific to
WebLogic.
Once we erased the WebLogic-specific files, this left us with a single EAR file
with our code and the three J2EE standard deployment descriptors: one
descriptor for the application, one for the Web module, and a third for the EJB
module.
The application.xml is the J2EE file that provides information for our Web
module, EJB module, and the security roles. An example of our application.xml
file is shown in Example 5-1.
Example 5-1 application.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application
1.2//EN" "http://java.sun.com/j2ee/dtds/application_1_2.dtd">
<application id="Application_ID">
<display-name>SecureSampleProject</display-name>
<module id="WebModule_1">
<web>
<web-uri>SecureSampleWebModule.war</web-uri>
<context-root>itso</context-root>
</web>
Chapter 5. Security
121
</module>
<module id="EjbModule_1">
<ejb>SecureEJBProject.jar</ejb>
</module>
<security-role id="SecurityRole_1">
<description>These users are allowed to access the servlet</description>
<role-name>normalusers</role-name>
</security-role>
<security-role id="SecurityRole_2">
<description>These users are allowed to access the servlet and
ejb</description>
<role-name>powerusers</role-name>
</security-role>
</application>
In the web.xml file, we have information about the servlet class and name, servlet
mappings, security roles, and the security constraints, based on the security
roles. Note that the <display-name> element should be removed. An example of
our web.xml file is shown in Example 5-2.
Example 5-2 web.xml
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">
<web-app>
<servlet>
<servlet-name>SecuredServlet</servlet-name>
<servlet-class>itso.examples.security.SecuredServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>SecuredServlet</servlet-name>
<url-pattern>/SecuredServlet</url-pattern>
</servlet-mapping>
<welcome-file-list>
<welcome-file>Post.html</welcome-file>
</welcome-file-list>
<security-constraint>
<display-name>RestrictedServlet</display-name>
<web-resource-collection>
<web-resource-name>RestrictedServlet</web-resource-name>
<description>We secured the post method</description>
<url-pattern>/SecuredServlet</url-pattern>
122
Migrating WebLogic Applications to WebSphere Advanced Edition V4
<http-method>POST</http-method>
<http-method>GET</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>normalusers</role-name>
<role-name>powerusers</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<description>These users are allowed to access the servlet</description>
<role-name>normalusers</role-name>
</security-role>
<security-role>
<description>These users are allowed to access the servlet and
ejb</description>
<role-name>powerusers</role-name>
</security-role>
</web-app>
In our sample application, the information stored in the ejb-jar.xml file is the
information concerned with describing the EJB and securing it. This includes the
roles and the method that have been secured. See Example 5-3.
Example 5-3 ejb-jar.xml
<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans
1.1//EN' 'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>
<!-- Generated XML! -->
<ejb-jar>
<enterprise-beans>
<session>
<ejb-name>HelloWorldBean</ejb-name>
<home>itso.examples.security.ejb.HelloWorldHome</home>
<remote>itso.examples.security.ejb.HelloWorld</remote>
<ejb-class>itso.examples.security.ejb.HelloWorldBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
</session>
</enterprise-beans>
<assembly-descriptor>
<security-role>
<description>Users allowed to access the ejb</description>
Chapter 5. Security
123
<role-name>powerusers</role-name>
</security-role>
<method-permission>
<role-name>powerusers</role-name>
<method>
<ejb-name>HelloWorldBean</ejb-name>
<method-intf>Remote</method-intf>
<method-name>hello</method-name>
</method>
</method-permission>
</assembly-descriptor>
</ejb-jar>
We import our EAR file into WebSphere Studio Application Developer from the
Server perspective.
As we browse through the different projects that WebSphere Studio Application
Developer has created for us, we note that there are three new files created
during the import process. They are:
򐂰 ibm-web-bnd.xmi and ibm-web-ext.xmi for the Web module
These two files are used to specify information such as what the error page is,
whether if we should serve servlets by class name or not, and some other
properties that are explained in greater detail in Chapter 8, “Java Servlets and
JavaServer Pages” on page 173.
򐂰 ibm-application-ext.xmi for the application
This file is internally used by WebSphere Application Server.
There will also be more files generated automatically by WebSphere Studio
Application Developer as soon as we provide deployment information using the
tools provided. These files include:
򐂰 ibm-application-bnd.xml
This file is where we specify the mappings to the authentication system users
and groups, and the mapping for the run-as bindings of the EJBs. With run-as
bindings we are able to specify on behalf of which user a given EJB runs,
provided that the EJB uses the feature run as role, within its deployment
desciptor.
124
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 ibm-ejb-jar-bnd.xmi.
We are responsible for the creation of this file. In order to do so, right-click the
META-INF folder located under the bin directory of SecureEJBProject and
create a new file with the name ibm-ejb-jar-bnd.xmi. Once this operation is
done, edit this file with the EJB extension editor and bind the HelloWorldBean
to the JNDI name ejb/HelloWorldHome in the Bindings tab.
Basically, defining security in J2EE applications means that we define security
constraints and map the authorized roles for those constraints to members or
groups of members defined in our security implementation (maybe an LDAP
directory or local operating system). We may also want to assign a role to all
authorized users or to all users.
In the case of Web modules, we define those constraints with a set of elements
defined by URL patterns and HTTP methods and by providing the roles which
are authorized to access to those elements. That information is stored in the
web.xml file and is standard for all J2EE-compliant application servers.
In the case of EJB modules, we define those constraints with a set of elements
defined by the method type (remote or home) and the method name. We secure
all methods by specifying the method type as undefined “*”.
The mappings of those authorized roles to the defined roles for our security
system are specified in the ibm-application-bnd.xmi file, which is not a standard
file.
The steps involved in the generation of these files are described below:
1. Once the EAR is imported, right-click the SecureSampleWebModule and
select Edit Module Dependencies to add the SecureEJBProject.jar.
2. Switch to the Java perspective to see if there are any Java errors or any
errors with the deployment descriptors.
3. We found that we were able to add an element named <display-name> under
the element <security-constraints> in the web.xml file. This does not comply
with the J2EE specs and particularly with web-app_2.2.dtd, which is the level
that we specified for our web.xml file, even though this is compliant with
web-app_2.3.dtd. So in order to successfully import the application we should
remove this element.
4. We need to enable the global security for our WebSphere Application Server,
Advanced Developer Edition that comes with WebSphere Studio Application
Developer for testing. To do this:
a. Double-click the WebSphere Administrative Domain in the Server
Configuration window.
Chapter 5. Security
125
b. Then, on the Security tab, click Enable security and specify the user and
password for the local operating system. See Figure 5-6 for an example.
The user specified should be an administrator and have the advanced
user right to act as part of the operating system. In Windows 2000 to add
this right to user use the local security settings window accessed by
choosing Start -> Programs -> Administrative Tools -> Local Security
Policy. Then choose Local Policies -> User right Assignment.
Figure 5-6 WebSphere Administrative Domain editor
5. If we want to have WebSphere Application Server, Advanced Edition running
on the same machine at the same time as the test server in WebSphere
Studio Application Developer, we must change the ports for the location
service daemon (LSD) and for ORB bootstrap used by the test server. To do
this, open the test server configuration and click the Ports tab. You can
change the port settings to use any other free ports. We used 902 for ORB
bootstrap and 9002 for LSD.
126
Migrating WebLogic Applications to WebSphere Advanced Edition V4
6. Next we have to map powerusers and normalusers to the groups we have
defined in our local OS. When we deploy to WebSphere Application Server,
Advanced Edition we will be able to change this to match those users and
groups of our names server.
7. In order to assign those mappings, double-click the ibm-application-ext.xmi
file, which is under the SecureSampleProject. This will open the application
extensions editor.
8. Select the Security Bindings tab and map the security roles to groups as
shown in Figure 5-5 on page 121.
Figure 5-7 Application extensions editor
9. Open the file ibm-application-bnd.xmi that is located under
<Product_Directory>\workspace\SecureSampleProject\META-IN in an editor
of your choice and manually add any accessId attributes and change
allauthenticatedusers to AllAuthenticatedUsers and eveyone to Everyone.
(Please note that when our redbook was written an e-fix was being prepared
Chapter 5. Security
127
to correct this problem, so it is possible that you will not see these errors in
your ibm-application-bnd.xmi.)
The application has now been secured. The next step is to generate the
deployment code for the EJB. To do this:
1. Right-click the SecureEJBProject and select Generate -> Deploy and rmic
code...
2. Select our enterprise bean and click Finish.
After the deploy code generation has completed we can test the application. To
do this:
1. Right-click Post.html and select Run on Server.
2. The WebSphere Application Server, Advanced Developer Edition will start
and a Web browser window will open on
http://localhost:8080/itso/Post.html.
5.5 AAT approach
WebSphere Studio Application Developer gives us all the resources we need to
perform a successful migration, since we are able to validate the code as well as
the deployment descriptors and we can debug the application in the WebSphere
Application Server, Advanced Developer Edition. An alternative to this approach
is to use the Application Assembly Tool (AAT) that is provided with WebSphere
Application Server, Advanced Edition.
The AAT utility allows us to edit, modify, and pack our J2EE application. It is
similar to the Web descriptor and EJB descriptor tools we access from the
administrator’s console of WebLogic, but it also allows us to create and edit
applications even though they are not yet deployed.
To successfully open our EAR file that includes only the standard deployment
descriptors, it is very important that application.xml, web.xml and ejb-jar.xml
conform with application_1_2.dtd, web-app_2_2.dtd and ejb-jar_1_1.dtd
respectively. BEA WebLogic Server V6.1 is compliant with the J2EE 1.2
specification so it has support for these levels, but in order to successfully import
the application into WebSphere Application Server we have to make sure that
only these levels are used in the application XML files.
We had to remove the <display-name> element under the element
<security-constraints> in the web.xml because this element does not conform to
the web-app 2.2 specs but web-app 2.3.
128
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Once we open the EAR file in the AAT, we need to change some elements in the
Web and EJB modules and for the application containing these:
򐂰 For the application, we need to edit the bindings related to the security roles
and add the users and groups that will be authenticated for those roles based
on our names directory. This can also be done at deployment time and we will
also be able to browse the names directory, since it has a search facility. Once
we add the Users/Group, as shown in Figure 5-8, click Apply.
Figure 5-8 Security roles for the application
򐂰 We also need to change the following attributes for the EJB module:
– We need to check the binding for the HelloWorldBean. Choose
SecureSampleProject -> EJB Modules -> SecureEJBProject.jar ->
Session Beans -> HelloWorldBean. Select the Bindings tab and bind
the EJB to the name ejb/HelloWorldHome. Click Apply to save the
changes.
Chapter 5. Security
129
– We also need to make sure that our remote method hello() has
powerusers as an authorized role. Choose EJB Modules ->
SecureEJBProject.jar -> Session Beans -> Method Permissions. Click
Security Constraints and for the remote method hello() ensure that
powerusers are allowed to execute it. This is shown in Figure 5-9.
Figure 5-9 Method permission for EJBs
Note that we had to add a JNDI name for the EJB but we did not modify the
security constraints. That is because Java 2 Platform, Enterprise Edition
specifies those attributes as common for all certified application servers. We do
not need to change anything for the Web module as far as security is concerned.
We could include an EJB reference for the SecureSampleModule.jar file, but this
is not needed because we are performing a global lookup in our code.
130
Migrating WebLogic Applications to WebSphere Advanced Edition V4
We have now specified all the user role information that is standard to the J2EE
security model. The specification leaves it up to the vendors to decide how to
implement mapping roles to the users registry and the supported registry types.
Chapter 5. Security
131
5.6 Deploying the secure EAR
This section covers aspects of deploying our application that are specific to
WebSphere Application Server, Advanced Edition.
Once we have created our application, we must deploy our EAR file. This
process will be the same regardless of whether we used WebSphere Studio
Application Developer or AAT to package the EAR.
To deploy the EAR:
1. Make sure that WebSphere Application Server, Advanced Edition is started.
2. Start the WebSphere Administrative Console.
3. Right click the Enterprise Applications folder and select Install Enterprise
Application.
4. Use the default value to browse for file or node, which should be our host
name.
5. Select Install Application (*.ear).
6. Click Browse to locate our EAR file.
7. When asked to deny access to all unprotected methods, select NO. This is
because we did not protect the Home method create() for our EJB. Therefore,
we would not be able to access the EJB if we denied access to unprotected
methods.
8. In the Mapping Users to Roles window, we see the same settings as specified
at the application level when we packed the application. We may leave them
as specified and click Next>.
9. In the Mapping EJB RunAs roles to users window, click Next>.
10.Leave Binding Enterprise Beans to JNDI Names as is. The values you will
see are:
– EJB: HelloWorldBean
– Module: SecureEJBProject.jar
– JNDI Name: ejb/HelloWorldHome
11.Click Next> until you see the Selecting Application Servers window.
12.Click Select Server... and choose ITSO Server (local _hostname) for both
modules.
13.Finally click Next> and then Finish.
14.When asked to generate or regenerate the necessary code for installation,
click Yes and in the next window click OK.
132
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Once we have deployed our application we have to regenerate the Web server
plug-in and set the module visibility to compatibility. To do this use the
WebSphere Administrative Console and:
1. Right-click the host name of our machine under the Nodes folder and choose
Regen Webserver plugin. We can monitor this operation in the message
window.
2. To change the module visibility, we have to click the ITSO Server and select
Compatibility in the Module visibility drop-down box.
3. The last operation will be start the server. Right click the ITSO Server and
click Start.
4. Now we can test our operation by opening a browser and pointing to
http://127.0.0.1/itso/
Chapter 5. Security
133
134
Migrating WebLogic Applications to WebSphere Advanced Edition V4
6
Chapter 6.
Transaction management
This chapter. discusses the J2EE specification mandates for transaction
management and considers how WebLogic and WebSphere implement the
specification.
© Copyright IBM Corp. 2002
135
6.1 Introduction
Transaction management is a long-standing requirement in applications, and
application developers have spent a great deal of time writing and rewriting
transaction systems and managing their transactions. The introduction of the
Java Transaction API to the Java 2 Platform, Enterprise Edition (J2EE) made it
easier for Java applications developers to manage transactions, by removing the
burden of managing transactions from individual programmers. J2EE supports
distributed transactions through two specifications, Java Transaction API (JTA)
and Java Transaction Service (JTS).
Sun defines JTA and JTS as follows:
”JTA is a high level, implementation-independent, protocol-independent API
that allows applications and application servers to access transactions. JTS
specifies the implementation of a Transaction Manager that supports JTA and
implements the Java mapping of the OMG Object Transaction Service (OTS)
1.1 specification at the level below the API. JTS propagates transactions
using the Internet Inter-ORB Protocol (IIOP).”
Figure 6-1 shows the communication between Java components and various
transaction managers:
Application Server
Transaction
Manager
Application Server
JTS
Servlet/
JSPs
IIOP
IIOP
Resource Manager
JTA
Java
Client
RMI/
IIOP
Transaction
Manager
JTA
IIOP
JTS
JTA
EJBs
Figure 6-1 Interaction between Java components and transaction managers
136
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Transaction
Manager
JTS
A transaction manager is responsible for maintaining the ACID properties of a
transaction. A resource manager provides access to resource and transaction
capabilities by implementing the transaction resource interface used by a
transaction manager to associate transactions and to complete transactions or to
perform recovery work. Examples of resource managers are Java Message
Service (JMS) providers, database management systems (DBMS) and EJB
containers. Stand-alone Java client programs control their transaction
boundaries by using a high-level interface provided by the application server or
the transaction manager. Alternatively, the application server can provide
transaction support through declarative attribute settings such as provided in
Enterprise JavaBeans (EJB) component architecture.
6.1.1 Non JTA transaction
Resource managers that have the capability of supporting transactions can be
used in a transactional fashion by Java components. Each resource manager
has its own way of implementing and supporting transactions and has to be
handled differently. For example, a JMS resource manager would provide a
handle to the transaction in the form of a session, whereas a JDBC resource
manager would do it through the connection. If the resource manager used is not
JTA-enabled, then it can support only a one-phase commit transaction, which is
also known as a local transaction.
An application can use one non JTA-enabled resource manager and a single
transaction of the resource manager at a time. If the resource manager is a
database, an application can obtain a connection more than once, as long as the
same user ID/password is used to obtain the connection. If the connection is
obtained more than once with the same user ID/password, essentially the
resource managers (DataSource) give the same instance of connection. The
connection will not be released to the resource manager until all the handles to
the connection are closed. For more information, refer to the white paper
“WebSphere Connection Pooling” available at:
http://ibm.com/software/webservers/appserv/whitepapers/connection_pool.pdf
Example 6-1 shows the sample use of transactional capabilities of the JDBC
connection.
Example 6-1 Non-JTA transaction
protected void transferFund(
int sourceAccount,
int destinationAccount,
float amount)
throws SQLException {
Connection conn = null;
Chapter 6. Transaction management
137
try {
conn = getDataSource().getConnection();
conn.setAutoCommit(false);
debit(sourceAccount, amount, conn);
credit(destinationAccount, amount, conn);
conn.commit();
conn.setAutoCommit(true);
} catch (SQLException e) {
if (conn != null)
conn.rollback();
throw e;
} finally {
try {
if (conn != null)
conn.close();
} catch (SQLException sqle) {
//usually can ignore
}
}
}
6.1.2 JTA transaction
Application servers supporting the J2EE specification are required to support
transactions. A JTA transaction is managed and coordinated by the application
server. A JTA transaction that spans multiple resource managers and enterprise
information systems is also known as a distributed transaction or a global
transaction. A distributed transaction use a two-phase commit protocol. The
two-phase commit protocol ensures that the transactional updates are committed
to all the resource managers, or all the resource managers are reverted to the
state when the transaction was started. Java components use the JTA interface
to use transaction capabilities provided by the application server. The application
server then co-ordinates with the individual resource managers involved in the
transaction to maintain the ACID properties of the transaction. Currently, the
J2EE platform supports only flat transactions. A flat transaction cannot have any
child (nested) transactions.
JTA allows applications to access transaction management in a manner that is
independent of a specific implementation. An application uses the JTA
UserTransaction interface to demarcate JTA transaction boundaries.
Example 6-2 shows the use of UserTransaction to handle a distributed
transaction.
138
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Example 6-2 JTA Transaction
protected void transferFund(
int sourceAccount,
int destinationAccount,
float amount)
throws Exception {
Connection conn = null;
getUserTransaction().begin();
try {
conn = getDataSource().getConnection();
debit(sourceAccount, amount, conn);
credit(destinationAccount, amount, conn);
} catch (SQLException e) {
getUserTransaction().setRollbackOnly();
throw e;
} finally {
try {
if (conn != null)
conn.close();
} catch (SQLException sqle) {
//usually can ignore
};
try {
getUserTransaction().commit();
} catch (RollbackException re) {
//Thrown to indicate that the transaction has been rolled back
//rather than committed.
System.out.println("User Transaction Rolled back! " +
re.getMessage());
}
}
}
A JTS transaction manager provides the services required to support transaction
demarcation, synchronization, and transaction context propagation. The
XAResource interface defines the contract between the resource manager and
the JTS transaction manager. The XAResource interface can be supported by
any transactional resource. Figure 6-2 shows the interaction of the transaction
manager, application server, and an XAResource supported by a database
management system.
Chapter 6. Transaction management
139
Client
Server Application
10. stmt.execute()
11. close()
0. Begin
lookup()
6. enlist(XARes)
13. delist(XARes)
12. connectionClosed()
3. addConnectionListener()
4. getXAResource()
8. getConnection()
2. getXAConnection()
XA Data
Source
XA
Connection
Global
Transaction
"XAconnection
pool"
Application Server
"execute" & "close"
connectionErrorOccurred()
Transaction
Manager
Data
Source
Create
1. getConnection()
Connection
9. Create handle
Transaction
Monitor
Create
5. Create handle
XA
Resource
7. start
14. end
15. prepare
16. commit
JDBC Driver
Database
© Power Assist, Inc. - used by permission
Figure 6-2 Interactions between application, server, transaction manager and XAResource provider
140
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 6-2 shows the typical interaction between the transaction manager,
application server, and resource manager. It is assumed that begin is called on
UserTransaction and is propagated to the transaction manager, which creates a
global transaction and associates it with the current thread. Then getConnection
is called on a DataSource, which causes XAResource to be instantiated and
enlisted with the transaction. The transaction in turn issues a start to
XAResource. Once this initial setup is finished, the application can perform
required operations using the connection and issue a close at the end. Closing
the connection delists the XAResource from the transaction and returns the
connection to the connection pool. The transaction monitor will perform the
two-phase distributed commit after all XAResource objects have been delisted
from the transaction.
To further understand the support for transactions in EJBs, see the redbook
Programming J2EE APIs with WebSphere Advanced, SG24-6124.
For more information about Java transactions, see the Java Transaction API
1.0.1 specification. Other useful links include:
򐂰 http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/Transaction.html
򐂰 http://java.sun.com/blueprints/guidelines/designing_enterprise_applica
tions/transaction_management/index.html
6.2 Migrating WebLogic extensions
Both WebLogic V6.1 and WebSphere V4.0 support the JTA 1.0.1 specification.
WebLogic has few proprietary extensions to JTA that require attention when
migrating to WebSphere. The description of these extensions is available in
WebLogic online documentation found at:
http://e-docs.bea.com/wls/docs61/jta/jtaapi.html
1. BEA WebLogic Server allows client programs and EJBs to access the
transaction manager by performing JNDI lookup. This allows clients and EJBs
to suspend and resume transactions. It is required that suspend and resume
should be performed in the same server process. Access to the transaction
manager allows XAResources to be enlisted and delisted with the transaction
manager at startup and shutdown.
The J2EE specification states that javax.transaction.TransactionManager is
an interface to allow application servers to manage transaction boundaries.
Hence, WebSphere V4.0 does not allow lookup for TransactionManager.
Enlistment of any resource with the TransactionManager is performed
exclusively by the ConnectionManager component of the WebSphere
Chapter 6. Transaction management
141
Application Server runtime, into which any third party JMS XA provider must
be plugged in as a resource adapter, per the Java Connector Architecture
(JCA). The WebSphere direction for its JMS XA support is to make this a
pluggable component into the ConnectionManager.
Any WebLogic application code that relies upon access to the transaction
manager to suspend and resume the transaction needs to be changed for a
successful migration. There is no easy common solution to migrate such
code, so any solution devised will have to be on a case-by-case basis
depending on the requirement of the application being migrated.
2. WebLogic has new classes: weblogic.transaction.RollbackException (extends
javax.transaction.RollbackException) and weblogic.transaction.XAException
(extends javax.transaction.xa.XAExeception). These classes preserve the
original exception for later use. Example 6-3 shows how these
WebLogic-specific classes might typically be used.
Example 6-3 WebLogic-specific code
try {
....
} catch (Exception e) {
throw new weblogic.transaction.RollbackException(e.getMessage(), e);
//or
throw new weblogic.transaction.XAException(e.getMessage(), e);
}
Reference to these classes could be replaced by corresponding JTA classes
and all the imports and references have to be updated. Recompiling the code
without weblogic.jar will uncover code impacted by this issue. Example 6-4
shows how this code might be re-written to comply with the J2EE standard.
Example 6-4 J2EE compatible code
try {
....
} catch (Exception e) {
e.printStackTrace();
throw new javax.transaction.RollbackException(e.getMessage());
//or
throw new javax.transaction.xa.XAException(e.getMessage());
}
Alternatively, you can extract weblogic.transaction.RollbackException and
weblogic.transaction.XAException from weblogic.jar and include them as a
part of extra libraries for your application. This way you do not have to do any
code changes to your application code. If you take this approach, you also
need to extract weblogic.utils.NestedThrowable.
142
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Another solution would be to create equivalent classes of your own, as shown
in Example 6-5.
Example 6-5 Custom class equivalent of WebLogic extension
public class RollbackException extends javax.transaction.RollbackException {
private Throwable nestedThrowable;
public RollbackException() {
super();
}
public RollbackException(String aMessage) {
super(aMessage);
}
public RollbackException(String aMessage, Throwable aThrowable) {
super(aMessage);
nestedThrowable = aThrowable;
}
public Throwable getNested() {
return nestedThrowable;
}
public void printStackTrace() {
printStackTrace(System.out);
}
public void printStackTrace(java.io.PrintStream s) {
super.printStackTrace(s);
s.println("-----------Original Exception----------");
getNested().printStackTrace(s);
}
}
3. The WebLogic JTA transaction manager object supports
weblogic.transaction.TransactionManager (which extends
javax.transaction.TransactionManager). This is done to allow XA resources to
register and unregister themselves with the transaction manager on startup
and shutdown.
This is not covered by J2EE specification and hence WebSphere does not
support this behavior. The recommended way to program in WebSphere is to
use the Java Connection Architecture, so this WebLogic code would need to
be modified as part of the migration effort.
4. The WebLogic JTA transaction object supports
weblogic.transaction.Transaction (which extends
Chapter 6. Transaction management
143
javax.transaction.Transaction). This allows an application to get and set
transaction properties. This interface includes methods such as get/setName,
get/setProperty, get/setRollbackReason, and so on.
As per the J2EE specification, transaction properties in WebSphere are not
accessible to Java applications. If these properties are needed to be passed
along with different EJB calls, it is recommended that you create a separate
class, such as TransactionContext, and pass an instance of this class to the
called EJBs as a method parameter.
5. WebLogic implements a helper class, weblogic.transaction.TxHelper, which
allows you to obtain the current transaction manager, transaction, and user
transaction. It also provides a status2String method to translate
javax.transaction.Status constants to strings.
Since, the transaction manager and transaction are not available to Java
applications, these methods are not required and references to these
methods should be removed. For making minimum changes to the code
referencing getUserTransaction and status2String methods, you can add your
own class TxHelper with these two methods.
6. WebLogic also declares an optional interface
weblogic.transaction.XAResource to allow XA resource providers to
communicate extra information to the transaction manager. This interface
currently has two methods: detectedUnavailable and getDelistFlag. The
detectedUnavailable method is for a health check on an XAResource. The
getDelistFlag is used by the transaction manager while calling
XAResource.end to allow resource providers to optimize the end. For
example, the XAResource.end called with TMSUSPEND is more expensive
than if it is called with TMSUCCESS, mainly because in the former case open
cursors are maintained.
WebSphere has no equivalent for these interfaces. Although it would be nice
to have these methods in a future J2EE spec, not having them now is not a
point of worry, because these methods would be ignored by WebSphere and
everything would still work fine.
144
Migrating WebLogic Applications to WebSphere Advanced Edition V4
6.3 The future
The latest version of JTA specification available is 1.0.1 and both WebLogic V6.1
and WebSphere V4.0, implement it. There are two approved Java Specification
Request (JSRs) related to the Java transactions.
JSR 95: J2EE Activity Service for Extended Transaction
This specification will support an activity to acquire and use resources for only
the required duration rather than the entire duration of a long-running
transactional activity. In the event of failures, obtaining reliable execution
semantics for the entire long-running transaction may require compensation
transactions that can perform forward or backward recovery.
For more details see:
http://jcp.org/jsr/detail/95.jsp
JSR 156: XML Transactioning API for Java (JAXTX)
This JSR requests the creation of the XML Transactioning APIs for Java 1.0
specification (JAXTX). This specification will describe Java APIs designed
specifically for the management (creation and lifetime) and exchange of
transaction information between participating parties in a loosely coupled
environment. Rather than communicating via IIOP, such parties will typically use
SOAP and XML document exchange to conduct business transactions. If these
transactions are to be conducted in an ACID transaction manner, then
information (for example the transaction context) will need to accompany these
XML documents and be managed appropriately.
For more details see:
http://jcp.org/jsr/detail/156.jsp
Currently the JTA specification supports only flat transactions and no support is
available for child (nested) transactions. We have to wait and see when this is
supported by J2EE specifications.
Chapter 6. Transaction management
145
146
Migrating WebLogic Applications to WebSphere Advanced Edition V4
7
Chapter 7.
Naming
This chapter outlines both the standard and the vendor-specific uses of JNDI in
the J2EE specifications. These include the JNDI environment naming context
and associated deployment descriptors. Common JNDI migration issues are
identified and presented along with recommended solutions. Future uses of JNDI
are also summarized.
© Copyright IBM Corp. 2002
147
7.1 J2EE JNDI naming context
JNDI provides a way to bind and look up a component’s dependencies at
runtime. The J2EE standard defines a special JNDI naming context that extends
these basic JNDI features in two important ways:
1. Indirect lookup
The name that is used in Java code for a JNDI lookup is actually an alias. This
allows the name of the target object to be redefined without source code
changes.
2. Deploy-time binding of target objects
The target object of a JNDI lookup is defined by a deployment descriptor. This
means that dependent EJBs and services can be specified at deploy time,
independently of the Java code.
The purpose of the J2EE JNDI naming requirement is to support and promote
portable and reusable components. Java code can to be written without knowing
the names of dependent EJBs and services. Moreover, the same component can
be deployed using different dependencies without modifying the Java code.
The J2EE specification requires that compliant servers provide components with
a read-only JNDI naming context. This context is used by EJB, Web, and client
components for runtime lookup of scalar environment variables, and EJB and
other factory objects.
򐂰 JNDI environment variables
Environment variables are classic customization parameters. They can be
any of the Java scalar types: String, Byte, Short, Integer, Long, Boolean,
Double, or Float.
򐂰 JNDI factory objects, including DataSources and EJB homes
We distinguish between two different kinds of factory objects:
a. Service factories, such as DataSources
DataSource objects are the most common service factories. A
DataSource is a factory for database connection objects.
b. EJB homes
An EJB home is a Java interface for a factory object. That factory object
generates instances of EJBs that implement the corresponding remote
interface. In principle, the same home and remote interface pairs can be
implemented by any number of different EJBs. In the J2EE 1.2
specification, every EJB home object must be retrieved by a JNDI lookup.
This is true even when one EJB instance refers to another EJB.
148
Migrating WebLogic Applications to WebSphere Advanced Edition V4
7.1.1 Java code for JNDI lookups
The following are examples of the Java code required to look up three different
kinds of objects in the J2EE naming context:
򐂰 Example 7-1 shows a typical Java coding sequence for retrieving the value of
an environment variable.
Example 7-1 Lookup environment variable
import javax.naming.InitialContext;
InitialContext lc = new InitialContext("java:comp/env”);
Object obj = lc.lookup(“TradeTitleMessage");
String title = (String)obj;
򐂰 Example 7-2 shows a typical Java code sequence for retrieving the value of a
DataSource to create a database connection.
Example 7-2 Lookup DataSource
import javax.naming.InitialContext;
import javax.sql.DataSource;
InitialContext lc = new InitialContext("java:comp/env”);
Object obj = lc.lookup("jdbc/TradeDataSource");
DataSource datasource = (DataSource)obj;
Connection conn = datasource.getConnection();
򐂰 Example 7-3 shows a typical Java code sequence for locating the home of
any EJB and creating remote instances of the EJB.
Alternatively, the resulting EJB home can be used with a finder method to
gain access to existing EJB instances.
Example 7-3 Lookup EJB
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
InitialContext lc = new InitialContext("java:comp/env”);
Object obj = lc.lookup("ejb/TradeAccountBean");
AccountHome accountHome =
(AccountHome) PortableRemoteObject.narrow(obj, AccountHome.class);
Account act = accountHome.create();
As depicted by the above examples, all lookups in the J2EE naming context have
the following common features:
1. InitialContext
Use a JNDI InitialContext object to locate the J2EE naming context provided
by the container.
Chapter 7. Naming
149
2. Context name java:comp/env
The J2EE naming context is named java:comp/env
– Syntax
Other than being unlikely to conflict with other JNDI context names, there
is no special meaning to the syntax of the name java:comp/env — think of
it as a mnemonic for Java component environment.
– Scope
The scope of this naming context is the J2EE component — that is, an
EJB or a Web component.
All instances of the same EJB have the same naming context. Each EJB
component has its own naming context, even if it is in a module with
multiple EJB components. This means that the same name can be used in
different EJBs and be bound to different values without conflict. The J2EE
naming context is also called:
•
•
Environment naming context (ENC)
Local naming context
We will use the term ENC for the time being.
– Subcontext
The following subcontext names are recommended by the J2EE standard,
but not mandated:
•
•
•
•
•
java:comp/env/ejb for EJB references
java:comp/env/jdbc for DataSource references
java:comp/env/jms for JMS connection factories
java:comp/env/mail for JavaMail connection factories
java:comp/env/url for URL connection factories
3. Casting
The object returned by the InitialContext lookup must be cast as follows:
– To the Java type of the scalar environment variable.
– Directly to the resource type for resources that do not use CORBA IIOP for
remote access — for example, DataSource.
– By way of the PortableRemoteObject.narrow method for all objects that
may use CORBA IIOP for remote access.
Even though your application may not be using CORBA IIOP at this time,
for example if it uses Java RMI, it is highly recommended that you convert
to the PortableRemoteObject.narrow protocol. Without this style of
casting, future upgrades and migrations will cause failures.
4. You can use the full ENC name in the lookup method.
150
Migrating WebLogic Applications to WebSphere Advanced Edition V4
As an alternative, the java:comp/env ENC name can be moved to the lookup
method calls, for example:
InitialContext lc = new InitialContext();
Object obj = lc.lookup("java:comp/env/jdbc/TradeDataSource");
It is common practice to localize all ENC names in one Java class to make it
easier to find and modify them. However, without also understanding the
overall program structure, it can still be difficult to find exactly where these
names are used.
In effect, the actual ENC names are determined by the Java code. They are
whatever the Java code uses in its JNDI lookup method calls. If the string
java:comp/env/account/limit is used as the argument to a JNDI lookup method,
then the name account/limit better be defined in the ENC. This is done by
defining a deployment descriptor of the appropriate type for inclusion in a
standard deployment descriptor file.
7.1.2 Standard deployment descriptors
The J2EE standard requires that EJB and Web components have the following
deployment descriptors in their respective JAR and WAR files:
򐂰 A META-INF/ejb-jar.xml file for each EJB JAR
򐂰 A WEB-INF/web.xml file for each Web component
Each java:comp/env ENC name that is used as a reference within a component
must be declared by the application assembler in the appropriate deployment
descriptor. The actual deployment element depends on the type of the JNDI
reference:
򐂰 An <env-entry> element is used for references to scaler environment
variables.
Example 7-4 is the <env-entry> deployment descriptor corresponding to the
environment variable lookup in Example 7-1 on page 149.
Example 7-4 Standard deployment descriptor for environment variable
<env-entry>
<env-entry-name>TradeTitleMessage</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>Trade J2EE Client Sample</env-entry-value>
</env-entry>
򐂰 A <resource-ref> element is used for references to resources other than
EJBs, such as DataSources.
Example 7-5 is the <resource-ref> deployment descriptor corresponding to
the DataSource lookup in Example 7-2 on page 149.
Chapter 7. Naming
151
Example 7-5 Standard deployment descriptor for DataSource reference
<resource-ref>
<res-ref-name>jdbc/TradeDataSource</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
򐂰 An <ejb-ref> element is used for references to EJBs.
Example 7-6 is the <ejb-ref> deployment descriptor corresponding to the EJB
lookup in Example 7-3 on page 149.
Example 7-6 Standard deployment descriptor for EJB reference
<ejb-ref>
<ejb-ref-name>ejb/TradeAccountBean</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>trade.AccountHome</home>
<remote>trade.Account</remote>
</ejb-ref>
The above deployment descriptors have the following similarities and differences:
1. The ENC names used in the deployment descriptors do not include the
java:comp/env initial naming context.
The ENC context is assumed in the deployment descriptor reference
elements. For example, the Java code in Example 7-2 on page 149 uses
java:comp/env/jdbc/TradeDataSource, while the corresponding deployment
descriptor reference element just uses jdbc/TradeDataSource.
2. The formats of these deployment descriptors are included as part of their
respective DTD definitions.
The Java Servlets 2.2 specification contains the specification of its DTD,
available at http://java.sun.com/j2ee/dtds/web-app_2_2.dtd. The
Enterprise JavaBean 1.1 specification contains the specification of its DTD
available at http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd. Both of these
DTDs contain the same <env-entry>, <resource-ref>, and <ejb-ref> elements.
3. The <env-entry> element provides all of the deployment information needed
for an environment variable.
It includes a mapping from the ENC name to its type, in addition to an optional
initial value.
4. The <resource-ref> element declares the DataSource type, but not its value.
It provides the name-to-type mapping, but does not provide a bound value. In
Example 7-5 on page 152, it is clear that the actual DataSource is missing.
152
Migrating WebLogic Applications to WebSphere Advanced Edition V4
5. The <ejb-ref> element declares its type, or is it the actual object?
In Example 7-6 on page 152, it is not so clear that the <home> and <remote>
elements are just type specifications. They could as well be used to bind to
the actual EJB object. In fact, both alternatives are possible.
– <home> and <remote> define the type of reference.
– <home> and <remote> provide the actual value of the reference.
In Example 7-6 on page 152, it is just the type, leaving the actual target EJB
unbound. We revisit this topic in 7.4.5, “The ejb-link alternative” on page 170.
The J2EE specifications allow vendors to define the mechanism for binding
target resource factory and EJB objects to references. Therefore, this information
does not appear in the standard deployment descriptors.
By way of a summary, the standard deployment descriptors do not include the
following bits of information:
1. Actual deployed JNDI names for EJB references and resource references
EJB and resource references do have ENC names, and these names are in
both the Java code (lookup methods) and in the standard deployment
descriptors (<resource-ref> and <ejb-ref> elements). The deployed JNDI
name for a reference is found only in vendor-supplied deployment descriptors.
2. Actual deployed JNDI names of EJBs
Unlike references, EJBs do not have ENC names. An EJB only has one JNDI
name — its deployed JNDI name — and it is not in the standard deployment
descriptor. The mechanism for cataloging and referencing EJBs is also left to
the vendors.
7.2 Local and global JNDI names
It is up to the vendor to determine how to deploy resource and EJB references.
The J2EE specifications suggest using JNDI itself for this purpose. In particular,
the JNDI LinkRef mechanism is suggested, and most vendors have adopted it. A
JNDI LinkRef is a kind of symbolic link where the first JNDI name becomes an
alias for the second JNDI name. When the first name is looked up, the object
bound to the second name is returned. So instead of just one JNDI name, there
are actually two JNDI names for each resource or EJB reference! The ENC name
is local to the EJB or Web component, while the second JNDI name is typically
global to a system-wide JNDI server, possibly including clusters of machines.
Vendors include a variety of features in their JNDI servers, and this is one reason
that this area of deployment is left to the vendors.
Chapter 7. Naming
153
Because they are more descriptive, we use the following terms in the remainder
of the chapter:
򐂰 Local JNDI name
A local JNDI name is the environment naming context name as defined in the
J2EE specification.
򐂰 Global JNDI name
A global JNDI name is the aliased JNDI name defined in a vendor-specific
deployment tool, and actually bound to the resource factory object in the
system JNDI server.
In WebLogic and WebSphere, the following information must be provided in
vendor-specific deployment descriptors:
1. Global JNDI names for EJBs
EJBs do not have local JNDI names. Global names must be assigned to EJBs
so they can be used to resolve EJB references. These global names make
EJBs visible externally.
2. Global JNDI names for resource references
The local JNDI name of a resource reference becomes an alias for its global
JNDI name. This global name is typically defined in a server for the desired
service. In the case of a reference to a DataSource, this is the DataSource of
the actual database.
3. Global JNDI names for EJB references
The local JNDI name of an EJB reference becomes an alias for its global
JNDI name. The global name is the name of the target EJB object in the
system JNDI server.
In effect, the JNDI names — local and global — provide a second level of
indirection for resource and EJB references. This is useful for:
1. Aliasing
Different local JNDI names can be aliases for the same resource. For
example, the Pet Store example in 12.2, “Pet Store example” on page 267
uses three different local DataSource names to refer to the same globally
named DataSource object.
2. Organizing global JNDI namespace
The organization of the global JNDI namespace is not constrained by the
organization of an application’s local namespaces. For example, the global
JNDI namespace may be organized by departments responsible for services
and software maintenance, while an application’s local namespaces typically
154
Migrating WebLogic Applications to WebSphere Advanced Edition V4
reflect the application’s structure. Moreover, the local JNDI names used in
vendor-supplied applications have no effect on the global JNDI namespace.
Figure 7-1 on page 156 depicts the relationship between J2EE artifacts, and the
local and global JNDI names.
򐂰 Java code
Local JNDI names are established by Java code. These are the names used
in the JNDI lookup method calls.
򐂰 Standard deployment descriptors
Local JNDI names must be declared in the standard deployment descriptors.
They are defined in the <res-ref-name> and <ejb-ref-name> elements. These
names are usually identified as resource or EJB references in deployment
tools. For example, these are the names in the EJB Reference column in the
WebSphere Studio Application Developer Web.xml editor in Figure 7-1 on
page 156.
򐂰 Extended deployment descriptors
EJB and resource references are aliased to global JNDI names in
vendor-specific extended deployment descriptors. In Figure 7-1, these are the
names in the JNDI Name column.
Chapter 7. Naming
155
Application Source
Servlet
ic.lookup(
"java:comp/env/ejb/TradeAccountBean")
EJB
ic.lookup(
"java:comp/env/ejb/TradeAccountBean")
Standard Deployment
Descriptors
web.xml
<ejb-ref-name>
ejb/TradeAccountBean
</ejb-ref-name>
Extended Deployment
Descriptors
ibm-web-bnd.xmi
ejb-jar.xml
<ejb-name>
ejb/TradeAccountBean
</ejb-name>
Environment
Naming
Context
JNDI
name
<ejbRefBindings
jndiName=
"trade/AccountHome">
ibm-ejb-jar-bnd.xmi
Deployed
JNDI
name
<ejbRefBindings
jndiName=
"trade/AccountHome">
Figure 7-1 Two JNDI names — local environment context and global deployed context
7.3 Extended deployment descriptors
The J2EE specification does not allow the format or content of standard
deployment descriptors to be modified by vendors. Therefore, each vendor
provides its own files for extended deployment descriptors. Indeed, each vendor
provides a collection of files for different kinds of vendor-specific deployment
descriptors. These include extended descriptors for JNDI bindings, CMP beans,
and database schema information. We are only interested in JNDI bindings in
this chapter. For these purposes:
򐂰 WebLogic provides:
– A META-INF/weblogic-ejb-jar.xml file for each EJB JAR
– A WEB-INF/weblogic.xml file for each Web component
򐂰 WebSphere provides:
– A META-INF/ibm-ejb-jar-bnd.xmi file for each EJB JAR
– A WEB-INF/ibm-web-bnd.xmi file for each Web component
156
Migrating WebLogic Applications to WebSphere Advanced Edition V4
In the next two sections, we show how each vendor has implemented their
extended deployment descriptors for the example presented in 7.1.2, “Standard
deployment descriptors” on page 151. In addition to the different file names,
there are two major implementation differences:
1. XML vs. XMI
WebLogic uses an XML-based extension, while WebSphere uses an XMI
extension based on XML Metadata Interchange (XMI).
2. WebSphere uses optional IDs in standard descriptors
WebLogic extended deployment descriptors refer to the corresponding
standard deployment descriptors by means of the names found in
<ejb-name> and <ejb-ref-name>. In contrast, WebSphere extended
descriptors refer to standard descriptors by means of optional IDs in the
standard descriptors. This approach requires that the WebSphere ejb-jar.xml
and web.xml files have these optional identifiers.
7.3.1 WebLogic extended descriptors
Continuing with the example above, WebLogic provides the following information
in its extended deployment descriptors:
򐂰 A <weblogic-enterprise-bean> element contains the global JNDI name for the
EJB with the corresponding <ejb-name> element.
The WebLogic-specific definition in Example 7-7 establishes AccountHome
as the global JNDI name for our example.
Example 7-7 Binding an EJB’s global JNDI name in WebLogic
<weblogic-enterprise-bean>
<ejb-name>TradeAccountBean</ejb-name>
<jndi-name>AccountHome</jndi-name>
</weblogic-enterprise-bean>
򐂰 A <resource-description> element defines the mapping between a resource
reference and its global JNDI name.
Example 7-8 maps the DataSource reference with the local JNDI name of
jdbc/TradeDataSource, to the global JNDI name of jdbc/TradeSample. This
WebLogic deployment descriptor extends to the standard deployment
descriptor shown in Example 7-5 on page 152.
Example 7-8 Global JNDI name for DataSource reference in WebLogic
<resource-description>
<res-ref-name>jdbc/TradeDataSource</res-ref-name>
<jndi-name>jdbc/TradeSample</jndi-name>
Chapter 7. Naming
157
</resource-description>
򐂰 An <ejb-reference-description> element defines the mapping between an
EJB reference and its global JNDI name.
Example 7-9 maps the EJB reference with the local JNDI name of
ejb/TradeAccountBean to the global JNDI name of AccountHome. This
WebLogic deployment descriptor extends the standard deployment descriptor
shown in Example 7-6 on page 152.
Example 7-9 Global JNDI name for EJB reference in WebLogic
<ejb-reference-description>
<ejb-ref-name>ejb/TradeAccountBean</ejb-ref-name>
<jndi-name>AccountHome</jndi-name>
</ejb-reference-description>
7.3.2 WebSphere extended descriptors
As described above, the standard deployment descriptors used with WebSphere
require the use of optional IDs. Each element in a standard deployment
descriptor that may be extended, must have an ID so it can be referenced from
the extended deployment descriptor. These IDs are added automatically when
an EAR file is imported into the WebSphere Studio Application Developer or AAT
tool. Example 7-10 shows the standard EJB descriptor with an ID. Example 7-11
and Example 7-12 correspond respectively to Example 7-5 and Example 7-6
with the optional IDs added.
Example 7-10 Standard EJB definition with optional ID
<entity id="ContainerManagedEntity_3">
<ejb-name>TradeAccountBean</ejb-name>
<home>trade.AccountHome</home>
<remote>trade.Account</remote>
<ejb-class>trade.AccountBean</ejb-class>
</entity>
Example 7-11 Standard DataSource reference with optional ID
<resource-ref id="ResourceRef_1">
<res-ref-name>jdbc/TradeDataSource</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>CONTAINER</res-auth>
</resource-ref>
Example 7-12 Standard EJB reference with optional ID
<ejb-ref id="EjbRef_3">
158
Migrating WebLogic Applications to WebSphere Advanced Edition V4
<ejb-ref-name>ejb/TradeAccountBean</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>trade.AccountHome</home>
<remote>trade.Account</remote>
</ejb-ref>
Continuing with the same example, WebSphere provides the same information in
its extended deployment descriptors as does WebLogic.
򐂰 An <ejbBindings> element contains the global JNDI name for the EJB with
the corresponding ID in the META-INF/ejb-jar.xml file.
The WebSphere-specific definition in Example 7-13 establishes
trade/AccountHome as the global JNDI name for the TradeAccountBean. This
bean is located in the ejb-jar.xml file by the optional ID
ContainerManagedEntity_3 as seen in Example 7-10 on page 158.
Example 7-13 Binding an EJB’s global JNDI name in WebSphere
<ejbBindings xmi:id="ContainerManagedEntity_3_Bnd"
jndiName="trade/AccountHome">
<enterpriseBean xmi:type="ejb:ContainerManagedEntity"
href="META-INF/ejb-jar.xml#ContainerManagedEntity_3"/>
</ejbBindings>
򐂰 A <resRefBindngs> element defines the mapping between a resource
reference and its global JNDI name.
Example 7-14 maps the DataSource reference with the local JNDI name of
jdbc/TradeDataSource to the global JNDI name of jdbc/TradeSample. This
WebSphere deployment descriptor extends to the standard deployment
descriptor shown in Example 7-11 on page 158, locating the appropriate
<resource-ref> element by means of the optional ID ResourceRef_1.
Example 7-14 Global JNDI name for DataSource reference in WebSphere
<resRefBindings xmi:id="ResourceRefBinding_1" jndiName="jdbc/TradeSample">
<bindingResourceRef href="WEB-INF/web.xml#ResourceRef_1"/>
</resRefBindings>
򐂰 An <ejbRefBindings> element defines the mapping between an EJB
reference and its global JNDI name.
Example 7-15 maps the EJB reference with the local JNDI name of
ejb/TradeAccountBean to the global JNDI name of trade/AccountHome. This
WebSphere deployment descriptor extends the standard deployment
descriptor shown in Example 7-12 on page 158, locating the appropriate
<ejb-ref> element by means of the optional ID EjbRef_3.
Chapter 7. Naming
159
Example 7-15 Global JNDI name for EJB reference in WebSphere
<ejbRefBindings xmi:id="EjbRefBinding_1" jndiName="trade/AccountHome">
<bindingEjbRef href="WEB-INF/web.xml#EjbRef_3"/>
</ejbRefBindings>
7.4 JNDI migration issues
In the process of migrating the various examples in this book, we experienced a
number of problems that have to do with JNDI naming issues. In this section we
discuss the following JNDI migration issues along with our recommended
solutions:
򐂰
򐂰
򐂰
򐂰
򐂰
JNDI name overloading
Making EJB and resource references portable
Conversion of WebLogic deployment descriptors
Conversion of WebLogic RMI
The ejb-link alternative
7.4.1 Name overloading
A lot of different names are used to define, deploy, and reference EJBs. These
include:
򐂰 The Java class names for home, remote, and implementation
򐂰 The names in the <ejb-name> and <display-name> elements in the standard
deployment descriptors
򐂰 Local and global JNDI names, with the local names appearing in both the
Java code and in <ejb-ref-name> elements
򐂰 Project and module names in WebSphere Studio Application Developer
A DataSource reference also has a local and a global JNDI name and a display
name, in addition to the database name.
If you do not fully understand the differences between these names, there is a
tendency to use the same or very similar name for several different purposes.
For example, you could choose to use the same name for the Java remote class,
the <ejb-name>, and the local and global JNDI names. This is generally a bad
idea. If you use the same name for multiple purposes, you are guaranteed to
become confused sooner or later. Even if you manage to keep it all straight,
someone looking at the code in the future will certainly be confused. More than
likely, that will be during a migration project when:
1. You may not be as familiar with all of the pieces in an application
160
Migrating WebLogic Applications to WebSphere Advanced Edition V4
2. You are using new tools and deploying to a new target server
We experienced this kind of confusion when migrating and deploying some of the
examples in this book.
To avoid this kind of problem, our recommendation is to establish and stick to a
naming convention that makes the intended use of each name obvious. Since
existing applications already use different naming conventions, you will have to
adapt your convention to each application. A migration project is a good time to
establish and implement an improved naming convention.
Here are some specific suggestions:
򐂰 For <ejb-name>, precede the remote interface name with The, for example,
TheAccount.
򐂰 For display names, use a descriptive phrase with one or more embedded
blanks, for example, Trade2 Account Bean.
򐂰 Use the recommended subcontext convention of java:comp/env/ejb for the
local JNDI names of EJB references.
򐂰 Make sure your global JNDI names are clearly different from your local JNDI
names. Some examples for global names are:
– home/account
– deployed/account
– projectname/account
Do not use ejb/tradeaccountbean, for example, because it is too close to the
local JNDI name of ejb/TradeAccountBean.
򐂰 The same rule applies to DataSource references. Avoid jdbc/database as the
global JNDI name.
򐂰 Append App to application project names.
򐂰 Append Ejb to EJB project names.
򐂰 Append Web to Web project names.
7.4.2 Portable EJB and resource references
This section is a synopsis of several migration problems that were observed
during the writing of this book. 12.4, “Banking example” on page 302 is a case in
point. For simplicity, we present this synopsis using WebLogic descriptors.
WebSphere Studio Application Developer tools that were used in the actual
examples. The underlying issue in each case is a variation on the issues raised
in 7.4.1, “Name overloading” on page 160.
Chapter 7. Naming
161
We start with an application that is non-J2EE compliant because it does not use
the local JNDI name for an EJB lookup. The Java code and the relevant
deployment descriptor are shown in Example 7-16 and Example 7-17.
1. The lookup is done with the JNDI name “ejb/AccountHome”, which does not
follow the J2EE specification.
2. The referenced EJB has been deployed with the same JNDI name
“ejb/AccountHome”. The names match, so the application works.
Example 7-16 Original non-J2EE JNDI lookup
InitialContext ctx= new InitialContext();
Object home = (AccountHome) ctx.lookup("ejb/AccountHome");
Example 7-17 Original deployed JNDI name (WebLogic descriptor)
<weblogic-enterprise-bean>
<ejb-name>TheAccount</ejb-name>
<jndi-name>ejb/AccountHome</jndi-name>
</weblogic-enterprise-bean>
As part of the migration project, we also had the goal of upgrading the code to
the J2EE 1.2 standard. This was accomplished by:
1. Upgrading the JNDI lookup to use java:comp/env/ejb/AccountHome, as
shown in Example 7-18.
2. Add a standard EJB reference deployment descriptor to the application, as
shown in Example 7-19.
3. Map the local JNDI name ejb/AccountHome to the global JNDI name
ejb/AccountHome, as shown in Example 7-20.
Example 7-18 Corrected J2EE JNDI lookup
InitialContext ctx= new InitialContext();
Object home = (AccountHome) ctx.lookup("java:comp/env/ejb/AccountHome");
Example 7-19 EJB reference for corrected JNDI lookup
<ejb-ref>
<ejb-ref-name>ejb/AccountHome</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>example.AccountHome</home>
<remote>example.Account</remote>
</ejb-ref>
162
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Example 7-20 Deployed JNDI name of EJB reference (WebLogic descriptor)
<ejb-reference-description>
<ejb-ref-name>ejb/AccountHome</ejb-ref-name>
<jndi-name>ejb/AccountHome</jndi-name>
</ejb-reference-description>
The resulting modified application works correctly, just like the original. As a test,
we just changed the Java code back to its original form, as shown in
Example 7-16, expecting the application to fail. But it worked too! So what
actually changed? Or did anything change at all? Did we do something wrong in
the conversion? These are the kinds of questions you ask yourself when a
program does not behave as expected after you have made modifications.
Of course, the explanation is that both forms of the application work, but they just
work a little differently. The original lookup of ejb/AccountHome goes directly to
the deployed JNDI ejb/AccountHome, while the java:comp/env/ejb/AccountHome
lookup gets mapped through the local JNDI context to the a global JNDI name,
and it just happens to be the same ejb/AccountHome name. The problem is that
name overloading obscured our testing procedure.
Portability testing policy
Consider the case where you made the above changes, except for the one in
Example 7-18 on page 162. Or maybe there were several lookup calls and you
failed to upgrade one of them. When you test the program there is no indication
of the error of omission. The application appears to work correctly, but the newly
added deployment code is completely ineffective. Changing the <jndi-name> in
Example 7-20 on page 163 would have absolutely no effect. But it will
undoubtedly cause future deployment and migration problems.
It is important to have a convincing test for your J2EE conversions, one that will
catch the error of omission described here.
We recommend the following simple testing policy: whenever you upgrade Java
to use the J2EE local JNDI context, redeploy with a new testing name to make
sure the new changes are effective.
With this policy, there is no confusion about expected behavior of the modified
application. If you fail to change the JNDI lookup, the JNDI lookup will fail with a
Java exception. The JNDI Explorer tool is a handy tool for debugging this kind or
error. Figure 7-2 on page 164 shows the output of this tool for the banking
example. In this case, the EJB was deployed with the new JNDI name of
AccountBean.AccountHome.TestVersion. This helps us to quickly spot our error
of omission. It is obvious that the JNDI Explorer name is different from the one
reported in the Java exception.
Chapter 7. Naming
163
The same sort of conversion problem can just as easily occur when converting
DataSources lookups to use the java:comp/env/jdbc local JNDI context.
Figure 7-2 Use JNDI Explorer to verify global JNDI names
7.4.3 Conversion of WebLogic deployment descriptors
Migrating from WebLogic 6.1 to WebSphere 4.0 requires that an application’s
global JNDI name bindings be:
1. Reentered manually, using one of the WebSphere tools for editing extended
deployment descriptors, or
2. You find a way to automate the conversion of WebLogic-specific deployment
descriptors into WebSphere-specific deployment descriptors
Based on our experience, the first option is laborious and error-prone. Moreover,
the errors introduced by incorrect JNDI names can be difficult to find. They do not
show up until you test the application, and the resulting Java exceptions often do
not pinpoint that JNDI names are the source of the error. This makes the second
option above even more desirable.
The was40utils conversion tool
We experimented with a tool, called was40utils, that converts global JNDI name
bindings from WebLogic to WebSphere. It also converts Sun Microsystems’ JNDI
name bindings, but we did not test this feature. This tool is freely available from
http://www.ejbinfo.com/FTP/was40utils.zip. The tool is written in Java and
the download includes source code. Its primary limitation is that it does not
address the conversion of CMP beans. It only converts global JNDI names.
164
Migrating WebLogic Applications to WebSphere Advanced Edition V4
For our purposes, there are three commands of interest:
1. The cvtid command adds the optional IDs to web.xml and ejb-jar.xml files.
As described in 7.3.2, “WebSphere extended descriptors” on page 158,
WebSphere deployment descriptors make use of the optional ID attributes to
coordinate extended deployment descriptors with the standard deployment
descriptors. This command adds the optional IDs to ejb-jar.xml and web.xml
files. It takes two arguments:
– Input ejb-jar.xml or web.xml file
– Output ejb-jar.xml or web.xml file with IDs added
2. The cvtwl command converts weblogic-ejb-jar.xml files to ibm-ejb-jar-bnd.xmi
files.
This command takes three arguments:
– Input ejb-jar.xml file with IDs
– Input original weblogic-ejb-jar.xml file
– Output converted ibm-ejb-jar-bnd.xmi file
3. The cvtwebwl command converts weblogic.xml files to ibm-web-bnd.xmi files.
This command takes three arguments:
– Input web.xml file with IDs
– Input original weblogic.xml file
– Output converted ibm-web-bnd.xmi file
The program attempts to read DTDs over the network. You can disable this by
commenting out DOCTYPE statements, but remember to restore them before
using the resulting files.
We used this tool to convert the WebLogic descriptors for the Pet Store example
(see “Automated conversion of WebLogic descriptors” on page 285), and for the
Trade2 example (see “Converting WebLogic deployment descriptors” on
page 294). The Trade2 example worked perfectly. We had some problems with
the Pet Store example, but believe that this was due to errors in the Pet Store
weblogic-ejb-jar.xml file supplied by WebLogic. Some of the <ejb-ref-name>
elements have the wrong names.
7.4.4 Conversion of WebLogic RMI
Prior to the inclusion of JNDI in the J2EE specifications, Java Remote Method
Invocation (RMI) was used to:
1. Register remote objects for distributed access
2. Look up and create handles to these remote objects
Chapter 7. Naming
165
3. Handle remote method calls, including serialization, and parameter
marshalling and unmarshalling
WebLogic provides a proprietary drop-in replacement for the standard RMI with
improved performance. From a programming perspective, the only differences
are the names of included packages, for example weblogic.rmi instead of
java.rmi.
JNDI provides an API for any naming service, including RMI. WebLogic V6.1
integrates JNDI with WebLogic RMI. JNDI is the preferred naming interface for
WebLogic V6.1, but existing WebLogic applications have not been fully
converted. Indeed, the sample banking application from WebLogic uses
WebLogic RMI instead of JNDI and J2EE deployment descriptors. Even though
this is a small example, it demonstrates two styles of registering distributed
objects. You can see the two objects displayed in the JNDI Explorer in Figure 7-2
on page 164.
1. The Account object is registered by using a deployment descriptor
2. The RMILogger object is registered dynamically at runtime by using RMI
In particular, the following deprecated interfaces and services are used by the
banking example:
1. Hard-coded global JNDI names for EJB references
2. Direct lookup of EJBs through RMI, instead of using portable EJB references
3. RMI lookup of a dynamically bound remote application object caller
RMILogger
4. RMIRegistry to make RMILogger available for remote method calls
The first of these issues is addressed in 7.4.2, “Portable EJB and resource
references” on page 161. The remaining RMI-specific issues are addressed in
this section.
Migration recommendations
Although the banking example in 12.4, “Banking example” on page 302 is used
as a reference for our recommendations, we expect that these same problems
will be found in larger, real-world applications. We recommend the following
general migration strategy:
1. Attempt to convert dynamic RMI registrations and lookups to use J2EE
deployment and local JNDI names for EJB and resource references.
2. If an object must be bound dynamically at runtime, migrate to the use of JNDI
and PortableRemoteObject for both object registration and lookup.
166
Migrating WebLogic Applications to WebSphere Advanced Edition V4
3. Avoid the use of server-specific parameters when establishing an initial
naming context.
It may be necessary to retain initial context parameters for client code that is
run outside of a standard J2EE container. If you must use it,
com.ibm.websphere.naming.WsnInitialContextFactory is the name of the
WebSphere initial context factory.
4. Improve portability by using local environment variables for naming context
parameters that are absolutely necessary, for example, JNDI names for
dynamic registration, URLs, and initial context factories.
In the examples in the following sections:
򐂰 RMILogger and Account are EJBs defined in the application.
򐂰 The required try-and-catch Java exception code has been removed for
conciseness.
򐂰 Only essential import statements and code snippets are shown.
Conversion of RMI lookup
You may run into either of the following remote object lookup sequences. Both of
these should be upgraded to the standard J2EE lookup sequence.
1. RMI Lookup
Example 7-21 shows the Java code for a traditional RMI lookup. The
rmi://lcalhost:7001 protocol, host, and port values are optional. Host defaults
to localhost and port defaults to 1099.
Example 7-21 Traditional RMI lookup
import weblogic.rmi.Naming;
RMILogger theLogger =
(RMILogger)Naming.lookup("rmi://localhost:7001/RMILoggerServer");
The WebLogic dependency is easily removed by changing weblogic.rmi to
java.rmi. However, conversion to the J2EE standard requires replacing the
code with that shown in Example 7-22. This code does not use the local JNDI
context. This is because the local JNDI context is read only, and we are
assuming that the target object is bound dynamically. If the object can be
bound by a deployment descriptor, then you should use the local JNDI
context with a name like java:comp/env/ejb/rmiLogger.
Example 7-22 J2EE standard for global JNDI name lookup
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
InitialContext ctx = new InitialContext();
Object home = ctx.lookup("RMILoggerServer");
Chapter 7. Naming
167
RMILogger logger =
(RMILogger) PortableRemoteObject.narrow(home, RMILogger.class);
2. InitialContext lookup with explicit initialization parameters
When JNDI was first introduced, it was generally used with the Java code
seen in Example 7-23. Some WebLogic applications continue to use this style
to obtain the failover and clustering advantages of the proprietary WebLogic
t3 protocol. Although this is probably no longer needed in WebLogic V6.1, it is
certainly not recommended for portable applications.
Example 7-23 InitialContext lookup with explicit properties
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
Properties h = new Properties();
h.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
h.put(Context.PROVIDER_URL,"t3://localhost:7001");
InitialContext ctx = new InitialContext(h);
Object home = ctx.lookup("containerManaged.AccountHome");
AccountHome accountHome = (AccountHome) (home);
The following changes are recommended to upgrade this code to the J2EE
standard. The results are shown in Example 7-24.
– Remove the Property variable and associated initialization code. New
InitialContext() will access the JNDI context defined in the J2EE container.
– Replace the global JNDI name in the lookup method with a local JNDI
name. This name must be mapped to the appropriate global JNDI name
by a vendor-specific deployment descriptor.
– Replace the explicit cast to AccountHome with the PortableRemoteObject
cast shown in Example 7-24. This is required for CORBA compliant
objects.
Example 7-24 J2EE standard local JNDI name lookup
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
InitialContext ctx = new InitialContext();
Object home = ctx.lookup("java:comp/env/ejb/account");
AccountHome accountHome =
(AccountHome) PortableRemoteObject.narrow(home, AccountHome.class);
168
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Conversion of RMI registration
Example 7-25 shows the Java code for a traditional RMI registration. This code
may be run from within an EJB or a Servlet. The resulting RMI registry can be
looked up by the code in Example 7-22 on page 167.
Example 7-25 RMI runtime registration
import weblogic.rmi.Naming;
RMILoggerImpl obj = new RMILoggerImpl("RMILoggerServer");
Naming.rebind("RMILoggerServer", obj);
The WebLogic dependency is easily removed by changing weblogic.rmi to
java.rmi. However, conversion to the J2EE standard requires replacing the code
with that shown in Example 7-26. This code has the following features:
򐂰 This code cannot use the java:comp/env local JNDI context because that
context is defined by the J2EE specifications as read only
Any update to the local JNDI context causes an exception. The initial JNDI
context used in Example 7-26 is not restricted and can be used for runtime
dynamic binding.
򐂰 The PortableRemoteObject exportObject method initiates listening for remote
method calls.
򐂰 The RMILoggerService symbol bound by this code can be read by the code in
Example 7-22 on page 167.
Example 7-26 JNDI runtime registration
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
InitialContext ctx = new InitialContext();
RMILogger obj = new RMILoggerImpl("RMILoggerServer");
PortableRemoteObject.exportObject(obj);
ctx.rebind("RMILoggerServer", obj);
Banking example footnote
Although the information in this section was used when migrating in the example
in 12.4, “Banking example” on page 302, due to time constraints not all of the
recommendations were fully implemented. This is what was done and what was
not done:
򐂰 All RMI code was upgraded to JNDI code.
򐂰 InitialContext parameters were removed.
򐂰 Local JNDI names and J2EE EJB references were not implemented.
Chapter 7. Naming
169
򐂰 Although there is no apparent reason for the RMILogger to be registered
dynamically, we did not convert it to J2EE deployment descriptors.
If the dynamic binding is retained, an environment variable should be added
for its JNDI name instead of the hard-coded RMILoggerService name.
򐂰 Casts were upgraded to use PortableRemoteObject.
7.4.5 The ejb-link alternative
The J2EE specification for EJB references (the <ejb-ref> element) provides for
an optional <ejb-link> element. Example 7-27 gives an example of its use in the
Pet Store example. The <ejb-link> name in this example is TheAccount. It must
be the <ejb-name> for an EJB in the scope of the application. It can be in another
EJB module, but it must be in an ejb-jar.xml file contained in the same EAR file. If
<ejb-link> is present, the EJB reference should be resolved to the named EJB.
Example 7-27 Pet Store ejb-link not effective
<ejb-ref>
<ejb-ref-name>ejb/account/Account</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>com.sun.j2ee.blueprints.customer.account.ejb.AccountHome</home>
<remote>com.sun.j2ee.blueprints.customer.account.ejb.Account</remote>
<ejb-link>TheAccount</ejb-link>
</ejb-ref>
The J2EE specifications are somewhat ambiguous about who is responsible for
implementing this binding. It may be the deployer’s responsibility, or it may be the
deployment tool’s responsibility. There seems to be no reason why an <ejb-link>
cannot be automatically bound to the named EJB. Based on our migration
experience, this would be a big advantage for applications that use this feature. It
would save the manual reentry of the global JNDI names for each EJB reference.
Unfortunately, neither WebSphere Studio Application Developer or AAT appears
to do this automatically at this time. We tried both tools. WebSphere Studio
Application Developer offers no assistance in making this binding. It does not
even try to verify what is actually entered. AAT does offer a list of alternative
EJBs to select from. We did only a superficial test on AAT, but it does not appear
to process <ejb-link> automatically either.
170
Migrating WebLogic Applications to WebSphere Advanced Edition V4
7.5 Future importance of JNDI
In this book, we look at only a very thin slice of JNDI naming facilities. JNDI is
actually a vast topic beyond the scope of this book. For more information, see
http://robocode.alphaworks.ibm.com/docs/jdk1.3/guide/jndi/. It provides a
more detailed view of its architecture and features. These include:
򐂰 Flexibility to support a wide variety of different naming syntaxes, for example
LDAP, RMI, COS Naming, NIS, and DNS standards.
򐂰 Integration with a broad variety of naming and directory service providers.
http://java.sun.com/products/jndi/serviceproviders.html provides a
comprehensive list of service providers.
򐂰 Ability to navigate a growing network of existing directories with objects
representing many different kinds of things, from software factory objects, to
printers, to locations, to people.
򐂰 Ability not only to name and locate objects, but to also attach a rich set of
attributes to describe these objects
JNDI is an integral part of the J2EE technologies. It will change very little, but its
use will continue to increase. We have already discussed some of the J2EE 1.2
technologies that depend on JNDI. These include naming and lookup for:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
EJBs from Servlets and other EJBs
DataSources for EJBs, Servlets and other JDBC services
Environment variables for EJBs and Servlets
UserTransactions supported by JTA
JavaMail services, using JAF
Data-driven viewers and editors, activated by JAF, and based on DataSources
of different types — anything using JAF depends on JNDI
We looked at previews of some of the J2EE 1.3 technologies in 2.2.2, “J2EE 1.3
preview technologies” on page 21 and in 2.2.3, “J2EE 1.3 and beyond” on
page 24. The J2EE 1.3 specification impacts JNDI in the following ways:
򐂰 JNDI 1.2 is folded into the J2SE 1.3 APIs
The Internet Domain Naming System (DNS) service provider will be added to
added to JNDI in J2SE 1.4.
򐂰 EJB 2.0 modifies its dependence on JNDI in a couple of ways:
a. The new dependent EJBs with local interfaces are not visible outside of
the EJB container, so they are not registered in JNDI.
b. The new message-driven beans integrate with JMS and its use of JNDI.
򐂰 JAAS, new to J2EE 1.3, depends on JNDI.
Chapter 7. Naming
171
򐂰 JCA, new to J2EE 1.3, looks up ManagedConnectionFactory objects through
JNDI.
򐂰 JMS mandates support for point-to-point and publish-subscribe. These use
JNDI for connection factory and destination objects.
Looking further ahead to J2EE 1.4 and beyond, there are currently a dozen JSRs
that mention JNDI as a candidate for supporting their naming and directory
needs. At first glance, almost anything that needs to publish a factory object or
other interface information could use JNDI. On closer examination, however,
other issues dominate:
1. J2EE 1.4 will emphasize Web services, and JNDI may not meet their needs.
Enterprise Web Services (JSR#109) lists JNDI as possible support for XML
registries, but Java API for XML Registries (JAXR, JSR#93) argues that JNDI
is not suitable for the requirements of business registries.
2. Other JSRs need features not found in JNDI.
Preferences API Specification (JSR#93) says JNDI is too heavy for user
preference data and configuration data. Java Temporary Caching API
(JCACHE, JSR#107) needs support for object expiration and synchronized
creation.
However, it is clear that JNDI will continue to be used for many future Java and
J2EE facilities. Just to give you a flavor for what is being considered by others,
here is the list of possible future JNDI clients as represented by current JSRs:
򐂰 Operations support system (OSS) services for back-office operations (five
JSRs) — activation, quality of service, inventory, trouble ticket, billing
򐂰 Java Agent Services (JSR#87) for autonomous communicative agents
򐂰 International locale information (JSR#150) for J2EE applications
򐂰 Computer Telephony Integration (CTI, JSR#61) for phonelets for J2EE
򐂰 Java DataObjects (JDO, JSR#12) for Java-centric persistent information
򐂰 Java Management Extensions (JMX, JSR#3) for managing Java-enabled
resources
򐂰 Java Print Services (JPS, JSR#6) for printing through Jini
172
Migrating WebLogic Applications to WebSphere Advanced Edition V4
8
Chapter 8.
Java Servlets and
JavaServer Pages
Java Servlets and JavaServer Pages are the parts of our application that the user
interacts with. If the client is a Web browser or a more generic client such as a
mobile device, the normal flow for the application will be invoking a servlet that
will act a a director for the client. Based upon the URL parameters that the client
passed, the servlet will perform the required actions normally by invoking
business logic beans, and the results will be passed for formatting to the JSPs,
usually using Java Beans. Therefore, we have to focus a big effort here so the
client for our application will not notice the migration.
© Copyright IBM Corp. 2002
173
8.1 Introduction
The Web application examples distributed with WebLogic V6.1 form the basis for
this chapter. We used them with the following straightforward process to discover
common migration issues in Java Servlets and JavaServer Pages.
1. Make sure the examples run on our WebLogic system.
2. Import source code and standard deployment descriptors into WebSphere
Studio Application Developer.
3. Make minimum changes to compile, deploy and test run.
4) Complete deployment and export EAR files.
A summary of the examples is provided in 8.3, “Migration examples” on
page 176. Not all examples were migrated.
As a rule, standard J2EE deployment descriptors should not require modification
across servers. However, we found a few exceptions to this rule. These issues
are covered in 8.2, “Differences in deployment descriptors” on page 174.
Based on our experience, the majority of migration issues will concern your
JavaServer Pages. These issues are covered in 8.4 "JSP migration issues".
The Java Servlets examples migrated with minimal changes. You can use either
WebSphere Studio Application Developer or AAT to establish vendor-specific
deployment descriptors. These alternatives are discussed in 8.5 "Deploying Web
application".
8.2 Differences in deployment descriptors
The Java 2 Platform, Enterprise Edition specifies a generic XML file web.xml for
Web modules. This file is interpreted in the same way for both WebLogic and
WebSphere application servers as long as we use the web-app_2_2.dtd. This is
the DTD associated with Java Servlets 2.2 and JavaServer Pages 1.1. BEA
offers preview technology that allows use of the draft for web-app_2_3.dtd and
differences allowed by this DTD will not be recognized and executed by
WebSphere Application Server. Therefore we need to stick to the 2.2
specification level DTD in order to easily migrate our applications.
In the following sections, we describe two aspects that need to be considered to
successfully migrate a web.xml file.
174
Migrating WebLogic Applications to WebSphere Advanced Edition V4
8.2.1 Strict servlet-mappings
As described in Migrating WebLogic Applications to WebSphere Advanced
Edition, SG24-5956, WebSphere Application Server is strict about the
servlet-mapping.
For example WebSphere is strict about having the servlet-mapping section of the
web.xml file conform to the Java Servlets 2.2 specification (Section 10.2). In
particular, it requires that the servlet-mapping begin with a ‘/’ character.
8.2.2 Validation of web.xml
It is possible to make changes to web.xml from the editor for application
descriptors from within WebLogic. We need to pay special attention to those
changes, since we may add an element that uses the 2.3 specification level.
Example 8-1 shows the beginning of a web.xml file used in our examples. Note
that it specifies the web-app_2.2.dtd.
Example 8-1 web.xml for examples
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">
....
However, we found that is possible to alter the web.xml using WebLogic’s Web
tooling, so that an element that does not conform to the web-app_2.2.dtd, but
instead conforms to the web-app_2.3.dtd, is added to the web.xml file. Elements
like this are also included if we use the weblogic.ant.taskdefs.war.DDInit utility.
Even though the element is not compliant with the specified dtd, WebLogic will
not produce an error report, but when we deploy to WebSphere Application
Server we get an error.
8.2.3 Proprietary deployment descriptors
WebLogic provides a proprietary weblogic.xml file where we specify information
relevant to the WebLogic servlet engine. This information is not covered by the
J2EE specification. WebSphere Application Server uses two files,
ibm-web-ext.xmi and ibm-web-bnd.xmi, to provide similar information. We found
it quite simple to provide this information for WebSphere at migration by using
either WebSphere Studio Application Developer or AAT.
Chapter 8. Java Servlets and JavaServer Pages
175
8.3 Migration examples
In this section we point out some of the common topics that will have to be
considered when migrating real-world applications. Every application will be
different, but we give some guidance for common migration topics.
8.3.1 Introduction
For the migration to be successful, it is very important that we have the source
code because we will often have to make code changes.
To provide samples of the changes that may be necessary, we migrated several
samples that are provided with BEA WebLogic Server V6.1 to our WebSphere
environment. These servlets and the JSPs we migrated are included with the
WebLogic examples server. The source code is provided in a different folder that
is outside the Web module WAR file. We imported the source code for the
servlets and JSPs into WebSphere Studio Application Developer and generated
the deployment descriptors. We took this approach since there was nothing in
the original web.xml from WebLogic except for the <servlets>, <taglib> and
<servlet-mapping> elements that would be of interest for our migration purposes.
Once we created the enterprise application and the Web module in WebSphere
Studio Application Developer, we edited the web.xml file using the web.xml editor
and copied all of the contents of the original WebLogic web.xml that are relevant
for our servlets and JSPs into the new WebSphere web.xml. We did this after
importing the source code and resources for those servlets and JSPs that we
were going to migrate.
If WebLogic had provided a WAR file with the source code as well as the
resources and the descriptors, we could import this file directly to WebSphere
Studio Application Developer, in a manner similar to that described in “Import
EAR file” on page 72.
Alternately we could also create a WAR file using tools outside of WebSphere
Studio Application Developer and then import this file.
We need to make sure that our web.xml file is defined according to
web-app_2_2.dtd. If there is an element that does not belong to the DTD,
WebSphere Studio Application Developer will show a warning in the tasks
window of the J2EE perspective.
8.3.2 Java Servlets
The servlets that we migrated with no code changes at all are:
176
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
examples.servlets.HelloWorldServlet
examples.servlets.HelloWorld2
examples.servlets.HelloWorld3
examples.servlets.CokieCounter
examples.servlets.PhoneServlet
examples.servlets.SessionServlet
examples.servlets.SurveyServlet
The servlet that we migrated with some code changes is:
򐂰 examples.servlets.SnoopServlet
The servlets we didn’t migrate are:
򐂰 examples.servlets.SimpleFormServlet
򐂰 examples.servlets.HelloKonaServlet
The code changes for SnoopServlet are shown in Example 8-2.
Example 8-2 SnoopServlet
......
print(out, "Authorization scheme", req.getAuthType());
print(out, "Request scheme", req.getScheme());
out.println("</pre>");
out.println("<h1>Certificate Information</h1>");
try {
//The WebLogic Certificate objects have been removed
//sun.security.x509.X509Cert sunCert = new
sun.security.x509.X509Cert( certs[0].getBytes() );
//print(out, "X509Cert",sunCert.toString());
out.print("<h2>Java Security Objects</h2>");
out.println("<pre>");
java.security.cert.X509Certificate javaCerts[] =
(java.security.cert.X509Certificate[]) req.getAttribute(
"javax.servlet.request.X509Certificate");
if (javaCerts != null) {
.......
We removed the references to WebLogic certificate objects.
As described in the previous redbook Migrating WebLogic Applications to
WebSphere Advanced Edition, SG24-5956, WebSphere Application Server does
not support htmlKona, which is used by SimpleFormServlet and
HelloKonaServlet. Therefore, we should replace the htmlKona code with some
other means of preparing the HTML output.
Chapter 8. Java Servlets and JavaServer Pages
177
Error pages
For a Web application we can specify a Web module-wide error page based on
the exception type or the HTTP error code produced. The way the exception type
works is that, whenever an exception is thrown for the service method of the
servlet called, the container will redirect the call to the first error page that
matches that criteria. Example 8-3 shows how error pages are specified in a
web.xml file.
Example 8-3 error-page element in web.xml
....
<error-page>
<exception-type>java.lang.Exception</exception-type>
<location>/ErrorPage.jsp</location>
</error-page>
<error-page>
<error-code>404</error-code>
<location>/ErrorPage.html</location>
</error-page>
....
WebSphere Application Server does not cast the exception, so if we specify an
error page for java.lang.Exception, then java.lang.NullPointerException will not
be passed to the error page as WebLogic does. Instead, we have to provide
specific mapping for that particular exception. We can also specify a
defaultErrorPage. The specified error page is defined in the ibm-web-ext.xmi file.
When dealing with the information specified in this file, it is best to use AAT as
shown in Figure 8-1.
178
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 8-1 IBM extensions editor
8.3.3 JavaServer Pages
The JSPs we migrated with no code changed are:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
HelloWorld.jsp
ShowDate.jsp
ThrowException.jsp
pagehits.jsp
showcode.jsp
SessionList.jsp
These JSPs required some small changes:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
ErrorPage.jsp
InteractiveQuery.jsp
JdbcTable.jsp
SessionServlet.jsp
SimpleDBLogin.jsp
SimpleSession.jsp
SnoopServlet.jsp
UrlEncode.jsp
Chapter 8. Java Servlets and JavaServer Pages
179
The JSP we did not easily migrate is:
򐂰 FormValidation.jsp
The minor changes that we needed to perform in order to have those examples
running were the following:
򐂰 All references to the class PrintStream need to be changed to the fully
qualified name java.io.PrintStream. WebLogic does not complain if this and
some other classes are not fully qualified, but in order to have them working
correctly in WebSphere Application Server, Advanced Edition, we need to
either qualify explicitly those classes or use an import statement. It is
preferable to use the import statement and not to qualify the class names
unless we have two different classes with the same name but belonging to a
different package.
򐂰 Similarly references to the classes Enumeration and Properties must be fully
qualified or have an import statement supplied.
򐂰 There are some unnecessary imports in the JSPs that can be removed. For
example we found import references to weblogic.db.jdbc and to
weblogic.common.
򐂰 For SnoopServlet.jsp we removed the WebLogic Certificate Objects, just as
we did with the servlets.
BEA WebLogic Server comes with an evaluation copy of the Cloudscape
database that allows only one connection at the time. Therefore we cannot have
a connection open from both application servers and if we need to use this
Cloudscape database in our testing, we must shut down one of the application
servers.
For those JSPs requiring access to a demo database from Cloudscape, we had
to perform the necessary setup to be able to connect to the database. These
settings are specified in 8.5.1, “WebSphere Studio Application Developer
approach” on page 187.
The JSPs we did not migrate are:
򐂰 EasyTableDisplay.jps
򐂰 EJBBeanManagedClient.jsp
We did not migrate these JSPs because the first one uses proprietary classes
and the second one performs an EJB lookup that we covered in Chapter 5,
“Security” on page 111.
180
Migrating WebLogic Applications to WebSphere Advanced Edition V4
8.4 JSP migration issues
Based on our experience, most of the migration problems for Web applications
occur in the JSP code and its deployment. We found a number of issues that
needed consideration when migrating JavaServer Pages. These issue, including
handling tag libraries, JSP expression tags, and JSP parameter settings, are
discussed in the following sections.
8.4.1 Tag libraries
As specified in the redbook Migrating WebLogic Applications to WebSphere
Advanced Edition, SG24-5956, the goal for tag libraries is to make it easier to
include complex Java logic in the presentation layer they can use simple custom
tags.
WebLogic and WebSphere Application Server come with their own set of tag
extensions and support the use of custom tags. The set of tags for WebSphere
Application Server will help us define database access as well as return the
values of the query. For more details of these tag libraries see section 4.2.2.3.7
of the WebSphere InfoCenter.
We did not have any problem migrating three of the four WebLogic examples that
use custom tags. These were pagehits.jsp, showcode.jsp and SessionList.jsp.
The only migration issues were those already discussed in 8.3.3, “JavaServer
Pages” on page 179. These examples show the use of tag libraries and come
with source code.
There are also two sets of custom tag libraries, weblogic-tags.jar and
weblogic-vtags.jar, that come with WebLogic and that can be found in the
<WL-install-dir>/ext. When we migrated FormValidation.jsp, which uses
weblogic-vtags.jar defined by WebLogic, we had to include the latest Jakarta
ORO Java classes. The current version is 2.0.5. See
http://jakarta.apache.org/oro/index.html for more information about ORO.
WebLogic validation tags are described at
http://e-docs.bea.com/wls/docs61/jsp/validation_tags.jsp and they give us
utilities to validate the text in fields against a regular expression, compare two
fields in a form, and verify that a required field has been filled in.
WebLogic JSP form validation tags include:
1. summary
The summary tag is the parent tag for validation. We must place the opening
<wl:summary> tag before any other element or HTML code in the JSP and we
must place the <wl:summary> tag anywhere after the closing </wl:form>.
Chapter 8. Java Servlets and JavaServer Pages
181
2. form
The form tag allows you to specify an HTML form that can be validated using
the WebLogic JSP form validation tags.
3. validator
We specify one or more <wl:validator> tags for each form field. The cases
where we will specify more than one are, for example, when we need to
validate an input against some pattern and it is a required input.
The FormValidation.jsp file is in the
<WL-install-dir>samples/examples/jsp/tagext/form_validation directory. We
imported this file to WebSphere Studio Application Developer. We also had to
import weblogic-vtags.jar to the lib directory of the Web module since we used
the same element in the web.xml file as shown in Example 8-4.
Example 8-4 taglib element in web.xml
...
<taglib>
<taglib-uri>
tagl
</taglib-uri>
<taglib-location>
/WEB-INF/lib/weblogic-vtags.jar
</taglib-location>
</taglib>
...
When we first tested this example, the compiler reported
java.lang.Exception:org.apache.oro.text.regex.Perl5Compiler.class. There is a
Perl5Compiler class in the jacl.jar that is included in <WAS-install-dir>, but it
belongs to com.oroinc.text.regex.
It is described by the Jakarta Project at:
http://jakarta.apache.org/oro/index.html
The Jakarta-ORO Java classes are a set of text-processing Java classes that
provide Perl5 compatible regular expressions, AWT-like regular expressions, glob
expressions, and utility classes for performing subtitutions, splits, filtering
filenames, etc.
We downloaded the zip file jakarta-oro-2.0.5.zip from
http://jakarta.apache.org/builds/jakarta-oro/release/v2.0.5/, which
includes the latest release of the jakarta-oro-2.0.5.jar, and placed it the lib
directory used by our Web application. The jar files in the lib directory are added
to the classpath.
182
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Once we did this and re-started our example, FormValidator.jsp produced an
output similar to WebLogic. When the expression tag is evaluated, if the result is
null WebLogic does not output anything to the HTML file, while WebSphere
Application Server prints out null.
8.4.2 JSP expression tags
To specify a Java language expression that will be resolved at runtime, we will
place the variable or the method between the JSP expression tags <%= and %>.
When processing the JSP, the toString() method for the variable will be called
and displayed in the output HTML. If the variable is a primitive type, the value will
be automatically converted to string.
In FormValidation.jsp, we have the following code:
Example 8-5 JSP expression tags
....
<td width=33% ><font face="Helvetica" size=2> User Name: </td>
<td width=33% ><font face="Helvetica" size=2>
<input type="text" name="username" value=
"<%= request.getParameter("username") %>
">
....
When WebLogic processes the JSP, the text reads:
User Name :
But when WebSphere Application Server processes the JSP, the text reads:
User Name : null
Therefore we need to display the value for request.getParameter("username")
only if it’s different from null.
There are many ways to solve this issue. One possible workaround is shown in
Example 8-6:
Example 8-6 JSP expression tag for null
....
<% String name = "";if(request.getParameter("username") != null)
name=request.getParameter("username");%>
<input type="text" name="username" value="<%= name %>">
....
Chapter 8. Java Servlets and JavaServer Pages
183
8.4.3 Parameter settings for JavaServer Pages
There are some different parameters that can be specified within a <jsp-param>
element in the weblogic.xml file. For a detailed explanation, see:
http://e-docs.bea.com/wls/docs61/webapp/weblogic_xml.html
When migrating from WebLogic, we need to consider whether WebSphere has
JSP parameters that provide the same functionality in WebSphere Application
Server. The specific parameters for WebSphere are located in the
ibm-web-ext.xmi file and we can use the WebSphere Application Assembly Tool
(AAT) to set these properties.
The WebLogic properties available are:
1. compileCommand
Specifies the full path of the standard Java compiler user to compile the
generated JSP servlets.
WebSphere Application Server uses its own JVM, which cannot be changed.
Therefore this option has no equivalent in the WebSphere environment.
2. compileFlags
Passes one or more command-line flags to the compiler.
There is no equivalent for WebSphere Application Server.
3. compilerclass
Name of the Java compiler that is executed in WebLogic Server’s virtual
machine. If this parameter is set, the compileCommand parameter is ignored.
There is no equivalent for WebSphere Application Server.
4. encoding
Specifies the default character set used in the JSP page. If not set, this
parameter defaults to the encoding for your platform. If we use a JSP page
directive included in the JSP code, this setting will be overridden.
WebSphere Application Server provides the same functionality. Edit the WAR
file using AAT, select Assembly Property Extensions, click the JSP
Attributes element, and select New. On the resulting window, specify the
attribute name defaultEncoding and a value of your choice, for example
ISO-8859-1. WebSphere first checks for the contentType directive’s charset in
the JSP page. If not specified, it will use the value for the defaultEncoding
attribute. If this value is not established, it will use the System property file
encoding, and if not found it will use ISO-8859-1. Figure 8-2 shows how to set
JSP attributes using AAT.
184
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 8-2 JSP Attributes
5. compilerSupportsEncoding
When set to true, it will use the same rules as specified above for creating the
intermediate Java file. If set to false, the JSP compiler uses the default
encoding for the JVM when creating the intermediate Java file.
There is no equivalent for WebSphere Application Server.
6. keepgenerated
Saves the Java files that are generated as an intermediate step in the JSP
compilation process. Unless this parameter is set to true, the intermediate
Java files are deleted after they are compiled.
Similar behavior is provided by WebSphere Application Server and the name
for the attribute is the same as well. We can add this attribute using AAT as
we did for encoding.
7. noTryBlocks
This option is set to avoid receiving a java.lang.VerifyError exception when
compiling a JSP file that has numerous or deeply nested custom JSP tags.
There is no equivalent for WebSphere Application Server.
8. packagePrefix
Chapter 8. Java Servlets and JavaServer Pages
185
Specifies the package into which all JSP pages are compiled.
There is no equivalent for WebSphere Application Server.
9. pageCheckSeconds
Sets the interval in seconds, at which WebLogic Server checks to see if files
have changed and need recompiling.
There is no equivalent for WebSphere Application Server. The JSP file will be
checked each time it is requested, as specified in Section 4.2.2.1 of the
InfoCenter.
10.precompile
When set to true, WebLogic automatically precompiles all JSPs when the
Web Application is deployed or re-deployed or when starting BEA WebLogic
Server.
Similar behavior is provided by WebSphere Application Server. To set this
option to false or true, edit the WAR file with AAT.
Select the root for your Web module, then select the IBM Extensions tab.
This will show the IBM Extensions editor, as seen in Figure 8-1 on page 179.
Check Precompile JSPs to enable precompilation.
11.verbose
If this property is set to true, BEA WebLogic Server sends detailed debugging
information to the browser, the command prompt, and WebLogic log file.
There is no equivalent for WebSphere Application Server. Error information is
always returned to the browser. You may use error pages instead, as
described in “Error pages” on page 178.
12.workingDir
The name of the directory for the .java and .class generated classes.
We can specify this behavior in WebSphere Application Server by setting the
JSP attribute scratchdir using AAT.
There are some attributes available in WebSphere Application Server that have
no equivalent in WebLogic:
1. dosetattribute
By default, JSP files using the usebean tag with Scope=session do not always
work properly when session persistence is enabled.
186
Migrating WebLogic Applications to WebSphere Advanced Edition V4
2. jsp.repeatTag.ignoreException
In previous releases, the <txs:repeat> tag would iterate until one expected
exception was thrown. The problem is that there were also other types of
exceptions caught but not thrown, and therefore this could result in numerous
errors being returned to the browser. In WebSphere V4 this behavior is
corrected, but you can restore the previous behavior by using the attribute
jsp.repeatTag.ignoreException.
8.5 Deploying the Web application
Once you have examined the Java Servlets and JavaServer Pages in your
application and addressed any migration issues encountered, you will need to
deploy these to WebSphere Application Server. In the following sections, we
provide more details on how to deploy Java Servlets and JavaServer Pages in
WebSphere. While WebSphere Studio Application Developer supports all
aspects of the Web application migration process, either WebSphere Studio
Application Developer or AAT can be used to create and edit deployment
descriptors and export EAR files.
8.5.1 WebSphere Studio Application Developer approach
In this section, we show how to customize the deployment descriptors for
WebSphere Application Server using WebSphere Studio Application Developer.
We do not focus every single parameter required for a successful configuration.
Instead, we point out those parameters specific to our migration examples and
also describe some generic parameters used by WebSphere Application Server.
Most parameters are covered by the Java 2 Platform, Enterprise Edition 1.2
specification, so we do not have to modify anything regarding parameters. What
we need to worry about are the specific parameters that were specified in
weblogic.xml and that are to be migrated to ibm-web-bnd.xmi and
ibm-web-ext.xmi.
First we should make sure that we have web.xml defined correctly and make sure
that the JSP tag libraries are specified correctly. Figure 8-3 shows how this is
specified in WebSphere Studio Application Developer.
Chapter 8. Java Servlets and JavaServer Pages
187
Figure 8-3 JSP tag libraries
For those examples that specify the session ID in the URL, we need to enable
the URL rewriting property. This setting is specified by editing the WebSphere
Administrative Domain as shown in Figure 8-4.
188
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 8-4 Enabling URL rewrite
In this window we also enable the session manager that is provided WebSphere
Application Server to store and manage Web sessions. Support for cookies are
enabled by default.
In order to execute those servlets and JSPs that access the database demo from
Cloudscape, we need to include the cloudscape.jar in the classpath for the
server instance. Edit the server instance and select the Paths tab. In the
classpath we include the external jar
<WL-product-install>/samples/eval/cloudscape/lib/cloudscape.jar. We also
include a system property to specify the directory where the database files are
located. In the system properties list, we add the property
cloudscape.system.home with the value
<WL-product-install>/samples/eval/cloudscape/data as shown in Figure 8-5.
Chapter 8. Java Servlets and JavaServer Pages
189
Figure 8-5 System properties
If necessary, we may specify some properties for the Web module, such as
reload interval or default error page, by double-clicking the file ibm-web-ext.xmi.
This will open an XML editor where we can specify that information.
8.5.2 AAT approach
We can use AAT only in those cases where we have JSPs and servlets that are
fully compliant with Java 2 Platform, Enterprise Edition 1.2 and that do not
require any changes.
We open the WAR file in AAT after removing the weblogic.xml file. Once we save
the WAR file in AAT the ibm-web-ext.xmi and ibm-ext-bnd.xmi files will be
created.
It it a good idea to verify the descriptors before saving the file. Figure 8-6 shows
AAT being used to verify descriptors.
190
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 8-6 Verifying descriptors
We may find information specific to IBM deployment descriptors in the IBM
extensions tab of the ExamplesWebApp.
There are also some specific properties in the Assembly Property Extensions
element. The information located in EJB and resource references will be saved in
the ibm-web-bnd.xmi file.
For detailed information about AAT, refer to the InfoCenter.
8.5.3 Deploying the EAR resource
One you have created an application in WebSphere Studio Application
Developer, it is straightforward to deploy the application to WebSphere
Application Server, Advanced Edition. The steps to do this are described in
Chapter 4, “Development and migration tools” on page 67. See “Export EAR file”
on page 97, and “Deploy on WebSphere” on page 98 for details.
Chapter 8. Java Servlets and JavaServer Pages
191
8.6 Future specifications
As developers request new functionality, new versions of the J2EE specifications
are being produced regularly. Both BEA and IBM do offer preview versions of
new technology from time to time, but in general it is more common for BEA to
include preview technology in its products. BEA will often provide an
implementation of the proposed new specifications even before the final version
of the specification is released. Therefore we often found that BEA applications
to be migrated use specific features of a proposed future release of a
specification that will not be supported or work similarly in WebSphere
Application Server. An example of this is support for the XML format in
JavaServer Pages, which is discussed in the redbook Migrating WebLogic
Applications to WebSphere Advanced Edition, SG24-5956. In the following
sections we look ahead to some future changes.
8.6.1 Java Servlets 2.3
The following are the main changes since Version 2.2:
1. Application events
With the event listeners, the application developer will be able to have more
control over interactions with servlet context and HTTP session objects.
The elements that will throw the events from the servlet context are:
a. Livecycle. Events will be thrown whenever the servlet context has been
created and is ready to serve its first request or whenever it is about to
shut down.
b. Changes to attributes. Attributes on the servlet context have been added,
removed or replaced.
The elements that will throw events for the HTTP session are:
a. Livecycle. An HTTP Session has been created, invalidated or timed out.
b. Changes to attributes. Attributes have been added, removed, or replaced
on an HTTPSession.
2. Servlet filtering
A filter is a reusable piece of code that can transform the content of HTTP
requests and responses and header information. They do not generate the
contents but they adapt the contents.
IBM has special extension packages for these two features. These are
extensions to Java Servlets 2.2 and they may not be compliant with Java
Servlets 2.3. The IBM packages are:
– com.ibm.websphere.servlet.event
192
Migrating WebLogic Applications to WebSphere Advanced Edition V4
– com.ibm.websphere.servlet.filter
In order to have a portable application, we recommend you do not use these
IBM-specific packages in new applications. However, if the application you are
migrating from WebLogic makes use of Java 2 Platform, Enterprise Edition
V1.3 filters or events, then you will need to consider changing the code to use
the IBM classes. The IBM classes are not compliant with Java Servlets 2.3,
so the implementation they offer is likely to be different in the next compliant
release of WebSphere. We did not investigate this issue in detail during our
redbook sample migrations.
For further information on Java Servlets see:
http://java.sun.com/products/servlet.
8.6.2 JavaServer Pages 1.2
No major differences are expected in the next release of the JavaServer Pages
specification, so we do not consider it likely that many migration issues will arise
here. One area to be aware of is the use of XML syntax for JavaServer Pages.
We did not investigate this in our redbook. See Migrating WebLogic Applications
to WebSphere Advanced Edition, SG24-5956 for a discussion of this issue.
The JSP specification is available at:
http://java.sun.com/products/jsp.
Chapter 8. Java Servlets and JavaServer Pages
193
194
Migrating WebLogic Applications to WebSphere Advanced Edition V4
9
Chapter 9.
Enterprise JavaBeans
Enterprise JavaBeans (EJBs) are the core of the Java 2 Platform, Enterprise
Edition Java component technology. EJBs are remotely accessible, distributed
objects. They implement the business logic of an enterprise system and provide
clients with Java interfaces for remote access. As enterprise components, EJBs
extend the write once, run anywhere feature of Java to enterprise transactional
servers, such as WebSphere and WebLogic. In theory, an EJB can be
redeployed in any J2EE server without recompilation. All that is required is a
redeployment, optionally modifying deployment parameters to conform with the
new operational environment.
Figure 9-1 depicts the EJB architecture. The basic idea is that EJBs live inside
containers provided by J2EE vendors. The container is responsible for resource
services such as persistence, transactions, security, and resource management,
while the EJBs implement the business logic. Other Java classes can live in the
same container for use by EJBs, in particular for access to legacy systems.
Clients create and access EJBs through Java interfaces. Although the interfaces
declare the EJB business methods, interface calls are intercepted by the
container. EJBs only get control indirectly through container-managed method
calls. The container delegates interface calls to its contained EJBs only after
performing necessary system services.
© Copyright IBM Corp. 2002
195
An EJB is parameterized to enhance its portability. It can reference environment
properties, other resources such as DataSources, and other EJBs, but only
through indirect named references. The names are compiled into the EJBs, and
their values are provided by deployment descriptors. Transaction management,
security management, and container-managed persistence (CMP) are also
specified by declarative deployment parameters. A deployment descriptor is
constructed for the EJBs as part of an assembly process. A deployment
descriptor tool simplifies this process and packages the result as an EJB JAR
file. This file contains the original EJB classes and interfaces along with the
completed deployment descriptor.
client
(servlet, application)
remote
home
lookup resource
stub
stub
access,
update
create,
find
ejb-ref
lookup resource
environment
1.0
resource-ref
container
CMP & transactions
1.1
JNDI
server
env-entry
deployment descriptors
ties
Figure 9-1 EJB architecture
196
Migrating WebLogic Applications to WebSphere Advanced Edition V4
EJB
other Java classes
The next step is to deploy the EJB JAR into the container. Code is generated
during this step. Stubs and ties are generated for RMI/IIOP remote access to the
EJB objects. Vendor-specific code is also generated. This code includes the
vendor’s implementation of the deployment parameters. Vendors may extend
deployment descriptors with vendor-specific features. Additional code may be
generated to support these features.
The container provides a JNDI server for runtime access to the values of
deployment parameters. These values are loaded into the server when an EJB is
started. At that point, the EJB is available to all clients for access through the
JNDI server. Clients can include servlets, Java applications, and other EJBs.
Environment properties are also made available, but only to the EJBs with which
they were deployed. One of the major changes between the EJB 1.0 and the EJB
1.1 specifications affects the programmatic interface for access to environment
properties. EJB 1.0 uses a Properties object, while EJB 1.1 uses the JNDI
server.
At runtime, a client locates an EJB’s home through the appropriate JNDI server.
For a servlet in a Web server, this is normally the container’s default JNDI server.
A public JNDI server is needed for remote access directly from an application.
The EJB’s home object implements the Home interface and is used to create or
find EJB instances. EJB instances are referenced by the resulting stubs. The
stubs implement the EJB’s Remote interface. The Remote interface supports all
of the business logic methods, providing access and manipulation of the remote
EJB instances.
9.1 EJB 1.1
The EJB specification now standardizes far more than ever before. With EJB 1.1
came the introduction of standard XML-based deployment descriptors, which will
remain largely compatible with those for the EJB 2.0 specification. Still, the EJB
1.1 specification does stop short of providing standard answers for every aspect
of an EJB. Without so-called extended deployment information, it is not generally
possible to deploy an enterprise bean. This is an area where different vendors
have taken steps to distinguish themselves.
Both WebSphere Application Server and BEA WebLogic Server support a
concept of extended deployment descriptors. These extended deployment
descriptors, in conjunction with the standard deployment descriptors, provide the
complete deployment picture. The format of the extended deployment
descriptors is different for each application server; each is incompatible with the
other. The files do have different names for the two products, and can therefore
co-exist within the same EJB module.
Chapter 9. Enterprise JavaBeans
197
9.2 Coding differences
In general, little modification of application code is required. This is true in the
case when the original application is written in accordance with the EJB 1.1
specification. However, not all applications are written in full conformance with
the specification and may therefore require some modification. WebSphere
Application Server, as a general rule, is very strict about conformance with the
specification.
This section presents some examples of common violations of the EJB 1.1
specification that have been observed in a number of WebLogic applications.
9.2.1 Type narrowing with PortableRemoteObject
Type narrowing is very often not done correctly in WebLogic applications. The
EJB 1.1 specification, Section 5.9, states:
“A client program that is intended to be interoperable with all compliant EJB
Container implementations must use the
javax.rmi.PortableRemoteObject.narrow(...) method to perform
type-narrowing of the client-side representations of the home and remote
interface.”
According to this passage, all client-side representations of the Home and
Remote interfaces must be narrowed. This includes bean homes accessed
through JNDI and any references to bean instances that are created by the
home. It also includes bean references returned by finder methods as well as
bean (and home) references returned by other bean methods (one bean might,
for example, return a reference to another bean). That is, strictly speaking, both
the bean home and any instances (however they are obtained) must be
narrowed as shown in Example 9-1.
Example 9-1 Client-side representations of the Remote and Home interfaces must be
narrowed using PortableRemoteObject
...
Context context = new InitialContext();
Object object = context.lookup("EmployeeHome"),
EmployeeHome home =
(EmployeeHome)PortableRemoteObject.narrow(object, EmployeeHome.class);
Object bean = home.findById(42);
Employee employee = (Employee)PortableRemoteObject.narrow(bean,
Employee.class);
...
198
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Note: The EJB 1.1 specification itself does not consistently follow this rule in
its own code examples. The examples in the specification do consistently
narrow the home reference, but they do not narrow remote references to bean
instances.
Strictly speaking, the bean instances should be narrowed. Applications that do
not do the recommended narrowing of bean instances do still work in
WebSphere Application Server V4. However, it is dangerous to assume that this
will always be the case. Since EJB 1.1 does specifically make this
recommendation (more than once), it is recommended practice that narrowing be
consistently applied to your application. By doing so, you will ensure compatibility
with future versions of the specification and of WebSphere Application Server.
9.2.2 T3 protocol
WebSphere Application Server uses RMI/IIOP as required by the EJB 1.1
specification. Many existing BEA WebLogic Server applications also use
RMI/IIOP, but many older applications use WebLogic's proprietary T3 protocol.
The T3 protocol has been part of BEA WebLogic Server for many years; it has
only recently been deprecated with the 6.0 release of the product. A very large
number of applications still exist that make use of the protocol.
T3 was created in the very early days of BEA WebLogic Server. In fact, it actually
predates EJB. T3 is a communication mechanism that was created in response
to concerns that the standard remote object communication mechanism, Java's
Remote Method Invocation (RMI), was inadequate for enterprise applications.
The creators of T3 were concerned that RMI could not scale to handle the huge
volume that must be handled by an application server.
Functionally speaking, T3 provides the same set of services that RMI provides.
From the application developer's point of view, the differences are very subtle.
Both T3 and RMI require that a remote interface and implementation class be
created for each remote object. They both also include tools for generating client
and server artifacts for implementing the communication. These artifacts are
provided in the form of a client-side stub and a server-side skeleton as shown in
Figure 9-2.
Chapter 9. Enterprise JavaBeans
199
<<interface>>
IThing
Generated by
the developer
Client
message()
Server
Thing_stub
2
Thing_skel
3
message()
1
message()
Thing
Generated by
RMIC
Figure 9-2 RMI stubs and skels facilitate communication between clients and the object
on the server
When the client sends a message to the server-side object, the following things
occur:
1. The message is sent to the object’s client-side representation, the stub.
2. The stub turns the message into a format that can be sent using the
communication protocol, and sends the message to the waiting skel.
3. The skel intercepts the message, converts it back into a Java message, and
forwards it to the server-side message.
Java's RMI has evolved since the early days of application server development.
RMI now has the ability to work on CORBA's Internet InterOrb Protocol (IIOP)
communication protocol which is generally more efficient and resource friendly
than the original JRMP protocol. The combination is commonly referred to as
RMI/IIOP or RMI over IIOP. RMI/IIOP was strongly recommended for remote
communication as part of the EJB 1.0 specification; EJB 1.1 requires its use.
Fundamentally, RMI/IIOP is quite different from both T3 and RMI/JRMP at the
implementation level. From the application developer's point of view, however,
they are conceptually similar and the differences are relatively small.
200
Migrating WebLogic Applications to WebSphere Advanced Edition V4
When generating the runtime artifacts for RMI/IIOP, the RMI Compiler (RMIC)
generates a server-side tie rather than a skel. Aside from the fact that these
artifacts must actually be generated, this should have little or no effect on the
migration process. The WebSphere tools, including both AAT and WebSphere
Studio Application Developer, automatically generate the required RMI/IIOP
artifacts as part of the deployment code generation process for EJBs. An
automated build process may invoke RMIC directly. If you must do this as part of
an automated build, be sure to include the -iiop option so that RMIC knows to
build IIOP-compliant stubs and ties.
More than just stubs and ties are generated for EJBs. The EJB container also
creates an implementation of the home and remote interfaces. RMIC generates
the stubs and ties for the generated home and remote interface implementations.
The container may generate additional classes for other purposes as well.
Figure 9-3 shows the relationships between the home interface and the various
generated artifacts.
<<interface>>
ThingHome
Generated by
the container
Generated by
RMIC
Client
create()
EJSThingHome_stub
Server
EJSThingHome_tie
create()
EJSThingHome
ThingBean
ejbCreate()
Figure 9-3 The EJB container generates an implementation of the home interface. RMIC
generates the stubs and ties
Similar artifacts are generated for the remote interface. With EJB, it is the
generated classes for which the stubs and ties are built. These generated
classes form the runtime components of the EJB container.
Perhaps the most important difference between T3 and RMI/IIOP is that T3 is
generally more forgiving than RMI/IIOP in consideration of method parameters
and return types. The RMI/IIOP specification is very particular about the types
that can be passed remotely. As a general rule, values passed as either method
parameters or return values must be primitive types, or object types that are
either serializable or remote.
Chapter 9. Enterprise JavaBeans
201
A serializable object is passed by value between remote peers. That is, the
sender converts the object into bytes, which are delivered to the receiver via the
communication protocol. The receiver then converts the bytes back into an object
and then does its work. This conversion process is automatically done by RMI
and requires no direct interaction from the application developer. Any object that
should be passed by reference should be marked as serializable by making the
type implement the marker interface java.io.Serializable.
A remote object is passed by reference. That is, the remote object exists on one
machine and stays there. When it is passed around, a remote reference is
actually passed and any communication with that remote reference is resolved
back to the object on the server. All EJBs are remote. Other objects can be made
remote as well; remote objects must have a remote interface (which extends
java.rmi.Remote) and an implementation class. If your application does make
use of remote objects, it is important that the remote interface and not the
implementation class be used as the type for method parameters and return
values. This is one example where T3 can be more forgiving than RMI/IIOP.
Note: If an object’s class implements both java.io.Serializable and
java.rmi.Remote, either directly or indirectly, RMI/IIOP will treat the object as a
remote object by default. If you intend to pass an object by value, its class
should not implement java.rmi.Remote.
Consult the RMI/IIOP documentation for more information on valid types.
9.2.3 InitialContext constructors
InitialContexts are used to interact with the Java Naming and Directory Interface
(JNDI). With EJB, InitialContexts are primarily used to find a registered EJB
home. Example 9-2 shows some example code that does a JNDI lookup for an
application running in BEA WebLogic Server.
Example 9-2 Creating an InitialContext with parameters (using the T3 protocol)
...
java.util.Properties properties = new java.util.Properties();
properties.put(Context.PROVIDER_URL, "t3://localhost:7005");
properties.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
InitialContext context = new InitialContext(properties);
Object object = context.lookup("MyBeanHome");
...
202
Migrating WebLogic Applications to WebSphere Advanced Edition V4
This code example sets up some properties, and then uses the properties to
create an InitialContext. The InitialContext is used to look up a EJB Home
reference by name. The Context.PROVIDER_URL property's value,
t3://localhost:7005, indicates that we communicate with the JNDI server using T3
(see 9.2.2, “T3 protocol” on page 199), and that the server itself is located on the
local machine (localhost) on port 7005. The
Context.INITIAL_CONTEXT_FACTORY parameter indicates the name of the
class that is used to create the InitialContext that will be used. The InitialContext
type is actually an interface, and it is the responsibility of each vendor to provide
their own implementation and corresponding factory. The value of
weblogic.jndi.WLInitialContextFactory is the name of the class that implements
InitialContext for WebLogic's T3.
The values for the InitialContext create parameters are particular to the server.
As part of the migration to WebSphere Application Server, this code must be
changed. For WebSphere Application Server, the value for
Context.PROVIDER_URL should be of the form iiop://localhost:900. IIOP is the
communication protocol for the JNDI server running on the local machine on port
900. Of course, these values can be customized, but these are the defaults. The
value for the Context.INITIAL_CONTEXT_FACTORY property should be
com.ibm.websphere.naming.WsnInitialContextFactory. With these changes, the
code changes as shown in Example 9-3.
Example 9-3 Creating an InitialContext with parameters (using the IIOP protocol for
WebSphere)
...
java.util.Properties properties = new java.util.Properties();
properties.put(Context.PROVIDER_URL, "iiop://localhost:900");
properties.put(Context.INITIAL_CONTEXT_FACTORY,
"com.ibm.websphere.naming.WsnInitialContextFactory");
InitialContext context = new InitialContext(properties);
Object object = context.lookup("MyBeanHome");
...
The changes are relatively minor. However, if this code is repeated a number of
times in your code, putting the changes into effect can be time consuming.
The EJB 1.1 specification recommends that the zero-argument InitialContext
constructor be used. With this constructor, properties are provided using one of
two available mechanisms. These properties can be provided as system
properties (named java.naming.factory.initial and java.naming.provider.url) or
through entries in the lib/orb.properties file found in the Java Runtime
Environment (JRE) directory (WebSphere Application Server automatically
provides these values as system properties). Example 9-4 shows how the code
changes when the zero-argument constructor is used.
Chapter 9. Enterprise JavaBeans
203
Example 9-4 Creating an InitialContext without parameters
...
InitialContext context = new InitialContext();
Object object = context.lookup("MyBeanHome");
...
The zero-argument constructor provides a lot of value. To start, the application
code is simplified, which makes it generally easier to work with and maintain.
Further, the code is better insulated against future changes. If the name of the
InitialContext Factory is changed, WebSphere Application Server will make sure
the appropriate values are set into the system properties; your code will not
require modification.
9.3 Deployment descriptor differences
The EJB 1.1 deployment descriptor, ejb-jar.xml, is required by both BEA
WebLogic Server and WebSphere Application Server. This file contains
important information, including such things as the names of the beans and the
classes required to run. Example 9-5 shows a typical example of an EJB
deployment descriptor.
Example 9-5 J2EE session bean deployment (ejb-jar.xml)
<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans
1.1//EN' 'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>
<ejb-jar>
<enterprise-beans>
<session>
<ejb-name>HrFacadeBean</ejb-name>
<home>com.hr.beans.facade.HrFacadeHome</home>
<remote>com.hr.beans.facade.HrFacade</remote>
<ejb-class>com.hr.beans.facade.HrFacadeBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
<ejb-ref>
<description>Local reference to the EmployeeHome</description>
<ejb-ref-name>ejb/EmployeeHome</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>com.hr.beans.domain.EmployeeHome</home>
<remote>com.hr.beans.domain.Employee</remote>
<ejb-link>EmployeeHome</ejb-link>
</ejb-ref>
</session>
</enterprise-beans>
<assembly-descriptor>
<container-transaction>
204
Migrating WebLogic Applications to WebSphere Advanced Edition V4
<method>
<ejb-name>HrFacadeBean</ejb-name>
<method-name>*</method-name>
</method>
<trans-attribute>Required</trans-attribute>
</container-transaction>
</assembly-descriptor>
</ejb-jar>
The session stanza defines a session bean. This particular session bean, as
indicated by the session-type stanza, is stateless. The session stanza declares
some important information about the bean, including the names of the types
required to make this bean work.
The ejb-ref stanza indicates how the session bean references other beans and
resources. The descriptor shown in Example 9-5 uses a local name of
ejb/EmployeeHome for connecting to the EmployeeBean’s home interface
through the local JNDI space. The name ejb/EmployeeHome translates into
java:comp/env/ejb/EmployeeHome at runtime. Example 9-6 shows how the
name might be used in code.
Example 9-6 How the local JNDI name is used in code
Context context = new InitialContext();
Object object = context.lookup("java:comp/env/ejb/EmployeeHome");
EmployeeHome home = (EmployeeHome)PortableRemoteObject
.narrow(object, EmployeeHome.class);
At runtime, the local name ejb/EmployeeHome must be connected to a global
JNDI name. The EJB 1.1 specification does provide a mechanism for specifying
local names (as shown in the ejb-jar.xml file). It does not, however, specify how
to connect the local name to a global name. This is one (of many) points where
the WebSphere solution differs from the WebLogic solution.
The ejb-reference-description stanza in the weblogic-ejb-jar.xml file provides this
connection on BEA WebLogic Server. Example 9-7 shows the
weblogic-ejb-jar.xml file containing extended deployment information.
Example 9-7 BEA WebLogic Server-specific deployment information (fragment from
weblogic-ejb-jar.xml)
<!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 6.0.0
EJB//EN' 'http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd'>
<weblogic-ejb-jar>
<weblogic-enterprise-bean>
<ejb-name>HrFacadeBean</ejb-name>
<jndi-name>com/hr/beans/facade/HrFacadeHome</jndi-name>
Chapter 9. Enterprise JavaBeans
205
<reference-descriptor>
<ejb-reference-description>
<ejb-ref-name>ejb/EmployeeHome</ejb-ref-name>
<jndi-name>com/hr/beans/domain/EmployeeHome</jndi-name>
</ejb-reference-description>
</reference-descriptor>
</weblogic-enterprise-bean>
</weblogic-ejb-jar>
The weblogic-ejb-jar.xml file also provides a number of other useful bits of
information that are not handled in a standard way, including such things as the
JNDI name for the bean itself (the jndi-name stanza in the
weblogic-enterprise-bean stanza).
For deployment on WebSphere Application Server, some changes must be made
to the J2EE deployment descriptor. In particular, an id attribute is included with
some of the tags. Example 9-8 shows the session and ejb-ref tags with id
attributes. The WebSphere Application Server-specific version of this file
includes an id attribute on the session tag. The value associated with the id
attribute is used to cross reference into the WebSphere-specific deployment files.
Example 9-8 WebSphere Application Server-specific J2EE deployment descriptor
(ejb-jar.xml)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans
1.1//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">
<ejb-jar id="ejb-jar_ID">
<display-name>WLEJBExampleEJB</display-name>
<enterprise-beans>
<session id="HrFacade">
...
<ejb-ref id="EjbRef_1">
<description>Local reference to the EmployeeHome</description>
<ejb-ref-name>ejb/EmployeeHome</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>com.hr.beans.domain.EmployeeHome</home>
<remote>com.hr.beans.domain.Employee</remote>
<ejb-link>EmployeeHome</ejb-link>
</ejb-ref>
</session>
</enterprise-beans>
...
</ejb-jar>
206
Migrating WebLogic Applications to WebSphere Advanced Edition V4
The ibm-ejb-jar-bnd.xmi file (see Example 9-9) specifies JNDI names for the
beans described in the ejb-jar.xml file. This file is also used to assign mappings
between the local JNDI names defined in the ejb-jar.xml file and the global JNDI
names used by the beans.
Example 9-9 WebSphere Application Server-specific Session Bean deployment
descriptor (ibm-ejb-jar-bnd.xmi)
<?xml version="1.0" encoding="UTF-8"?>
<ejbbnd:EJBJarBinding xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"
xmlns:ejbbnd="ejbbnd.xmi" xmlns:ejb="ejb.xmi" xmlns:commonbnd="commonbnd.xmi"
xmlns:common="common.xmi" xmi:id="ejb-jar_ID_Bnd">
<ejbJar href="META-INF/ejb-jar.xml#ejb-jar_ID"/>
<ejbBindings xmi:id="HrFacade_Bnd"
jndiName="ejb/com/hr/beans/facade/HrFacadeHome">
<enterpriseBean xmi:type="ejb:Session"
href="META-INF/ejb-jar.xml#HrFacade"/>
<ejbRefBindings xmi:id="EjbRefBinding_1"
jndiName="ejb/com/hr/beans/domain/EmployeeHome">
<bindingEjbRef href="META-INF/ejb-jar.xml#EjbRef_1"/>
</ejbRefBindings>
</ejbBindings>
</ejbbnd:EJBJarBinding>
The ejbBindings stanza in this file contains the binding information. Within the tag
itself, the global JNDI name for the bean is specified. Occurrences of the
ejbRefBindings tag map global JNDI names to the local ones specified in the
ejb-jar.xml file. In this example, the HrFacade bean (indicated in the
enterpriseBean stanza) maps the reference named EjbRef_1 (included in the
ejb-ref tag in the ejb-jar.xml file) to the global name
ejb/com/hr/beans/domain/EmployeeHome).
It’s obvious that this file is not intended to be manually edited, nor is this file
intended to be human readable. WebSphere provides some tools to assist in the
construction of both the ejb-jar.xml and ibm-ejb-jar-bnd.xmi files. The Application
Assembly Tool ships with WebSphere Application Server. WebSphere Studio
Application Developer is a separate product that is a completely integrated
development environment.
Chapter 9. Enterprise JavaBeans
207
9.4 Application Assembly Tool
The Application Assembly Tool (AAT) is, as the name suggests, a tool for
assembling applications. The primary job of AAT is to build deployment artifacts,
including Enterprise Application Archive files (EAR), Web archive files (WAR),
and EJB archive files (EJB JAR). As part of the assembly process, AAT can
either make use of existing deployment descriptor files or can generate them
from scratch. EAR files generated by AAT can be immediately deployed on any
version of WebSphere Application Server.
While AAT is intended as a tool for generating deployable archive files, it can also
be used as part of an automated build process. More accurately, AAT generates
artifacts that can be used as part of an automated build process. Deployers can
use AAT to provide the deployment information required for the enterprise beans.
The EJB JAR file that is created as part of that process will contain deployment
descriptors that reflect the information captured in the tool. Those deployment
descriptors can be extracted from the archive and included as part of a larger
build process.
When AAT starts, it presents you with a welcome window (Figure 9-4) containing
a number of different options. The first row of options is shown in Figure 9-4.
Figure 9-4 The Application Assembly Tool welcome window
208
Migrating WebLogic Applications to WebSphere Advanced Edition V4
AAT presents a tree view containing the various aspects of deployment. One
entry in this tree view is for session beans (see Figure 9-5).
Figure 9-5 Creating a new session bean
By highlighting Session Beans in the tree view and selecting, New from the
context menu, you will be presented with a window gathering information about a
new session bean (Figure 9-6).
Figure 9-6 The New Session Bean window
Chapter 9. Enterprise JavaBeans
209
The New Session Bean window captures information about a session bean. The
window features a number of views (tabs) that permit you to enter both standard
and extended information about the bean.
Clicking the Browse buttons found on the window takes you to a types browser
(Figure 9-7). It takes some effort to get used to the types browser. The entry field
at the top of the window contains the browsing root. All types are located
relatively to this root. The root can be either a directory or a JAR/ZIP file. Use the
tree view to the left to navigate the contents of that root directory; select the
appropriate type (in this example, we are asked to select a Home interface) on
the right.
Figure 9-7 The types browser can locate classes for your bean in the file system as well
as in JAR and ZIP files
Once created, the new session bean will appear in the tree view under the
Session Beans category (Figure 9-8).
210
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 9-8 The new session bean is selected in the tree view
The right pane of the AAT window shows information that is specific to the
selection in the left pane. With a session bean selected, the right view contains
entries that can be used to edit all deployment aspects of the session bean.
Switch to the Bindings tab to specify a JNDI name for the session bean (this will
be stored in the ibm-ejb-jar-bnd.xmi file). Additional information, such as
environment properties, and method isolation levels can also be specified here.
To specify EJB references, highlight the EJB References node under the
session bean in the tree view and select New from the context menu (Figure 9-9)
Chapter 9. Enterprise JavaBeans
211
.
Figure 9-9 Create EJB references
With the New EJB Reference window (Figure 9-10), you specify EJB reference
information.
Figure 9-10 The New EJB Reference window
Once created, the EJB reference will appear in the table in the right pane of the
window (Figure 9-11). Note that the EJB References node must be selected in
the tree view. The EJB reference is stored in the ejb-jar.xml file.
212
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 9-11 Set the JNDI name for the EJB Reference
With the Bindings tab selected, enter the JNDI name for the reference. This
information will be placed in the ibm-ejb-jar-bnd.xmi file.
With the bean properties defined, the EJB JAR file can be saved (select File ->
Save or Save As...). Once saved, the EJB JAR file is ready to be deployed on
WebSphere Application Server or included as part of an EAR file. Alternatively,
the generated deployment descriptors can be extracted from the JAR file and
included as part of an automated build process.
For more information on AAT, consult the redbook WebSphere Version 4
Application Development Handbook, SG24-6134.
Chapter 9. Enterprise JavaBeans
213
9.5 WebSphere Studio Application Developer
WebSphere Studio Application Developer is the preferred tool for developing
applications for deployment to WebSphere Application Server V4. This tool
provides excellent code development, application assembly, testing and
debugging support for building enterprise applications. The redbook Web
Services Wizardry with WebSphere Studio Application Developer, SG24-6292,
contains an excellent introduction and overview of WebSphere Studio Application
Developer.
WebSphere Studio Application Developer is intended as a complete
development environment for all members of the development team. A number of
different perspectives assemble tools that are appropriate for different tasks. The
Java perspective, for example, contains tools for organizing and writing Java
code. The Debug perspective contains tools for debugging. Additional
perspectives provide tools specifically for data management (Data perspective),
Web content editing (Web perspective), enterprise application development
(J2EE perspective) and more.
Each perspective contains a number of different views. Some views are used in
multiple perspectives. In fact, you can customize perspectives to contain any
views you desire/require. The most common view is the Navigator view, which
presents a direct view of the underlying file system. Other views, such as the
J2EE view, provide a higher-level virtual look at the underlying files. The J2EE
perspective is used to build Enterprise JavaBeans.
9.5.1 WebSphere Studio Application Developer projects
WebSphere Studio Application Developer organizes applications into projects.
An EJB project, as the name suggests, contains some number of Enterprise
JavaBeans. Within the EJB project, beans can be added, manipulated, and
tested (with help from the Server perspective). When the EJB project is exported,
its contents are packed into an EJB JAR file.
J2EE requires that EJB JAR files be contained within an Enterprise Application
Archive (EAR) file. EAR files are represented by enterprise projects. EJB
projects are not contained within an enterprise project, but they are connected.
EJB projects are considered modules of an enterprise project. When the
enterprise project is exported as an EAR file, the referenced EJB projects are
packaged up and included as well.
214
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Create enterprise and EJB projects for your application. Switch to the Navigator
view and drop the source code for your beans in the ejbModule directory; drop
the ejb-jar.xml file into the META-INF directory. When you switch to the J2EE
view (included with the J2EE perspective), your Enterprise JavaBeans should
appear as shown in Figure 9-12.
Figure 9-12 Import existing enterprise bean classes using the Navigator view
When you switch to the J2EE view, WebSphere Studio Application Developer
figures out what Enterprise JavaBeans are available and displays them under the
EJB modules category. Figure 9-13 shows the J2EE view immediately after
importing the Enterprise JavaBean classes and the ejb-jar.xml file.
Figure 9-13 The J2EE view shows enterprise beans
Chapter 9. Enterprise JavaBeans
215
Once the Enterprise JavaBeans have been loaded into WebSphere Studio
Application Developer, the deployment descriptor can be accessed by
highlighting the EJB project (HrBeans in this example), and selecting Open With
-> EJB Editor from the context menu. The EJB editor, shown in Figure 9-14, is
used to specify the standard deployment descriptor information required by EJB
1.1.
Figure 9-14 The EJB editor showing the Beans page
The EJB editor works directly off the ejb-jar.xml file. If you have started from an
EJB 1.1-compliant deployment descriptor, then you will not have to change
anything in this editor. Figure 9-14 shows the EJB editor with the Beans page
selected (the Beans tab is selected on the bottom of the editor). The entries in
this page specify very basic information about the beans including the collection
of types that are required by the bean and container-managed fields (additional
container-managed fields can be specified in this editor as well). Additional
information is specified on the remaining pages. If you want to view the
ejb-jar.xml file directly, select the Source page.
Extended deployment information, including the JNDI name for each bean, is
specified by in the EJB extension editor. This editor, shown in Figure 9-15, can
be opened for the EJB project by selecting Open With -> EJB Extension Editor.
216
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 9-15 The EJB extension editor showing the Bindings page
The Bindings page is shown in Figure 9-15. On this page, the JNDI name for the
bean is provided. The name of the DataSource that owns the table
corresponding to the entity bean is also specified here, along with an appropriate
user name and password for accessing the database (if required).
Once this information has been specified, deployment code can be generated
and the bean tested. Deployment code is generated by highlighting the EJB
project and selecting Generate -> Deploy and RMIC Code from the context
menu. Test the bean by highlighting it and selecting Run on Server from the
context menu.
Third-party tools
Other third-party tools exist that can assist in the process of migrating WebLogic
deployment descriptors into WebSphere deployment descriptors. A set of
utilities, named was40util, available from the EJBINFO.COM Web site at
http://www.ejbinfo.com, provides some command-line tools that use XSL
stylesheets to perform the conversion of JNDI binding information.
We have not taken an opportunity to really stress these tools, but they do at least
appear to do a reasonably good job. While they do not do a complete job of the
migration, they do provide a start on the process (especially if you have a large
number of beans).
Chapter 9. Enterprise JavaBeans
217
9.6 Entity beans with container-managed persistence
Much more information must be provided for entity beans than for session beans.
In addition to the information required by session beans in the extended
deployment descriptor, CMP entity beans also require information detailing the
container-managed field mappings, finder queries and more.
9.6.1 CMP field mappings
The weblogic-cmp-rdbms.xml file defines the CMP field mappings and finder
information for the CMP entity beans. An example of this file is shown in
Example 9-10.
Example 9-10 An example weblogic-cmp-rdbms.xml file
<!DOCTYPE weblogic-rdbms-jar PUBLIC
'-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB 1.1 RDBMS Persistence//EN'
'http://www.bea.com/servers/wls600/dtd/weblogic-rdbms11-persistence-600.dtd'>
<weblogic-rdbms-jar>
<weblogic-rdbms-bean>
<ejb-name>Employee</ejb-name>
<data-source-name>hrds</data-source-name>
<table-name>EMP</table-name>
<field-map>
<cmp-field>empId</cmp-field>
<dbms-column>ID</dbms-column>
</field-map>
<field-map>
<cmp-field>firstName</cmp-field>
<dbms-column>FIRST</dbms-column>
</field-map>
<field-map>
<cmp-field>lastName</cmp-field>
<dbms-column>LAST</dbms-column>
</field-map>
<field-map>
<cmp-field>salary</cmp-field>
<dbms-column>SAL</dbms-column>
</field-map>
<finder>
<finder-name>findWithSalaryGreaterThan</finder-name>
<finder-param>double</finder-param>
<finder-query><![CDATA[(> salary $0)]]></finder-query>
</finder>
<finder>
218
Migrating WebLogic Applications to WebSphere Advanced Edition V4
<finder-name>findByName</finder-name>
<finder-param>double</finder-param>
<finder-query><![CDATA[(& (= lastName $0) (= firstName
$1))]]></finder-query>
</finder>
</weblogic-rdbms-bean>
</weblogic-rdbms-jar>
A weblogic-rdbms-bean stanza is declared for each Enterprise JavaBean. Within
this stanza, the name of the bean, the name of the DataSource, and the table
name are declared. The mappings for the container-managed fields are declared
as field-map entries. Each field-map declares a direct-to-field mapping between
the field and corresponding column in the table. Though it is not shown here, the
field-map stanza may also include column type information.
In WebSphere Application Server V4, field mappings are stored in the
ibm-ejb-jar-jdbc.xmi file. This file is not intended to be human readable and is
certainly not intended to be human-edited. Mappings between CMP entity beans
and an existing table (a so-called meet-in-the-middle mapping) must be manually
recreated using WebSphere Studio Application Developer (see “Mapping CMP
entity bean fields with WebSphere Studio Application Developer” on page 222).
9.6.2 BEA WebLogic Server CMP EJB finder queries
BEA WebLogic Server provides a number of different ways to specify queries for
the finder methods defined on a CMP entity bean’s home interface. Recent
versions of BEA WebLogic Server support EJB-QL, the EJB Query Language
that is included as part of the EJB 2.0 specification. Older versions of the product
support a proprietary query mechanism called WebLogic Query Language
(WLQL).
The WebLogic Query Language has been around since the early days of BEA
WebLogic Server. Queries in WLQL are specified using a prefix notation of the
form (operator operand1 operand2). The parentheses are part of the query. The
findWithSalaryGreaterThan finder specified in Figure 9-10 indicates the query in
the finder-query stanza. The value, specified as XML CDATA (character data), is
(> salary $0), which indicates that the query will find those employees whose
salary is greater than the first argument ($0) in the corresponding method in the
home interface.
The next finder, findByName, contains a compound query. (& (= lastName $0) (=
firstName $1)) indicates that the finder returns the employee whose lastName is
equal to the first argument in the corresponding method in the home interface,
and the firstName is equal to the second argument.
Chapter 9. Enterprise JavaBeans
219
These queries, which use the name of the field in the bean class, not the column
name are converted by BEA WebLogic Server into SQL statements. The
findWithSalaryGreaterThan query (> salary $0) would be expanded into a JDBC
statement similar to select ID, FIRST, LAST, SAL from EMP where (SAL > ?).
The query (& (= lastName $0) (= firstName $1)) defines a tree as shown in
Figure 9-16. The query tree is recursed in order to build the corresponding JDBC
statement.
&
=
lastName
=
$0
firstName
$1
Figure 9-16 WLQL queries use prefix notation to define a query tree
An in-order pass through this tree visits the nodes in this order: lastName, =, $0,
&, firstName, =, $1. Each subtree implicitly defines a set of parentheses that are
inserted into the generated SQL. By inserting parentheses for each subtree, the
resulting expression appears as ((lastName = $0) & (firstName = $1)). When this
expression is converted into SQL (substituting column names for field names),
the JDBC statement is something like select ID, FIRST, LAST, SAL from EMP
where ((LAST = ?) and (FIRST = ?)). The where clause is what you need for
WebSphere to be able to execute the query. Additional information about WLQL
can be found in the WebLogic product documentation.
WebSphere Application Server V4 does include support for EJB-QL as well. In
EJB-QL, this query becomes select e from EmployeeBean e where (e.lastName
= ?1 and (e.firstName = ?2).
Finder queries are declared on the Finders page in the EJB extension editor for
the EJB Project (shown in Figure 9-17). On the left side of the page, a tree view
displays the available entity beans and corresponding finder methods. With the
finder method highlighted, you can provide the query as a full SQL select
statement, an SQL where clause only, or as EJB-QL. In anticipation of EJB 2.0
support in the next version of WebSphere Application Server, EJB-QL is
preferred.
220
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 9-17 The Finders page on the EJB extension editor
9.6.3 Modified property
Earlier versions of the BEA WebLogic Server provide read-only methods for
entity beans by including an isModified() method and corresponding modified
boolean field in the bean class. Methods that modify the state of the bean set the
value of the modified field to true. The container uses the isModified() method to
determine whether or not the bean's state must be persisted when the
transaction completes. Beans that implement the isModified() method will work
without modification in WebSphere Application Server (WebSphere will simply
ignore the method).
WebSphere Application Server provides the ability to specify the access intent of
a method declaratively. Using the access intent setting, the container
automatically keeps track of whether or not the state must be persisted. The
access intent is specified in the extended deployment information. To realize the
performance benefits associated with this feature, the value must be set using
either WebSphere Studio Application Developer or the Application Assembly
Tool.
Chapter 9. Enterprise JavaBeans
221
9.7 Mapping CMP entity bean fields with WebSphere
Studio Application Developer
Once the enterprise bean code and deployment descriptor has been imported
into WebSphere Studio Application Developer (as described in 9.5, “WebSphere
Studio Application Developer” on page 214) you can use WebSphere Studio
Application Developer to map CMP bean fields.
Start this process by highlighting your EJB project in the J2EE view, and
selecting Generate > EJB to RDB Mapping.... A SmartGuide will appear to take
you through the mapping process. The SmartGuide appears only the first time
you attempt to generate the mappings. Only beans and tables that exist at the
time the SmartGuide runs are handled. If new entity beans are added, new
mappings will have to be manually created using the Mapping editor (see “The
mapping editor” on page 226).
WebSphere Studio Application Developer gives you several options when
creating the mapping:
򐂰 Bottom up: Create entity beans based on an existing database schema
򐂰 Top down: Create a database schema based on an existing set of entity
beans
򐂰 Meet in the middle: Create a mapping between existing entity beans and an
existing database schema
Through this process it is assumed that, since this is a migration effort, the
database and tables already exist and a meet-in-the-middle mapping is the most
appropriate.
The EJB to RDB mapping SmartGuide
The SmartGuide, shown in Figure 9-18, contains several pages. On these pages,
you will:
򐂰
򐂰
򐂰
򐂰
Specify the kind of mapping (bottom up, top down, or meet in the middle)
Connect to the database and get the list of tables
Select the tables to map
Generate a best guess at the mappings.
When the SmartGuide is complete, its best guess at the mappings can be tuned.
222
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 9-18 Specify a meet-in-the-middle mapping to map an existing entity bean to an
existing table
Click Next on the SmartGuide to move to the second page. On page 2, shown in
Figure 9-19, information about the database is gathered.
Chapter 9. Enterprise JavaBeans
223
Figure 9-19 Make a connection to your database on page 2 of the SmartGuide
In this example, DB2 7.2 is running on a remote machine named “hodge”. The
connection name is used by WebSphere Studio Application Developer to keep
track of this connection after it is created (the connection can be manipulated in
the Data perspective). If you have a connection already defined, the bottom-most
entry on this page lets you use that existing connection (useful when you are
mapping several different EJB projects).
When you leave the second page, the SmartGuide will connect to the database
and get a list of available tables as shown in Figure 9-20.
224
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 9-20 Page 3 of the SmartGuide shows the available tables
Put a check mark beside the names of the tables you want to map beans against.
The next page of the SmartGuide, shown in Figure 9-21, provides some options
for the tool to make a best guess at the mapping. You may choose to change the
mapping completely manually by selecting None, or can have the SmartGuide
do its best by mapping field and column by names, or by names and types.
Figure 9-21 The SmartGuide can generate a best guess at the mapping if desired
Chapter 9. Enterprise JavaBeans
225
When you click Finish, the SmartGuide will complete its work and the mapping
editor, shown in Figure 9-22, will appear.
The mapping editor
The mapping editor has two main parts. The top part shows the list of available
entity beans on the left and the list of available tables on the right. Both lists can
be expanded to show the fields and columns. Mappings between beans and
tables are managed in this part of the editor. Highlight an entity bean on the left
and a table on the right, and select Create Mapping from the context menu to
generate a new mapping.
Figure 9-22 The mapping editor
The bottom part of the mapping editor also shows entity beans on the left and
tables on the right. The difference is that this part of the editor is used to
manipulate mappings between container-managed fields and columns. When a
column is highlighted in this table, a drop-down box appears in the column field;
use this drop-down box to select a column for the highlighted field.
The Properties view will update based on the selection in the table. With a
container-managed field selected, the Properties view will permit you to select a
translator for the mapping. The translators permit values to be converted
between types. Consult the product documentation for more information about
the mapping editor.
226
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Tuning the database schema
Some tables do not import correctly. In particular, the import process makes
some assumptions about what Java types to assign to each field. The import
process does not determine the primary key fields in the imported table. A
warning may appear in the Tasks view as shown in Figure 9-23. In this case, the
schema will have to be changed.
Figure 9-23 The ever-present Task view lists errors and warnings
Switch to the Data perspective and then to the Data view (as shown in
Figure 9-24). Navigate in the Data view to the schema folder in your EJB project.
Expand the schema until you see your table. Double-click the table to open the
table editor.
In the table editor, change the column types as necessary. The import process
always treats fixed-point numeric values as BigDecimal. If the corresponding
field on the bean class is of type double, then the value should be changed to
double in the table schema as well.
Chapter 9. Enterprise JavaBeans
227
Figure 9-24 Use the Data view (part of the Data perspective) to specify the primary key
fields for the table schema
228
Migrating WebLogic Applications to WebSphere Advanced Edition V4
10
Chapter 10.
Database connectivity and
persistence
This chapter describes the different methods and technologies you could use in
WebLogic to access persistent data in a database and how these should be
migrated to WebSphere. It is beyond the scope of this book to cover all these
technologies in detail. We focus on the JDBC API, which is a core part within the
Java 2 Platform, Enterprise Edition. We also look at persistence products from
other vendors that you may encounter when migrating applications, and consider
the future direction of persistence solutions as detailed in the Enterprise
JavaBeans 2.0 specification.
© Copyright IBM Corp. 2002
229
10.1 Introduction
Object persistence is a major topic in every enterprise application and because
persistence efforts always take a lot of time, you will find many products and tools
that promise to raise productivity and lower maintenance costs. Many
approaches can be used for persistent data access, but we expect that not all
these approaches will be used in the future, as efforts to standardize functionality
become more successful. See the EJB 2.0 and JDBC 3.0 specifications from
Sun Microsystems for more details on proposed future directions.
The JDBC API has been established as the industry-standard interface for Java
applications to access databases. Nearly all leading database and middleware
vendors support JDBC technology. It is also a key technology in the J2EE
architecture and thus supported by both WebLogic and WebSphere application
servers.
JDBC has been widely accepted by the developer community, so you find many
applications based on the pure JDBC API. Both WebSphere as well as WebLogic
support the JDBC 2.0 standard, while JDBC 1.0 drivers still can be used. These
applications should not present any major migration difficulties.
There are many high-level technologies and frameworks based on JDBC, mainly
to provide a higher level of abstraction than JDBC does. The products
dbKona/htmlKona, which are shipped and supported by WebLogic, is such a
class library. It was provided with the intention to simplify JDBC programming, for
instance by automatically generating SQL with the consideration of
vendor-specific details. The new features of JDBC 2.0 have meant that most of
the previous dbKona/htmlKona benefits, such as caching, shared query results,
and better support for displaying results in table views, are now supplied by the
base JDBC API. We expect that most developers will use the core JDBC
features, and that the role of proprietary extensions will become less significant.
The market also offers many sophisticated persistence frameworks, which
provide complex mapping from objects to data stores, mostly relational
databases. Nearly all of them are built on top of the JDBC API, which guarantees
a high degree of platform and database vendor independence. These types of
products can be compared with what the Enterprise JavaBeans specification
says about entity beans, particularly about entity beans with container-managed
persistence (CMP). Entity beans support in EJB-compliant products has been
demanded only since the EJB 1.1 specification, so it is fairly new. The latest EJB
2.0 specification has many improvements for the CMP bean type.
230
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Given the limitations of the early EJB support for CMP, there are a lot of tools
available that offer persistency mapping for fine-grained objects. These tools are
far more comprehensive and typically provide more features than can be
supported with the current EJB 1.0/1.1 implementations. WebGain offers their
product TopLink for BEA WebLogic, which integrates the persistence product
TopLink into the BEA WebLogic Server. It is likely that you will encounter TopLink
when migrating WebLogic applications, since it is a successful tool with wide
acceptance. TopLink is used not only for fine-grained objects and for entity beans
with bean-managed persistence (BMP), but is also a sophisticated
implementation for CMP entity beans, with features beyond the EJB 1.1 standard
(WebGain’s TopLink for WebSphere provides equivalent functionality for
WebSphere Application Server).
10.2 JDBC
JDBC is an API that provides a uniform programming interface to access different
forms of tabular data, such as databases, spreadsheets, flat files and so on.
Because of the platform independence provided by Java, JDBC provides
platform-independent access to databases. JDBC makes use of the remote
object features in Java (RMI) and thus enables database location transparency.
You can also make use of techniques to make proprietary database issues
transparent.
Both application server products, WebSphere as well as WebLogic, support the
JDBC 2.0 API standard. Therefore, you should not have to use any specific
packages of the application server vendor, but only the standard interfaces
(java.sql.* and javax.sql.*). This makes code portable between the servers.
Both products have partnerships with several database vendors, and they ship
and support their JDBC drivers. Nevertheless it should still be possible to use
any JDBC 1.0/2.0-compliant driver from another vendor. We detail some
potential problems in this chapter.
Another field where the middleware has to cooperate with the JDBC API is in the
support for distributed transactions. The JDBC 2.0 Optional Package API also
defines standards here and provides for a two-phase commit (2PC) protocol. We
tested that 2PC worked correctly and in the same way in both servers.
Chapter 10. Database connectivity and persistence
231
10.3 DataSource
The DataSource specification and interfaces are part of the JDBC 2.0 Optional
Package API. A DataSource can be seen as a representation of a particular
DBMS or some other data source, such as a file. A DataSource is simply a
factory for JDBC connections.
The previous means (JDBC 1.0) to get a connection to the database was via the
JDBC DriverManager or in WebSphere also with the IBM Connection Manager
(for connection pooling). With that approach the particular driver and database
had to be hardcoded. At least some developers used properties files and a
generic way to introduce new JDBC drivers.
But now with the specification of DataSources, developers have a standard
abstract way of obtaining database connections by using just a logical name. The
physical settings for the JDBC driver are set and updated by an administrator.
This makes code more portable and uniform, and eases maintenance and
deployment of JDBC applications. Figure 10-1 illustrates the uses of a
DataSource to connect to a database.
JNDI Naming
Service
lookup( )
Application
jdbc/example DS
Data
Source
eN
ame
Serve
JDBC
Driver
ber Descr
um
ion
ipt
Port N
getConnection( )
r
Na
me
as
Datab
Database
Figure 10-1 Connecting to a DataSource
WebSphere and WebLogic both offer support for generic JDBC 2.0-compliant
DataSources. Through their administration tools it is possible to set up
DataSources and bind them to the JNDI naming service of the server.
232
Migrating WebLogic Applications to WebSphere Advanced Edition V4
In both servers it is still possible to run applications using the old approach via
the JDBC DriverManager (the Connection Manager is no longer supported in
WebSphere). But the preferred way of getting database connections is now a
DataSource. You are encouraged to use DataSources, since the DriverManager
and the ConnectionManager interfaces will be deprecated in the future.
According to the specification of the JDBC 2.0 Optional Package API,
implementations of javax.sql.DataSource may be provided by JDBC driver
vendors as part of their JDBC 2.0 products. WebLogic does not provide any
assistance in incorporating DataSource implementations from other vendors and
for binding them into the namespace. WebSphere provides specific DataSource
implementations from supported database vendors, including DB2, Oracle, and
Sybase. For other database vendors, WebSphere uses a generic DataSource
implementation similar to that used by WebLogic.
Generic DataSource implementations offer a way to utilize JDBC classes from
other vendors still at the Driver class level. This means that the application
administrator either has to integrate a foreign DataSource or needs to get a
foreign driver working with the generic DataSource. The application developer is
not impacted by the implementation of the DataSource and is able to write highly
portable code.
There are slight nuances in the implementations provided by WebLogic and
WebSphere that could force you to change the code when migrating from one
vendor to the other.
10.3.1 Binding a DataSource to a naming service
To create a DataSource object within WebLogic, you define it in the
weblogic.properties file. DataSources always point to a connection pool, which is
also defined in the properties file.
For example a DataSource named jdbc/EstoreDB would be defined by adding
the following line to the weblogic.properties file:
weblogic.jdbc.DataSource.weblogic.jdbc.EstoreDB=EstorePool
If your DataSource has to support Java Transaction Services (JTS), then you
must use a connection pool with a JDBC driver supporting JTS. The following
line would add a JTS enabled DataSource (TXDataSource) with the logical name
jdbc/EstoreDB_TX.
weblogic.jdbc.TXDataSource.weblogic.jdbc.EstoreDB_TX=EstorePool
Regarding the naming of DataSources, the JDBC 2.0 Optional Package API
specification from Sun Microsystems states the following:
Chapter 10. Database connectivity and persistence
233
“The JDBC 2.0 API specifies a simple policy for assigning JNDI names to
data sources. All JDBC data sources should be registered in the JDBC
naming subcontext of a JNDI namespace, or in one of its child subcontexts.
The parent of the JDBC subcontext is the root naming context.”
WebSphere Application Server, V 3.5.x takes the usage of the jdbc naming
subcontext as a rule. With that version of WebSphere, the administrator should
not use the jdbc or jdbc/ subcontext in the DataSource name, as WebSphere
already implicitly prepends this subcontext. With WebSphere Application Server,
Advanced Edition V4, the DataSource can be located anywhere in JNDI space
(and can be nested arbitrarily). No restrictions are placed on the name.
10.3.2 Connecting to a DataSource
The code samples in this section provide a short demonstration of code that will
run in WebLogic as well as in WebSphere.
In the class where you want to obtain the DataSource, import the following
packages:
import javax.sql.*;
import javax.naming.*;
To obtain a DataSource from the JNDI naming service, you first have to get the
root naming context as the InitialContext. From the root naming context, the
DataSource can be obtained. Example 10-1 shows how this is done in BEA
WebLogic Server.
Example 10-1 Obtaining the InitialContext in BEA WebLogic Server
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
env.put(Context.PROVIDER_URL,
"t3://myserver:7001");
Context context = new InitialContext(env);
DataSource dataSource = (DataSource) context.lookup("jdbc/EstoreDB");
...
Similar code, as shown in Example 10-2, is used to obtain the InitialContext and
DataSource in WebSphere Application Server.
Example 10-2 Obtaining the InitialContext in WebSphere Application Server
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,
"com.ibm.ejs.ns.jndi.CNInitialContextFactory");
env.put(Context.PROVIDER_URL,
234
Migrating WebLogic Applications to WebSphere Advanced Edition V4
"iiop://myserver:900");
Context context = new InitialContext(env);
DataSource dataSource = (DataSource) context.lookup("jdbc/EstoreDB");
...
As you can see, both products use different initial context factories. The URLs
are less product specific than configuration specific (in WebLogic you can still
use their t3 protocol, but now they support IIOP as well). The best practice is to
not hardcode those parameters, but get them from an external configurable
resource (an environment, a properties-file or another LDAP naming server).
The zero-argument constructor for InitialContext is preferred. With the
zero-argument constructor, the property values are obtained from system
properties (or in the lib/orb.properties file). These values are set automatically by
the application server (both BEA WebLogic Server and WebSphere Application
Server do this). If your client is a stand-alone (fat client) Java application, the
following system properties must be explicitly set.
java.naming.factory.initial =
com.ibm.websphere.naming.WsnInitialContextFactory
java.naming.provider.url = iiop://localhost:900
These values can be set using the -D option on the Java executable’s command
line.
Example 10-3 shows how the DataSource is obtained using the zero-argument
InitialContext constructor.
Example 10-3 DataSource with zero argument constructor for initial context
Context context = new InitialContext();
DataSource dataSource = (DataSource) context.lookup("jdbc/EstoreDB");
It s recommended that hardcoded strings not be used. Values, such as the name
of the DataSource, should be bound in the environment or another configuration
resource. Also, you should not use the name of the DataSource directly, but the
resource-ref indirection in the deployment descriptor of your J2EE component
(either the in war.xml or ejb-jar.xml file).
10.3.3 Connection pools
Connection pools provide a significant performance gain, since there is an
overhead in the process of permanently opening and releasing database
connections.
Chapter 10. Database connectivity and persistence
235
With the introduction of the DataSource interface, connection pooling has been
abstracted, since there is no difference in the code, whether the DataSource
object has just opened a single connection or whether an existing connection has
been assigned from a PooledDataSource. The pooling of DataSource
connections is driver independent. You should not need any server-specific
classes or packages any longer to access DataSource connections from a pool.
One thing you have to be sure to do in the code is to always call a close() on the
connection you obtain from DataSource.getConnection(), as soon as the
connection will not be needed any longer. In this way you do not really close the
connection, but rather return it to the pool and make it available for other
applications. Example 10-4 shows typical code used to manage access to
DataSources using a connection pool.
Example 10-4 Connection pools
Connection connection = null;
Statement statement = null
try {
connection = getDataSource().getConnection();
statement = connection.createStatement();
// execute query
// process results
} catch (SQLException e) {
// handle exception
} finally {
if (statement != null)
try {
statement.close();
} catch (SQLException e) {
// Do something with the exception
}
if (connection != null)
try {
connection.close();
} catch (SQLException e) {
// Do something with the exception
}
}
Closing JDBC connections has little to do with the migration process. However, it
is a widely accepted best practice to do so and a migration effort is an excellent
opportunity to ensure that it is being done correctly. Closing these resources
correctly can have a significant impact on system resource use and ultimately
performance.
236
Migrating WebLogic Applications to WebSphere Advanced Edition V4
10.3.4 Available drivers
WebSphere Application Server, Advanced Edition V4 supports the following
database systems:
򐂰
򐂰
򐂰
򐂰
򐂰
DB2
Informix
Oracle
SQL Server
Sybase
InstantDB is supplied as a solution for users who do not have database software
available for use as a configuration repository. It is not recommended for
application usage and does not support EJB CMP, or JTA. Periodically new
drivers may be added to the supported list. Please refer to the online product
documentation to see the most recent list and for exact details of the versions of
each database that are supported.
For WebSphere Application Server software prerequisites, go to:
http://www-3.ibm.com/software/webservers/appserv/doc/latest/prereq.html
This does not mean that you cannot use any JDBC 1.0/2.0-compliant drivers
supplied by other database vendors for use in Java Servlets or EJB BMP, but you
will have to evaluate and confirm the suitability of those drivers.
10.3.5 Migration issues when changing JDBC drivers or databases
The JDBC API provides a common programming interface for accessing different
databases. It can also be used for vendor-specific features (stored procedures,
utilizing metadata, specific data types, SQL dialects, and so on). In this case
changing the database or the driver would not be easy. Driver support for
advanced JDBC 2.0 scenarios, such as batch updates, CLOB/BLOB support,
scrollable ResultSets, programmatic changes through ResultSet, distributed
transactions, and so on, also varies from vendor to vendor.
The JDBC specification discourages use of the DriverManager in favor of
DataSources saying that the DriverManager, Driver, and DriverPropertyInfo are
legacy features of JDBC and that they may be deprecated in the future. In
previous versions of JDBC, the DriverManager's getConnection(url, property)
was the standard method of obtaining a connection, so developers are familiar
with this and often expect the same behavior from DataSource implementations.
Changing a JDBC driver and using its functionality should not have any particular
dependency on the application server but, because WebSphere does not
support the setting of driver-specific properties where the driver is not compliant,
and only certain drivers are allowed for Entity CMP, this could mean that a driver
Chapter 10. Database connectivity and persistence
237
used in a WebLogic application cannot be used in WebSphere. If the driver you
use in WebLogic cannot work with generic settings and thus cannot be integrated
into the WebSphere environment, you may have to check whether your database
code will be a major migration issue.
Should you encounter this situation during your migration, we recommend that
you give careful consideration to your options before migrating to a different
driver or database. It is possible that the driver-specific properties used in your
WebLogic application are not crucial to the application functionality and that
using the generic driver support provided in WebSphere may perform acceptably.
However, it is possible that you will have to use a different JDBC driver or
consider migrating to a different database system. We expect this issue to
decline in importance over time, as JDBC driver vendors move toward providing
the standard way to get and set properties. The JDBC 2.0 Standard Extensions
Specification says that the only property that is required on a DataSource is the
description. The specification defines other standard properties that must use the
defined names. All standard and vendor- specific properties must provide get
and set methods and the use of getter and setter methods is the standard way of
handling properties for DataSources. Once JDBC driver vendors move to this
standard, we expect that migration between vendors will become an easier task.
10.3.6 Summary: Writing portable JDBC applications
The following recommendations will help you to write portable JDBC applications
that can be used across application servers and databases:
򐂰 Use the zero-argument InitialContext constructor (set System property values
if necessary). See 10.3.2, “Connecting to a DataSource” on page 234.
򐂰 Use DataSources to obtain connections.
򐂰 Do not hardcode the JNDI name of your DataSource; get it from the
environment or a configuration file.
򐂰 Avoid database-specific, vendor-specific JDBC extensions and optional JDBC
features (such as scrollable ResultSets).
򐂰 Do not be dependent on a particular vendor-supplied default transaction
isolation level and avoid user control of the same with
setTransactionIsolation().
Sources of differences between databases and JDBC drivers are:
򐂰 The actual data types offered.
򐂰 The details of the SQL commands, syntax, and operations.
򐂰 The availability of DBMS-related services such as batch processing.
238
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 DababaseMetaData and ResultSetMetaData: avoid dependencies on
vendor-specific information except where your code also supports a
completely portable solution.
򐂰 Stored procedure support and syntax are generally vendor-specific; if used,
process ResultSets before OUT parameters.
򐂰 Multiple ResultSets and vendor-specific batch support -- avoid using.
򐂰 SQLException and SQLWarning attributes are generally vendor-specific -use data only for presentation.
򐂰 Support for updatable ResultSet is optional (CONCUR_UPDATABLE).
Although this avoids the explicit SQL problem, it is still vendor-specific.
RowSet is a more portable solution.
򐂰 Support for JDBC 2.0 batch update feature (addBatch(), executeBatch()) is
optional. This is better than a vendor-specific batch processing language, but
it may still be non-portable.
򐂰 RowSet may have optional URL and database name parameters. Use
DataSource options instead.
10.4 jDriver (jdbcKona)
jDriver (formerly jdbcKona) is a collection of native JDBC drivers for Oracle,
Sybase, Informix, and Microsoft SQL Server. These drivers provide a number of
extensions to the vendor’s original JDBC driver. For example, the
jdbcKona/Oracle driver provides an extension for creating and using Oracle
sequences. jdbcKona seems to be part of BEA WebLogic Server V4.5 and has
been replaced by jDriver, a collection of WebLogic JDBC drivers, in V5.1.
jDriver drivers are two-tier and multi-tier drivers that depend on client-side
middleware to function. WebLogic has no single packaged JAR-file for their
drivers, which could then be taken over to a different application server. You
would need to filter out all class and interface types from the WebLogic core
classes that are needed by the driver and package it on your own. But it is
doubtful whether this is a good and valid solution.
A discussion of available drivers for WebSphere can be found in 10.3.4,
“Available drivers” on page 237.
For more information on the BEA WebLogic jDriver family, see:
http://www.beasys.com/products/weblogic/drivers.shtml
For details on using the jdbcKona family of JDBC drivers, see:
http://www.weblogic.com/docs/classdocs/API_joci.html
Chapter 10. Database connectivity and persistence
239
10.5 dbKona
dbKona is a WebLogic tool that provides a higher-level mechanism for accessing
JDBC databases. Much as with htmlKona, applications developed using dbKona
will likely require considerable effort to migrate.
A dbKona code example is shown in Figure 10-5. The connection (conn) is
created using the standard JDBC 1.0 API. It is unclear if dbKona supports a
connection obtained from a DataSource.
Example 10-5 A dbKona example
...
ts1 = new TableDataSet(conn, "emp");
for (int i = 0; i < 100; i++) {
Record rec = ts1.addRecord();
rec.setValue("empno", i)
.setValue("ename", "Person " + i)
.setValue("deptno", i);
}
// Save new records. dbKona does selective saves, that is,
// it saves only those records in the TableDataSet.
System.out.println("Inserting " + ts1.size() + " records.");
ts1.save();
// Define a KeyDef for updates and deletes.
KeyDef key = new KeyDef().addAttrib("empno");
// Update the 100 records that we originally added.
ts2 = new TableDataSet(conn, "emp", key);
ts2.where("empno < 100");
ts2.fetchRecords();
for (int i = 0; i < ts2.size(); i++) {
Record rec = ts2.getRecord(i);
rec.setValue("ename", "Worker " + i);
}
ts2.save();
...
The full example can be found at
http://www.weblogic.com/docs/examples/dbkona/db2examples.html. The KeyDef
mentioned in the example is the primary key of the table. The primary key must
be known in order to do updates.
240
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Unfortunately, dbKona is likely to cause problems during a migration. One
problem with tools such as dbKona is that developers tend to forget about such
things as application layering. That is, it is very likely that dbKona code will be
found directly in the servlet code. As part of the migration effort, a distinct data
layer should be introduced.
dbKona provides a higher-level abstraction of JDBC, but in this example we see
that dbKona is marginally higher-level than using the standard JDBC
PreparedStatements. The use of JDBC 2.0 RowSets would provide a more
standard alternative to much of the dbKona functionality.
A considerable amount of work must be done to convert existing dbKona source
into standard JDBC 2.0, but this is the recommended and portable way.
Unfortunately, this will be a largely mechanical effort, since we are not aware of
tools to automate the process.
For the most-part, dbKona calls can be converted directly into JDBC calls.
As with htmlKona, there also is no technical reason why the dbKona code cannot
be used without modification in WebSphere. However, it is unclear whether
dbKona classes licensed from BEA WebLogic Server can be legally used in
WebSphere, or if dbKona can be licensed separately from BEA WebLogic
Server.
For an overview of dbKona architecture see:
http://www.weblogic.com/docs/techoverview/db.html
10.6 Business objects - persistence frameworks
In Java 2 Platform, Enterprise Edition the EJB specification is beginning to
provide a business object standard, but there is still much that remains to be
done. The Java Data Objects (JDO) specification attempts to provide a
persistence solution, but has not gained popular acceptance. EJB 2.0, with
support for local beans with container-managed persistence holds a lot of
promise as a persistence solution for fine-grained entity beans.
The solution for fine-grained business objects considered by the EJB 1.1
specification are so-called dependent objects, which should not be implemented
as entity beans. Instead, a dependent object is better implemented as a Java
class (or several classes) and included with the entity bean on which it depends.
Version 1.1 of the specification does not attempt to standardize the notion of
dependent objects or how they are persisted. It is left to the vendor and
application programmer to develop proprietary solutions.
Chapter 10. Database connectivity and persistence
241
Regarding entity beans, the EJB 1.1 specification left many things open to the
server provider. This has resulted in some non-portable code. The EJB 2.0
specification deals with many of these issues and makes some major steps
towards standardization of entity beans. The revised entity bean specification
includes support for container-managed relationships between entity beans and
a notion of local (non-remote) beans. It provides a foundation for pluggable
persistence managers and specifies a portable finder query syntax called
EJB-QL. Furthermore, it enables support for more efficient vendor
implementations by leveraging lazy loading, dirty detection, and memory
footprint reduction.
10.6.1 Container-managed persistence (CMP) entity beans
The coding for CMP entity beans is much simpler than for BMP (bean-managed
persistence), because most of the work is being done by the container. CMP
entity beans should perform better than BMPs because the container has a lot of
possibilities to optimize performance issues.
Entity beans as such are the most puzzling for migration issues, because they
still have a heavy dependency on server proprietary solutions.
WebLogic offers two CMP persistence solutions:
򐂰 The BEA WebLogic Server RDBMS Persistence for trivial entity bean
applications
򐂰 TopLink for WebLogic
The BEA WebLogic Server persistence mechanism and the implications for its
use with respect to migration is discussed in depth in Chapter 9, “Enterprise
JavaBeans” on page 195.
TopLink for WebLogic, sold by WebGain as an add-on to BEA WebLogic Server,
is a popular EJB container that is widely used in WebLogic applications. A
TopLink for WebSphere exists for WebSphere Application Server V3.5, and
should soon be available for V4. TopLink code generally requires little change as
part of a migration. Refer to 10.6.3, “TopLink” on page 243 for more information
about migration issues involved with that product.
WebSphere already supports associations and inheritance for EJBs. There is a
current restriction that EJBs must use the DataSources from DB2, Oracle, or
Sybase. Other databases cannot be used for CMP entity beans.
242
Migrating WebLogic Applications to WebSphere Advanced Edition V4
10.6.2 Bean-managed persistence (BMP) entity beans
As the name implies, BMP entity beans have to manage their persistent data on
their own. This can be done either by using direct JDBC, a persistence mapping
tool, or even a legacy application.
The persistence approach in the BMP may be an issue for portability or
migration. If the BMP persistence uses JDBC, you have to consider the points
mentioned earlier in this chapter. If you use other products or applications,
migration issues or incompatibilities will be vendor and product specific.
10.6.3 TopLink
TopLink for Java is a persistence framework that maps objects to relational
databases. TopLink has a significant install base and, as such, may be part of a
migration effort. The base product, TopLink for Java, is written in Java and is
therefore completely platform independent. Applications written using the
foundation product should migrate with relative ease from one application server
to the next.
TopLink for WebLogic is a container designed specifically to provide persistence
mapping for BEA WebLogic Server. Some parts of BEA WebLogic Server have,
in fact, been influenced by the TopLink implementation. TopLink for WebLogic is
BEA's preferred container-managed persistence solution. They do have an
alternative (BEA WebLogic Server RDBMS Persistence), but BEA's own sales
force aggressively markets (and frequently sells) TopLink. The point is that where
there are CMP EJBs with WebLogic, TopLink is probably being used.
TopLink for WebSphere provides the same basic functionality as TopLink for
WebLogic and from the application developer’s point-of-view, very little change is
required. The WebLogic version of the product automatically generates primary
keys for entity beans upon creation using a sequence table. Due to a timing issue
with the WebSphere container, TopLink cannot automatically generate keys for
WebSphere. The application developer must modify their ejbCreate(...) methods
to include a single line of code to generate sequence numbers:
TOPLink.Public.EJB.SessionManager.getManager().getSession("TLWSEmployeeDemo
").getActiveUnitOfWork().assignSequenceNumber(this);
This is ugly code, but it is only one small change. Unfortunately it is very
non-standard. TopLink does force a number of other non-standard things into
your beans, especially if you want to take advantage of more advanced features
such as deferred loading of contained objects.
Chapter 10. Database connectivity and persistence
243
Migration strategy
For TopLink for Java, there are no major issues. The migration should be
relatively simple. For TopLink for WebLogic, migration should still be a relatively
simple matter of mechanically making changes to the code.
10.6.4 Other persistence managers
Besides TopLink, there are also other persistence manager products on the
market that provide support for both servers. These include Thought Inc.’s
CocoBase and Versant’s Object Container (OO database). We did not examine
the migration issues that might arise from using these tools.
244
Migrating WebLogic Applications to WebSphere Advanced Edition V4
11
Chapter 11.
Application assembly and
deployment
Previous chapters discussed migration issues related to the component creation
and partially about assembly and deployment. This chapter is completely
dedicated to migration issues related to application assembly and deployment.
© Copyright IBM Corp. 2002
245
11.1 Introduction
A J2EE application undergoes a development cycle of:
Component Creation -> Assembly -> Deployment
The Java 2 Platform, Enterprise Edition(J2EE) specification provides a standard
for J2EE application assembly and deployment. A J2EE application is composed
of one or more J2EE modules and one J2EE application deployment descriptor.
A J2EE module consists of one or more J2EE components of the same container
type and one module level deployment descriptor. A J2EE module can be
deployed alone or as a part of J2EE application. A J2EE application can be
packaged into an Enterprise Application Archive (EAR) file. A J2EE package
may also include libraries referenced by J2EE modules, help files
documentation, and so on.
Deployment descriptors are a contract between the developer and application
assembler, and between the application assembler and deployer. The developer
or the module producer is responsible for providing structural information about
the module including the list of referenced external resources and the
environment variables. The application assembler is responsible for adding
information that describes how the module fits into the large application
deployment unit. The deployer is responsible for resolving any external resource
references, assigning JNDI names to the components and assigning appropriate
values to environment variables. It is possible that a single person may take
more than one role, but it is good to distinguish the responsibilities.
The J2EE application deployment descriptor contains information in XML form
whose grammar is defined by the J2EE application document type definition
(DTD). An application descriptor must contain the following DOCTYPE
declaration:
<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application
1.2//EN' 'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>
Figure 11-1 shows the structure of the application_1_2.dtd.
246
Migrating WebLogic Applications to WebSphere Advanced Edition V4
application
icon?
small-icon?
display-name
module+
description?
ejb | java | web
large-icon?
web-uri
alt-dd?
security-role*
description?
role-name
context-root
Figure 11-1 J2EE application descriptor DTD
The application descriptor is stored in the application.xml file. As shown in
Figure 11-1, the J2EE specification V1.2 specifies three different types of
modules:
򐂰 EJB module
򐂰 Web module
򐂰 Java application client module
Each of these modules has its own XML deployment descriptor. Table 11-1 lists
the names of XML deployment descriptor files.
Table 11-1 J2EE deployment descriptors
Module type
Descriptor file name
EJB
ejb-jar.xml
Web application
web.xml
Client application
application-client.xml
Each of these XML deployment descriptors is defined by a DTD, and the
descriptor should contain a corresponding DOCTYPE declaration as follows:
򐂰 ejb-jar.xml
<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise
JavaBeans 1.1//EN' 'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>
򐂰 web.xml
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
򐂰 client-applicatication.xml
Chapter 11. Application assembly and deployment
247
<!DOCTYPE application-client PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE
Application Client 1.2//EN"
"http://java.sun.com/j2ee/dtds/application-client_1_2.dtd">
Note: These DOCTYPE declarations correspond to J2EE specification V1.2.
They have changed in V1.3 of the J2EE specification. Also, a new connector
module has been introduced.
These deployment descriptors contain platform-independent information
required to deploy components in the module. More information required for
deploying these components on different J2EE platforms is available in the
separate platform-specific files. Table 11-2 lists the platform-specific files for
WebLogic and WebSphere.
Table 11-2 Platform-specific descriptors
Module Type
WebLogic
WebSphere
EJB
weblogic-ejb-jar.xml
ibm-ejb-jar-bnd.xmi
ibm-ejb-jar-ext.xmi
ibm-ejb-access-bean.xmi
Map.mapxmi
Schema.dbxmi
Web application
weblogic.xml
ibm-web-bnd.xmi
ibm-web-ext.xmi
Client application
client-application-runtime.
xml
ibm-application-client-bnd.
xmi
WebSphere also has application-level platform-specific descriptors:
򐂰 ibm-application-bnd.xmi
򐂰 ibm-application-ext.xmi
11.2 Application assembly
J2EE does not specify how to assemble the EAR file. It does not specify what
must be packaged. It specifies what can be packaged and there are no basic
requirements on minimum content of a packaged application (EAR file).
As explained in the introduction, a J2EE application consists of different modules
and an application-level deployment descriptor. Although there is no standard for
how to package the EAR, over time developers have developed some best
practices.
We recommend that you structure the application as shown in Figure 11-2.
248
Migrating WebLogic Applications to WebSphere Advanced Edition V4
-
-
-
Application
META-INF
application.xml
EJBModuleN
META-INF
Manifest.mf
ejb-jar.xml
WebModuleN
META-INF
Manifest.mf
WEF-INF
web.xml
classes
lib
ClientModuleN
META-INF
Manifest.mf
application-client.xml
Deployment
Descriptors
Figure 11-2 Staging directories
This structure is known as a staging directory structure. This structure helps you
understand the separation between modules and their interdependencies. The
above structure also shows the directories that hold deployment descriptors for
individual module. Deployment descriptors for EJBs and client applications are
stored under a META-INF directory whereas those for Web modules are stored
under WEB-INF. The META-INF file also holds a manifest file that stores such
information as classpath, and so on.
If your IDE supports the concept of modules, then as a developer you are
relieved from the concern of staging directories. WebSphere Studio Application
Developer is one such IDE that works on the concept of modules and you can
export a module as a JAR or as a part of an EAR.
Although it is good to work on the staging directory structure during development,
it is hard to distribute the application in this structure and keep all the
components synchronized. It is better to create JAR files for individual modules
and then package them together in an EAR along with an application descriptor.
Then the resultant structure would look like Example 11-1.
Chapter 11. Application assembly and deployment
249
Example 11-1 Recommended packaged structure
Application
META-INF
application.xml
EJBModuleN.jar
WebModuleN.war
ClientModuleN.war
JAR files are convenient for packaging components and applications for
distributions. They make it easy to share the components between two
applications. The jar utility is a standard utility shipped with the Java
Development Kit (JDK). Using this utility, you can create a new JAR file, extract
the contents, or list the contents of the existing JAR file. For more information
see the command-line help or documentation for JDK utilities.
Application servers can read the deployment descriptor bundled in the JARs and
deploy the application and modules appropriately. When modules are dependent
on other modules for them to work correctly, it is required that they are loaded in
appropriate order by the classloaders of the application server. To help the
classloader solve this problem, you can take two approaches. Either bundle the
required classes in the same module or set up the appropriate classpath in the
manifest file. With the first approach, the same class is copied to more than one
place. Sometimes this can become confusing, and it is hard to debug the
problems if the versions at different places are out of synch. Hence it is best to
set up the classpath information in the manifest files and keep it up to date. The
same thing is true for common code. It is best to package the common code in an
independent JAR and then add it in the classpath of the modules that need it.
In almost all the projects, some kind of version control system is used to version
the source code and resources. Even though all the code and resources are
managed in a version control system, when the EAR file is created there is no
explicit link to the source it was derived from. There are many ways to solve
these problems such as adding an extra information file or adding version
information in the manifest file. The alternative chosen for a particular EAR file
will usually depend on the policy of your organization. We have seen that even if
there are strict rules in place about how to keep information about versions in the
EAR file, it is still common for the information to be lost or out of synch. This
causes many problems during maintenance, so it is good practice to bundle .java
files inside the EAR file. This provides an easy way of identifying the class
versions. This helps not only in debugging the application but also provides a
reliable backup for the source code.
250
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Putting source code in the EAR file does not cause any problems for the
application servers. It takes slightly longer to create the EAR file with source
code and the size is bigger, but it is worth the effort. Moreover, packaging tasks
are mostly done by utilities, such as Ant, where no human intervention is
required. Hence, you can run these scripts every night without consuming
development time. You can also deploy EAR files created by the Ant script
automatically on the development servers and do any unit testing required.
11.2.1 Packaging components
The first step towards packaging an application is to package the individual
components. When the component is produced by developers, they provide
structural information about the component. Part of this information is provided in
the form of deployment descriptors. For example when an EJB component is
created by a developer, they provide an ejb-jar.xml that contains such
information as EJB name, Home interface, Remote interface, references to other
EJBs, and resources. Although the information is not sufficient to deploy the
component it is a good starting point for the application assembler and deployer.
Developers may write the deployment descriptor manually or can generate it
using tools provided by the application server.
We recommend that you use tools provided by the individual platform vendor or
XML validating editors to edit these files rather than use a simple text editor to
write deployment descriptors.
WebLogic provides Java-based utilities to automatically generate deployment
descriptors.These include:
򐂰 weblogic.ant.taskdefs.war.DDInit, for creating web.xml and weblogic.xml
򐂰 weblogic.ant.taskdefs.ejb.DDInit, for creating ejb-jar.xml, weblogic-ejb-jar.xml
and weblogic-cmp-rdbms-jar.xml as per EJB 1.1 specifications
򐂰 weblogic.ant.taskdefs.ejb20.DDInit, for creating ejb-jar.xml,
weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml as per EJB 2.0
specifications
You may have to edit these deployment descriptors before deploying the
application. You can download an XML editor from the BEA site or you can use
your favorite XML editor to edit these files.
Chapter 11. Application assembly and deployment
251
Note: weblogic.ant.taskdefs.ejb20.DDInit does not generate such elements as
cmp-field and prim-key. You have to write them yourself. Also, the generated
web.xml has a DOCTYPE where the URL points to web-app_2_2.dtd, but
actually it creates the XML compliant to 2.3. One such example is
<display-name> under <security-constraint>. This element needs to be
removed to make the XML valid.
WebSphere provides more than one tool to generate and edit the deployment
descriptors. If you are using WebSphere Studio Application Developer as an IDE,
deployment descriptors are created as soon as the project is created. You can
update the descriptors using various editors provided by WebSphere Studio
Application Developer. For example, you would use the EJB editor to update the
deployment descriptor for an EJB module, or you would use Web.xml editor to
edit deployment descriptor for a Web module. If the application assembler
decides to use the WebSphere Studio Application Developer as an assembly
tool, then he can use other editors, such as the EJB Extension editor, in addition
to the above editors.
And finally WebSphere Studio Application Developer can be used to export the
JAR for the component. Most of the time, the developer would write the assembly
and deployment information for the component to test it in the WebSphere test
environment provided inside WebSphere Studio Application Developer. In that
case, the application assembler can edit this information to suit the final
deployment environment.
WebSphere Application Server includes an Application Assembly Tool (AAT) as a
part of the installation. AAT provides a GUI that simplifies the task of creating and
assembling modules and editing the deployment descriptors. You can also
manage the WebSphere-specific binding and extension files. Chapter 4,
“Development and migration tools” on page 67 provides details on how to use
AAT and also describes how to use the EJB Deployment tool.
Once you have updated the deployment descriptors, the next task is to package
them in the JAR file. You first have to create the staging directory structure as
shown in Figure 11-2 on page 249 and distribute the deployment descriptors to
the appropriate directories. Then you can use the jar utility provided with the JDK
to create the JAR file.
If you are using WebSphere Studio Application Developer, you can create the
JAR file by choosing the export menu option.
252
Migrating WebLogic Applications to WebSphere Advanced Edition V4
You can also use Ant to do the packaging. You can write Ant scripts to create the
staging directory structure and then package the components into the JAR or
WAR. To gain a better understanding of the standard features available with Ant
consult the Ant documentation that is available on the Web at
http://jakarta.apache.org/ant/index.html and in the Ant distribution. If the
standard features do not suit your purposes, remember that Ant provides a
mechanism for you to implement your own tasks in Java. We used Ant in the
banking example for packaging individual components and the application itself.
WebSphere requires an attribute ID for the tags in the ejb-jar.xml and web.xml
files for which there is binding specified.This ID is used for cross-reference.
WebLogic doesn’t need a special ID. Hence when you are migrating from
WebLogic, you need to create these IDs. You can use the was40utils utility to
create these ID attributes. For information about how to use this utility, refer to
“The was40utils conversion tool” on page 164.
In general, a developer or a team of developers will deliver one or more EJBs and
will also provide the corresponding ejb-jar.xml. The application assembler is
allowed to package those EJBs separately or together with other EJBs delivered
by other developers. It is the application assembler’s responsibility to make sure
that the resultant ejb-jar.xml files are well-formed and conform to standards
found at: http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd
In the case of a Web module, an application assembler is responsible for writing
a consolidated web.xml file. He/she will get JSPs, servlets and other resources
from an individual developer or a team of developers along with web.xml files
specifying the servlet name, class name, environment entries, EJB and other
resource references. The application assembler can combine these resources
and the corresponding web.xml, and will also have to let developers know about
the URL patterns used for servlets and JSPs.
If the JSPs used tag libraries, the application assembler should assemble the
required tag libraries in the Web module and update the taglib-uri element in
web.xml. There is no specification for how the tag libraries should be packaged in
the Web module. Normally they are put under the /WEB-INF/ folder. WebSphere
Studio Application Developer suggests that you store tag libraries at
/WEB-INF/tlds/. Hence, if you are going to use WebSphere Studio Application
Developer for future maintenance and enhancement of the application, you can
move the tag libraries to /WEB-INF/tlds/.
As per, http://java.sun.com/j2ee/dtds/web-app_2_2.dtd, the element
<jsp-file> should contain the full path to a JSP file within the Web application.
WebLogic is lenient about this requirement and will work even if the leading / is
missing in the <jsp-file> element, but WebSphere Studio Application Developer
requires the full absolute path, which means a leading / has to be added to the
value of the <jsp-file> tag.
Chapter 11. Application assembly and deployment
253
For more information about packaging J2EE application components for
WebLogic refer to:
http://e-docs.bea.com/wls/docs61/programming/packaging.html
Refer to Chapter 4, “Development and migration tools” on page 67 for
information about WebSphere Studio Application Developer and AAT.
11.2.2 Packaging an application
Once you have packaged individual modules to JAR or WAR, you will have a
structure similar to that shown in Figure 11-2 on page 249. The only thing
missing will be an application.xml.
WebLogic provides the following Java base utility to automatically generate an
application.xml:
weblogic.ant.taskdefs.ear.DDInit
For Web modules, the element context-root will have a value equal to the name
of the WAR file without an extension. You may want to update this before
packaging the application.
If you are using WebSphere Studio Application Developer, change the context
root of a Web module by selecting J2EE View from the J2EE Perspective,
selecting the Web project, right-clicking and choosing Properties. Update the
context root in the Web settings. Changing the context root here will
automatically update the context-root element in the application.xml. Instead, if
you try updating the application.xml directly using the XML Editor (the EJB editor
has this field disabled), WebSphere Studio Application Developer will complain
about a mismatched context root. Alternatively, you can also open the
websettings file from the corresponding Web project and update context root
there. But this does not update the application.xml and you will have to manually
update it.
Since WebLogic supports deployment of the application in the exploded format, it
is a common practice to test the application in the exploded form before
packaging into the EAR file. For more information about assembling and
configuring Web applications in WebLogic, see
http://e-docs.bea.com/wls/docs61/webapp/index.html.
WebSphere Application Server does not support deploying applications in the
exploded format. It is not necessary to separately test an expanded version of
the application for WebSphere because the application can very well be tested in
the WebSphere Test Environment provided with WebSphere Studio Application
Developer. See 4.1.3, “Setup test server” on page 88 for more details on how to
254
Migrating WebLogic Applications to WebSphere Advanced Edition V4
set up the test environment and test an application in WebSphere Studio
Application Developer. See 12.4.8, “Testing application” on page 313 for a
specific example of testing an application using WebSphere Studio Application
Developer.
Once the application.xml is written, you can create the EAR file for the
application using the jar utility from the JDK. If you are using WebSphere Studio
Application Developer, it will export the application in the format of EAR.
AAT supports opening existing application packages or creating new
applications. You can add and remove components from the application. AAT
adds the appropriate module element to the application.xml file for each newly
added module and removes the existing module element from the
application.xml file when a module is removed. You can update the context root
of any Web modules, change icons, and update deployment descriptors of the
modules. Once you are done, you can export the modified EAR.
11.3 Deployment
Assembly of the components or application produces deployable JAR, WAR or
EAR files. These files contain deployment descriptors originally written by
developers and possibly updated by the application assembler. The deployer’s
task is to update these descriptors and generate deployment code and run it on
the server. Generation of deployment code includes creating stubs and ties
specific to J2EE platform for EJBs and RMI classes.
In WebLogic, stubs and ties can be generated by running the following
commands:
1. For RMI classes:
java weblogic.rmic [options] <classes>.
2. For EJBs:
java weblogic.ejbc [options] <source jar file> <target directory or jar>
You should add these generated stubs and ties to the existing JAR. If you do not
generate the stubs and ties, WebLogic will automatically do it for you at runtime.
In WebSphere, you can generate stubs and ties for EJBs using WebSphere
Studio Application Developer, EJBDeploy or AAT. While deploying an EJB
module or an application on WebSphere, the server will automatically generate
stubs and ties if they are not already generated. If they are already generated, it
will give you an option to regenerate them.
Chapter 11. Application assembly and deployment
255
Generating stubs and ties for RMI classes for WebSphere is a more difficult task.
There is no easy way to generate stubs and ties for RMI classes. You have to do
it by running the following command at the command prompt:
rmic -iiop -keep [other options] <classes>
where the -keep option is used if you want to import the Java classes into
WebSphere Studio Application Developer.
For more information about using AAT, and the EJBDeploy tool, see the redbook
WebSphere Version 4 Application Development Handbook, SG24-6134.
In WebLogic, you can write startup and shutdown classes to do initialization and
cleanup. For example, in the original banking sample, RMILoggerImpl was
registered as a startup class so that it could bind an instance in the RMI registry,
which was later looked up by the BankAppServlet.
WebSphere does not have support for startup and shutdown classes. One
solution to this is to write a servlet with the init method that would invoke these
startup classes. In the deployment descriptor, this servlet descriptor should have
the <load-on-startup> element with the smallest positive integer, and all other
servlet descriptors should have higher integer values. This solution will help as
long as only servlets and JSPs are dependent on the startup class.
WebLogic allows specifying a DataSource or connection pool name for mapping
of CMP entity beans. But WebSphere allows the use of the DataSource only.
When an individual EJB module or Web module is deployed on the WebLogic
server, that module appears under corresponding (EJB or Web applications)
category under deployment. When the same module is deployed on WebSphere
Application Server, a default enterprise application is created for you and the
module is deployed as part of it.
The wartowebapp script allows you to convert WAR files to Web applications, so
that you can run the Web applications on a servlet engine inside the
development runtime environment (such as VisualAge for Java). For more details
see:
http://ibm.com/software/webservers/appserv/doc/v35/ae/infocenter/was/04
0210.html
4.2.2, “EJBDeploy” on page 105 also describes how to use the EJBDeploy tool.
EJBDeploy is used by WebSphere Application Server to generate deployed code
for EJBs. But you can also use this as a command-line utility to generate
deployed code. The advantage of generating deployed code beforehand is that
256
Migrating WebLogic Applications to WebSphere Advanced Edition V4
you have to do it only once. Instead, if you deploy the EJBs on many servers,
each server will generate the code. This is just a matter of saving some time and
is optional. The EJBDeploy utility also performs other functions, such as
generating top-down mappings for CMP beans, which can then be customized.
11.4 Migrating deployment descriptors
This section covers the important differences in the platform-specific deployment
descriptors of WebLogic server and WebSphere Application Server. We provide
a guide for mapping WebLogic deployment descriptors to WebSphere. We have
listed which element/attribute goes into which field in AAT. Most of the fields are
named similarly in WebSphere Studio Application Developer. Extension tabs in
AAT map to various extension editors in WebSphere Studio Application
Developer and binding tabs in AAT map to the bindings tabs in WebSphere
Studio Application Developer.
11.4.1 Application deployment descriptors
The main application.xml file is the same for WebLogic and WebSphere. In
addition to the application.xml file, WebSphere also uses the
ibm-application-ext.xmi file, which includes information about security role
mapping. According to the J2EE specification, roles are defined in each module
and it is the container’s responsibility to provide a mapping tool to map these
roles. In WebLogic, role mapping for a module is provided in a module-specific
extension file. For example, module mapping for a Web module is in
weblogic.xml, and that for an EJB module will be in the weblogic-ejb-jar.xml file.
In WebSphere, that mapping is provided in a central place at the application
level, in the ibm-application-bnd.xmi file. Figure 11-3 shows the AAT tool with the
Security Roles node selected. For more information about security, see
Chapter 5, “Security” on page 111.
Chapter 11. Application assembly and deployment
257
Figure 11-3 Mapping security roles using AAT
11.4.2 EJB deployment descriptors
Figure 11-4 shows AAT with the EJB modules node expanded, to show the
deployment descriptor mappings.
258
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 11-4 Layout of EJB modules in AAT
Table 11-3 shows how the information from weblogic-ejb-jar.xml is mapped to
ibm-ejb-jar-ext.xmi and ibm-ejb-jar-bnd.xmi. WebSphere Application Server
allows you to specify only a handful of things and most of the attributes from
weblogic-ejb-jar.xml cannot be preserved.
Table 11-3 Migrating weblogic-ejb-jar.xml
Element/Attribute name
Location in AAT or WebSphere
Administration Console
entity-descriptor,
stateless-session-descriptor,
stateful-session-descriptor
See sub-elements below.
pool, max-beans-in-free-pool and
initial-beans-in-free-pool
These attributes allow you to specify how
many instances of each EJB should be
created at the startup and the maximum
number of instances in the free pool.
WebSphere does not support such granularity,
but you can specify the cache size and cache
cleanup interval in the EJB Container Service,
which is found on the Services tab for the
server node in WebSphere Administration
Console.
entity-clustering, stateless-clustering,
stateful-session-clustering
No support for tuning this.
Chapter 11. Application assembly and deployment
259
Element/Attribute name
Location in AAT or WebSphere
Administration Console
entity-cache, stateful-session-cache
No support for tuning this.
persistence
(is-modified-method-name,
delay-updates-until-end-of-tx,
finders-load-bean,
is-modified-method-name,
db-is-shared)
No support for tuning this.
persistence-type and persistence-use
These elements are not mapped. These
elements contain WebLogic-specific
type-identifier and type-version.
lifecycle, passivation-strategy
See Bean Cache option in IBM Extension tab
for the EJB in AAT.
transaction-descriptor
(trans-timeout-seconds)
You cannot specify this value for the entity
bean. It is defaulted to 600 seconds for the
session bean.
reference-descriptor
(resource-description,
ejb-reference-description)
You can specify these under the Resource
References and EJB References node in the
WebSphere Administration Console.
jndi-name
This can be specified on the Bindings tab for
the EJB in AAT.
enable-call-by-reference
This is not supported by WebSphere.
security-role-assignment
Select the Security Roles node under the
Application node and open the Bindings tab in
the WebSphere Administration Console.
run-as-identity-principal
Not supported in WebSphere.
transaction-isolation
This can be specified in the Container
Transaction node under the EJB module.
persistent-store-dir
See the EJB Container Service in the Services
tab for the server node in WebSphere
Administration Console.
The followings tags and their children from weblogic-ejb-jar.xml can be ignored
for now, because they are for EJB 2.0:
򐂰 invalidation-target
򐂰 message-driven-descriptor
򐂰 resource-env-description
260
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 ejb-local-reference-description
򐂰 local-jndi-name
Table 11-4 shows how the information from weblogic-cmp-rdbms-jar.xml is
mapped to ibm-ejb-jar-ext.xmi and ibm-ejb-jar-bnd.xmi. This is best mapped
using WebSphere Studio Application Developer.
Table 11-4 Migrating weblogic-cmp-rdbms-jar.xml
Element/Attribute name
Location in WSAD
pool-name | data-source-name
In WebSphere, you can only specify the
DataSource and not the pool name. DataSource
can be specified in the Bindings tab of EJB
Extension Editor. WebSphere allows you to
specify the default DataSource for all the EJBs in
the module with the capability of overriding the
setting per EJB.
field-map
This is specified in the mapping editor.
finder
Finder tab in EJB Extension Editor.
create-default-dbms-tables
This facility is not available in WebSphere, but you
can always generate DDL and execute it
manually.
enable-tuned-updates
This facility is not available in WebSphere.
validate-db-schema-with
This facility is not available in WebSphere.
Refer to 9.3, “Deployment descriptor differences” on page 204 for information
about the differences in deployment descriptors for the EJB module.
11.4.3 Web deployment descriptors
Figure 11-5 shows a snapshot of AAT with the Web Modules node expanded, to
show the deployment descriptor mappings.
Chapter 11. Application assembly and deployment
261
Figure 11-5 Layout of Web modules in AAT
Table 11-5 shows how the information from weblogic.xml is mapped to
ibm-web-ext.xmi and ibm-web-bnd.xmi.
262
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Table 11-5 Migrating weblogic.xml
Element/Attribute name
Location in AAT
security-role-assignment
Select Security Roles node under application node
and open the Bindings tab.
reference-descriptor
See below: resource-description and
ejb-reference-description.
resource-description
Resource References node under corresponding Web
module (web.war node).
ejb-reference-description
EJB References node under corresponding Web
module (web.war node).
session-descriptor
Contains various parameters.These parameters go in
different tabs in session manager service settings.
See Figure 11-6.
jsp-descriptor
Contains many parameters. WebSphere uses only a
few of these attributes. Precompile is set on the IBM
Extensions tab of web.war node. Keepgenerated and
encoding are specified by adding attributes for node
JSP Attributes. See 8.4.3, “Parameter settings for
JavaServer Pages” on page 184 for more details.
auth-filter
container-descriptor
No support for this in WebSphere.
charset-params
Figure 11-6 show the session manager service settings window, where you can
enter values from the session-descriptor element of weblogic-web-jar.xml.
Chapter 11. Application assembly and deployment
263
Figure 11-6 Session management in WebSphere Application Server
264
Migrating WebLogic Applications to WebSphere Advanced Edition V4
12
Chapter 12.
Migration examples
This chapter describes the migration process and individual migration issues and
solutions. It shows that a step-by-step approach can help in integrating these
tasks to perform sample migrations. This chapter presents end-to-end examples
of three small migration projects. Together, these examples exploit the process,
tools, and migration advice presented in the rest of this book. Since each
migration project is unique, these examples also raise some of their own
migration issues and highlight variations on the migration process itself.
© Copyright IBM Corp. 2002
265
12.1 Introduction
At first, we searched for a single medium-sized, publicly-available WebLogic
application for migration to WebSphere. The idea was that this would be
representative of an actual migration effort. When we failed to find such an
example, we chose to migrate several smaller examples. We believe this
approach actually revealed a richer set of migration issues. Each example has its
own style and its own migration problems. It would be unlikely to find all of these
styles and problems in a single larger example.
The goal for each example is basically the same: to modify the application using
the WebSphere Studio Application Developer environment to get it running on
WebSphere. The process for each example also follows the same basic steps:
1. Import into WebSphere Studio Application Developer workspace:
a. Collect existing artifacts
b. Construct a standard EAR file
c. Import EAR file into WebSphere Studio Application Developer
2. Migrate the database to DB2. This step can be performed at any time during
step 3., “Iterate through modify and test cycles until the application runs on
WebSphere.” on page 266.
3. Iterate through modify and test cycles until the application runs on
WebSphere.
a. Analyze application to discover errors that prevent deployment or correct
execution.
b. Correct errors. Minimal corrections are OK, but best practices and future
changes should also be considered.
c. Deploy and test on the WebSphere Studio Application Developer test
server.
4. Export the migrated EAR for deployment on WebSphere Application Server,
Advanced Edition.
These steps are consistent with the migration process outlined in 2.3, “Migration
process” on page 26. However, it is important to recognize that one size does not
fit all migration projects. Each migration effort will develop its own variation, as we
did in the examples in this chapter. WebSphere Studio Application Developer is
the primary migration tool set, but other tools were used as needed, including
AAT, Ant, and custom scripts.
266
Migrating WebLogic Applications to WebSphere Advanced Edition V4
An important aspect of any migration effort is to learn how to use the tool set of
the target server. As such, this chapter can also be read as a set of examples on
how to use WebSphere Studio Application Developer. Chapter 4, “Development
and migration tools” on page 67 describes common tasks needed in any
migration effort. Details of the examples in this chapter refer you to those tasks
instead of repeating them here. Less common and specialized tasks are
described in detail within these examples.
Each of our examples has some special features that affect its migration. The
interesting features are listed below:
1. Pet Store application
– Well-known application that has been migrated to many J2EE servers
– Deployed versions available for Sun Microsystems’ reference platform,
WebLogic, and WebSphere
– Source code not included in EAR file
– Uses only BMP beans
– Requires code modification for DB2 migration
2. Trade2 application
–
–
–
–
–
WebLogic deployment descriptors available
Source code part of EAR file
Uses only CMP beans
Built for DB2 using top down RDB mapping
No code modifications needed for DB2 migration
3. Banking application
–
–
–
–
–
–
Originally written for WebLogic
Source code only available in exploded file system structure
Uses only CMP beans
Migration requires meet-in-the-middle RDB mapping
Uses deprecated RMIRegistry mechanism
Uses WebLogic proprietary startup class feature
12.2 Pet Store example
This example was designed as a blueprint for the design of J2EE applications. It
is also used by vendors as a test for J2EE application deployment. It has been
deployed to many J2EE server products, including WebSphere Application
Server, Advanced Edition and WebLogic. Each such deployment has required
minor modifications. You can expect similar migration issues to arise with other
J2EE-compliant applications. We demonstrate how the WebSphere Studio
Application Developer tool set helps you discover and resolve common migration
problems.
Chapter 12. Migration examples
267
As the J2EE standard has evolved, the Java Pet Store has been updated to keep
pace. There are currently three versions of this application available for
downloading from http://java.sun.com/blueprints/code/index.html. We
chose V1.1.2 because it is the most recent version for J2EE 1.2 servers. Since
we expected this to be an almost trivial migration, we adopted a very simplistic
and somewhat optimistic migration strategy:
1. Import the EAR file from Sun Microsystems, without source code
2. Attempt to run the application on the test server to discover migration issues
3. Solve migration issues as they appear, and try to run again
4. Export resulting EAR file for deployment into WebSphere Application Server,
Advanced Edition
5. Repeat these steps using the WebLogic distribution of the Pet Store
application
We discovered and addressed the following common migration issues:
򐂰 Minor syntax problems that violate standards
򐂰 Classpath problems that violate standards
򐂰 Database conversion, in this case to DB2
We also learned how to assemble and deploy in the WebSphere Studio
Application Developer environment. Indeed, this is an excellent exercise for
learning how to use this tool set.
12.2.1 Syntax problems
The jps-1_1_2.zip file from Sun Microsystems includes a petstore.ear file without
Java source code. Source code is optional for an EAR file, so you should always
check to see if it is present. The full Java source for the Pet Store is in the ZIP file,
just not in the EAR file. In a real migration effort, you want to include the Java
source code in your workspace for testing purposes. However, as a kind of
challenge, we decided to see how far we could get using just the class files.
We imported the petstore.ear file into WebSphere Studio Application Developer
as described in “Import EAR file” on page 72. In this process, we clicked the first
Finish to accept component dependencies as distributed. Figure 12-1 shows the
resulting workspace. There are nine projects, one for each of the eight modules
from the petstore.ear file, in addition to PetStoreApp, which we defined as part of
the import operation.
268
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-1 initial import of petstore.ear
Figure 12-1 also shows 495 errors and warnings in the tasks list. Do not be
intimidated by the number of messages. In this case, almost all of them can be
ignored. We used filtering to help find real migration problems. Most of the
messages shown in this figure are for the petstore project. We temporarily closed
this project to remove them from the message list. We also set task filtering to
just show errors as described in “Filter by type” on page 77.
These steps reduce the message list to nine errors, one for each ejb-jar.xml file.
Double-click one of them to bring up the EJB Editor, as shown in Figure 12-2. It
appears that the XML encoding identifier is misspelled throughout the Pet Store.
This identifier should be ISO-8859-1. You can correct this directly in the EJB
Editor. It is common to find this kind of error during migration. It turns out that this
error exists only in the EAR file distributed by Sun Microsystems, and not in the
source code included separately in the ZIP file.
Chapter 12. Migration examples
269
We discovered that this particular error was only critical in the taglib.tld file. Other
cases could be ignored, but will probably cause problems in the future. It is better
to fix them now. We also realized that we need not rely completely on reported
message severities: many errors do not cause a real problem, while some
warnings do.
Figure 12-2 Discover ISO-8859-1 syntax errors
Next, we used resource filtering to discover the resources with most of the errors
and warnings. “Filter by resource” on page 78 describes resource filtering. With
resource filtering in effect, you can step through the projects, their component
folders, and files to see the errors in just those resources. We quickly noticed that
all of the messages are confined to four projects: customerEjb, petstore,
petstoreEjb, and shoppingCartEjb, with most of them in the petstore project.
270
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Using the resource filter to delve into folders in the petstore project, we took a
closer look at the webApplication/ja folder.The webApplication/ja folder supports
the Japanese version of Pet Store. Even though we planned to ignore the
migration of this feature, some of the messages piqued our interest. With
resource filtering in effect, we started looking at the JSP files and found another
common syntax error: the name of the Katakana character encoding type SJIS
(see Figure 12-3). With a bit of research, we verified that this name should be
Shift_JIS instead of SJIS. If you want to find all such errors, use the task filter’s
“where description contains” clause. The filter’s where description field defaults
to blank — see Figure 4-10 on page 79. We modified the resource filter by
entering the string unsupportedencoding in the where description field. This
string was taken from the error message in Figure 12-3. With this filter, we easily
found the twenty-nine JSP files that have this same error. Figure 12-4 on
page 272 shows the results. It is also apparent that all of these errors are in the
webApplication/ja folder.
Figure 12-3 Discover JSP contentType charset naming error
Chapter 12. Migration examples
271
Figure 12-4 Use filter to find all SJIS charset errors
Here is one last example of how WebSphere Studio Application Developer helps
analyze errors. With the task filter set to show only errors in resources and their
children, Figure 12-5 on page 273 shows a JSP file where the definition of the
symbol contact is missing. Look at the JavaCompile error messages in the task
list, and line 26 of the source code. The changeaddressform.jsp file is included
by other JSP files. By convention, the programmer is supposed to define contact
before including changeaddressform.jsp. Although this style is legal and the code
works correctly, it is error prone, and therefore flagged by the static validation of
WebSphere Studio Application Developer. A jsp.include action with parameters
might be a better choice.
Figure 12-5 on page 273 also shows the use of File -> Search to find the six files
that include changeaddressform.jsp. Figure 12-6 on page 274 shows one of
these files with its definition of contact and its include directive of
changeaddressform.jsp. A similar coding style is used in used in the HTML files
in the petstore project, where HTML tags are opened in one file and closed in
another. This is also legal, but error prone, so WebSphere Studio Application
Developer will flag it.
272
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-5 Missing variable definition in included JSP
Chapter 12. Migration examples
273
Figure 12-6 Variable definition provided by including JSP
With the exception of the taglib.tld ISO8859_1 error, the errors and warnings
mentioned so far will not prevent correct execution. Indeed, the version of the Pet
Store distributed with WebSphere Studio Application Developer, found in the
AppServer\installableApps\petstore, contains these same errors from the original
jps-1_1_2.zip distribution from Sun Microsystems.
WebLogic Pet Store distribution
We repeated the above steps with the Pet Store sample application distributed
with WebLogic V6.1. We imported its petstore.ear file into WebSphere Studio
Application Developer and examined the error messages. The only significant
difference is that BEA has apparently rewritten two of the JSPs to error-free
replacements — changeaddressform.jsp and changepreferencesform.jsp. These
two files account for over 45 error and warning messages in the original Pet Store
distribution.
If you try to import the WebLogic EAR file, please notice that the petstore.ear file
from BEA includes all of the deployment code generated for WebLogic. Delete
these folders immediately after import. Curiously, you will find them under the
package name com.sun.j2ee.blueprints.
274
Migrating WebLogic Applications to WebSphere Advanced Edition V4
12.2.2 Classpath problems
In this section, we deal with problems caused by missing or incorrect classpaths.
As a reminder, we are working only with the class files. If the Java source code
was also in the workspace, the Java compiler would be the primary source of
messages about classpath problems. With resource filtering in effect, we next
took a look at the petstoreEjb project. Most of the resulting messages in
Figure 12-7 concern missing classpath information for the petstoreEjb project.
From these messages, it is clear that petstoreEjb depends on each of the other
six EJBs. According to J2EE specifications, classpath information should be
provided by the manifest file of each EJB component.
Figure 12-7 Missing classpath
As you can see in Figure 12-8 on page 276, the petstoreEjb MANIFEST.MF file,
distributed with the Pet Store example, has no references to the other EJBs. This
is an error.
Chapter 12. Migration examples
275
Figure 12-8 petstoreEjb manifest missing dependencies
An EJB manifest is manipulated in WebSphere Studio Application Developer by
the module dependency window. To correct the manifest, do the following:
1. Select the petstoreEjb project.
2. Right-click the Edit Module Dependencies operation. The resulting Module
Dependencies Dialog window is shown in Figure 12-9 on page 277.
3. Place a check in the desired dependencies. As shown in the figure, we added
checks for the client interfaces of the other six EJBs.
276
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-9 Modifying petstoreEjb module dependencies
The manifest information could also have been corrected when we initially
imported the EAR file. See “Import EAR file” on page 72. The corrected
MANIFEST.MF file is shown in Figure 12-10 on page 278.
Chapter 12. Migration examples
277
Figure 12-10 Corrected manifest file for petstoreEjb module
Another way to identify certain kinds of classpath problems is to try to generate
and compile the deployment code. Classpath problems will cause the Java
compiler to complain. Generate deployment code for the components in the
customerEJB project as described in “Generate deployment code” on page 88.
Looking at the results in Figure 12-11 on page 279, it is clear that we have a
classpath problem. One of the deployment classes needs the org.w3c.dom
package. We addressed this problem as follows:
1. We used Edit -> Search to search open projects for the org.w3c.dom
package. See Figure 12-12 on page 279.
2. We found two JAR files containing this package.
3. Using the Edit Module Dependencies operation, similar to what was done in
Figure 12-9 on page 277, we made the customerEjb project depend on the
petstoreEjb.jar.
With this fix to our classpaths, we can successfully generate deployment code for
all seven of the EJB projects.
278
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-11 Errors generating deployment code
Figure 12-12 Search for org.w3c.dom package
Although we know that we still need to migrate the database and complete all of
the deployment descriptors, it is difficult to resist trying to execute the application
right now. This is very easy with WebSphere Studio Application Developer, and it
may uncover additional project dependencies.
Chapter 12. Migration examples
279
1. Follow the instructions in “Run on server” on page 96.
The console in Figure 12-13 shows the results for our Pet Store application.
There are apparently no more classpath problems and each EJB started
successfully. Also notice that a Servers project folder has been added to the
projects list as described in “Run on server” on page 96.
2. Use your browser with URL http://localhost:8080/estore to try to enter
the Pet Store. As expected, we do not get far.
Now we are ready to migrate the database.
Figure 12-13 Running application with incomplete deployment descriptors
12.2.3 Conversion to DB2
Although the original Pet Store application does not support DB2, its design
easily accommodates a new database system with a little bit of new code. For
DB2, we had to add one Java class. As database migration efforts go, this is a
very simple one. Since real database migration usually require new code, data
reformatting, and lots of testing, we recommend organizing this work into a
separate and independent migration effort. In Migrating WebLogic Applications to
WebSphere Advanced Edition, SG24-5956, we did not complete the migration of
280
Migrating WebLogic Applications to WebSphere Advanced Edition V4
the Pet Store application to DB2. Since then, the DB2 code has been written, and
is distributed with WebSphere Application Server, Advanced Edition V4. In this
section, we show you how to use this new code within WebSphere Studio
Application Developer. There are just two parts to this conversion:
򐂰 Generated a DB2 version of the Pet Store database
򐂰 Add the new DB2 support code to the Pet Store application
A script for generating and populating the tables of the DB2 Pet Store database
is distributed in the file AppServer\installableApps\petstore\ps_db2.sql. Logged
in as user db2admin, we created a database with the following commands in a
DB2 command window:
db2
db2
db2
db2
create database PETSTORE
connect to PETSTORE user db2admin using db2admin
-f ps_db2.sql
terminate
The AppServer\installableApps\petstore\petstore.ear file contains the new DB2
support in com.ibm.j2ee.blueprints.customer.order.dao.OrderDAODB2. This
class extends OrderDAOImpl in the corresponding com.sun package. Both the
Java source and class files are provided in the EAR file. In keeping with our
attempt to use only class files in this example, we import only
OrderDAODB2.class into the customerEjb project. Figure 12-14 on page 282
depicts this process. Perform this import operation by carefully following these
steps:
1. Extract OrderDAODB2.class from the EAR file.
2. Click File -> Import.
3. Select File system and Next to get you to the file system window.
4. Browse to the Directory containing the package for the class file, which is
...\customerEjb in this case.
5. Expand the resulting folder structure to the full package name and check the
file (or files) you wish to import, which is OrderDAODB2.class in this case.
6. Now browse to the target folder, which in this case is customerEjb/ejbModule
(alternatively, you could have selected customerEjb/ejbModule before step 2
above).
7. Click OK and Finish.
The folder com/ibm/j2ee will be created and added to the
customerEjb/ejbModule. It contains the newly imported OrderDAODB2.class file.
Chapter 12. Migration examples
281
Figure 12-14 Importing a class file
The next step is to tell the Pet Store application to use this newly imported class
in place of its current database support. The Pet Store application provides an
environment variable for the name of this class. Making an educated guess, we
selected File -> Search to locate OrderDAO, and quickly located the required
variable. To do this:
1. Click File -> Search.
2. Enter OrderDAO as the search expression.
3. Double-click the second of the two resulting ejb-jar.xml files.
4. Referring to Figure 12-15 on page 283, select the Environment tab of the
EJB Editor.
5. Expand TheOrder component to find the OrderDAOClass environment
variable. Its current setting is for OrderDAOCS, the version for Cloudscape.
282
Migrating WebLogic Applications to WebSphere Advanced Edition V4
6. In this view, change sun to ibm, and modify OrderDAOCS to OrderDAODB2.
7. Save the results.
We are done with the database conversion, but we cannot test it yet because we
did not begin with a running application. This is why you want to do database
migration as a separate effort. It allows you to test as you go. Our database
testing will have to be delayed until we complete the assembly and deployment of
the migrated application.
Figure 12-15 FInding the OrderDAOClass environment variable
12.2.4 Complete deployment descriptors
Assembling an application consists of structuring its EJB and Web components,
and creating and initializing component deployment descriptors. Since the Pet
Store has already been structured, its deployment descriptors created, and its
environment variables assigned, all that remains is to bind:
򐂰 The JNDI names for EJBs
򐂰 The JNDI names for EJB references
򐂰 The JNDI names for resource references
Chapter 12. Migration examples
283
The Pet Store has no CMP entity beans, so we do not even need to generate the
ibm-ejb-jar-ext.xmi files used for that purpose.
As discussed in Chapter 7, “Naming” on page 147, JNDI naming can be a bit
confusing, especially when using a new set of deployment tools. To help reduce
confusion and avoid errors, we established a JNDI naming convention. The idea
is to use names that are not easily confused with other names, such as EJB
names, class names, component names, and environment JNDI names.
As we have already seen, our Pet Store contains seven EJB projects, some with
multiple EBJ components, and a Web application. There are also three different
DataSource references. Table 12-1 and Table 12-2 show examples of our JNDI
naming convention. The EJB JNDI names are used for the EJBs themselves, and
for EJB references. The DataSource JNDI names only apply to resource
references. The database name is included here for completeness. It will not be
configured until the server deployment step.
Table 12-1 JNDI names for Pet Store EJBs (partial list)
Remote class
ejb-name
Environment JNDI name
Deployed JNDI name
Account
TheAccount
ejb/account/Account
home/Account
Customer
TheCustomer
ejb/customer/Customer
home/Customer
Order
TheOrder
ejb/order/Order
home/Order
Table 12-2 JNDI names for Pet Store DataSources
Environment JNDI name
Deployed JNDI name
Database
jdbc/InventoryDataSource
datasource/Petstore
PETSTORE
jdbc/EstoreDataSource
datasource/Petstore
PETSTORE
jdbc/SignOnDataSource
datasource/Petstore
PETSTORE
Follow the procedure in “Bind ejb, ejb-ref, and resource-ref” on page 81 for the
customerEjb project. This will bind JNDI names into the deployment descriptors
for the customerEjb project. You can examine the resulting ibm-ejb-jar-bnd.xmi
file in an XML editor.
1. Select the ibm-ejb-jar-bnd.xmi file.
2. Click Open with -> XML Editor.
See the example in Figure 12-16.
284
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-16 JNDI names in ibm-ejb-jar-bnd.xmi file
Each of the EJB projects requires similar treatment, except for the mailerEjb
project, which we ignored. Be careful because spelling errors are easy to make
and there is no checking done for you at the point. Indeed, errors may result in
non-obvious runtime exceptions. The Pet Store uses ejb-link specifications for
each EJB reference. Deployment tools are supposed to use this information for
validating your names, but this is apparently not yet available in WebSphere
Studio Application Developer.
The Pet Store Web component also references the EJBs and the database. For
this purpose, follow the same basic procedure as described in “Bind web.xml
references” on page 82.
Automated conversion of WebLogic descriptors
The manual entry of JNDI names is a slow, error-prone process. If you do not
have to actually change the JNDI names, then it would be nice to automatically
convert the corresponding WebLogic descriptors into WebSphere descriptors. A
tool for doing this is discussed in “The was40utils conversion tool” on page 164. It
is called was40utils, and is available, along with its Java source code, on the
Web. We tried using this tool on the descriptor files from the Pet Store distributed
with WebLogic V6.1. Although the was40utils tool worked as advertised, the
WebLogic descriptor files contained errors that prevented a successful result.
Chapter 12. Migration examples
285
򐂰 It successfully added the optional identifiers required by WebSphere.
򐂰 It successfully extracted EJB JNDI names and generated EJB bindings.
򐂰 It successfully extracted the JNDI names for resource references and
generated resource reference bindings.
򐂰 It failed to extract the EJB reference JNDI names. Instead, it generated EJB
reference bindings with a blank JNDI names.
Upon further investigation, it was found that the problem was caused by incorrect
<ejb-ref-name> names in the distributed weblogic-ejb-jar.xml files. For example,
ejb/account should be ejb/account/Account, and ejb/order should be
ejb/order/Order. The was40utils conversion succeeds if you correct these
names. We did not verify that the distributed Pet Store actually runs on
WebLogic. If WebLogic uses the <ejb-link> descriptors (see 7.4.5, “The ejb-link
alternative” on page 170), it may just ignore incorrect extended descriptors
altogether. We did not investigate further. This difficulty highlights the importance
of making sure your application artifacts are complete and correct before starting
the migration project..
12.2.5 Deploy to test environment
At this point, the only missing piece is the connection to our PETSTORE
database. Although we have already assembled a JNDI name for the database,
the actual target object of this name has not been assigned. This object is a
Connection factory for our DB2 database. We have to configure the WebSphere
Studio Application Developer test server for the database. If we deploy to another
server, it will have to be configured for the same or similar database on that
server. Our final EAR file will contain the deployed JNDI name for referencing our
database, but not the configuration information for the required DB2 Connection
factory. The database configuration information will be placed in the
defaultConfiguration.wsc/server-cfg.xml file in the Servers project folder.
Deploy and test as follows:
1. Follow the procedure in “Configure database” on page 92.
2. With all of the changes we have made, rebuild each project and regenerate
the deployment code according to “Generate deployment code” on page 88.
3. Start the Pet Store application on the test server as described in “Run on
server” on page 96.
4. Point your browser to http://localhost:8080/estore and buy some cats
and dogs. This should look like Figure 12-17.
286
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-17 Pet Store on WebSphere Studio Application Developer V4.0 using DB2
If you made some errors along the way, as we did the first time around, the server
console will provide clues in the form of Java exceptions.
You have completed migrating the Pet Store application and have tested it at
least a little bit. It is time for production:
1. Create the final EAR file by following the instructions in “Export EAR file” on
page 97.
Chapter 12. Migration examples
287
2. Deploy on WebSphere Application Server, Advanced Edition according to
“Deploy on WebSphere” on page 98.
12.2.6 Summary
We successfully migrated and deployed both the Sun Microsystems’ and
WebLogic’s Pet Store distributions to WebSphere V4.0 using DB2. Moreover,
with the exception of one new Java class for the DB2 support, this migration was
accomplished without using the Java source code. This represents a big
advance over the Pet Store migration example described in Migrating WebLogic
Applications to WebSphere Advanced Edition, SG24-5956. That migration
required significant code modifications.
There was no significant difference between the three Pet Store distributions that
we worked with. The only differences were relatively minor spelling and syntax
errors.
Even though we did not use WebSphere Studio Application Developer to develop
new Java code, it was clear that an integrated environment is just as helpful at
coding and testing deployment descriptors. Migration is not a one-shot
assignment of deployment properties. It has the same iterative modify and test
cycle as does code development. That is:
1.
2.
3.
4.
5.
6.
Search projects for deployment properties and dependencies
Change deployment descriptor to what you think will work
Generate deployment code
Deploy to test server
Run on test server
Repeat process until there are no errors
Our deployment descriptors were not perfect the first time around. The effects of
missing or misspelled JNDI names or environment variables often do not show
up until runtime. Test tools, such as the JNDI Explorer, are wonderful debugging
tools. Granted, we did spend time learning how to use the tools, but the resulting
automation and integration with WebSphere Studio Application Developer was
well worth the investment.
The most error-prone and tedious task was translating and re-entering the
vendor-supplied deployment descriptors — mostly JNDI names in the Pet Store
example. The was40utils tool was helpful in partially automating this task, and
further investment in this area would be beneficial.
288
Migrating WebLogic Applications to WebSphere Advanced Edition V4
12.3 Trade2 example
The Trade2 application was written by IBM for evaluating J2EE performance
issues. We are interested only in the migration issues represented by this
application, and not performance evaluation. Trade2 has also been ported to
WebLogic, so we have two versions available for analysis and comparison.
By comparison with the Pet Store application, Trade2 accesses its database
through CMP beans, instead of BMP beans. CMP beans should be more
portable, and thus easier to migrate, because SQL code is provided by
deployment descriptors instead of being hardcoded into the beans. We examine
this assumption in this example.
Our strategy for the Trade2 example is:
1. Import the original application into WebSphere Studio Application Developer
for analysis, deployment, and test.
2. Migrate the WebLogic version and examine it for:
– Portability issues
– Deployment descriptor conversion
3. Introduce the WebSphere Studio Application Developer tools used for CMP
beans and RDB mapping.
12.3.1 Trade2 in WebSphere Studio Application Developer
Since Trade2 was originally written to run on WebSphere using DB2, deploying
and testing it in WebSphere Studio Application Developer was straightforward.
Our purpose in using this example was to show how a CMP-based application
looks in WebSphere Studio Application Developer. The Trade2 EAR file contains
source code and is ready to deploy. The download is available from
http://www-4.ibm.com/software/webservers/appserv/wpbs_download.html. To
become familiar with the application, we first did the following:
1. Import the EAR file.
2. Create the DB2 database and configure the test server to use it.
3. Deploy and run in the test server.
Import TradeSample.ear
The import went smoothly:
1. We imported the TradeSample.ear file according to the steps described in
“Import EAR file” on page 72.
2. We reviewed the warning messages in the resulting tasks message list.
Chapter 12. Migration examples
289
Although there were a total of 71 warnings, they were relatively minor:
򐂰 A few deprecated methods
򐂰 Invalid bordercolor in JSPs
򐂰 Java static variable not declared final
A quick look at EJB references reassured us that the application’s deployment
descriptors were initialized. For example, the web.xml editor shown in
Figure 12-18 indicates that the Web application’s EJB references have been
initialized to reasonable JNDI names.
Figure 12-18 Imported TradeSample.ear
Create DB2 database
The Trade2 DB2 database is created by a script, called TradeDB.bat. It is
distributed as part of the DB2_AEs.zip file. We could not find current
documentation for this script, so we just figured it out. This script also has a
couple of errors. These sort of problems are typical in migration projects.
Make sure that the two CONNECT commands in the script are modified to the
following:
db2 -z %LOG% CONNECT TO TRADEDB USER %DB2USER% using %DB2PASSWD%
We logged on as user db2admin, and executed this script in a DB2 command
window initiated by db2cmd. The script takes four arguments:
TradeDB.bat db2admin db2admin DB2 db2log.log
290
Migrating WebLogic Applications to WebSphere Advanced Edition V4
DB2 is the instance name for our databases. This generates a database by the
name of TRADEDB.
The Trade2 application refers to its database with the deployed JNDI name
jdbc/TradeSample. We completed the Trade2 deployment as follows:
1. Used the steps described in 4.1.3, “Setup test server” on page 88 to create a
test server.
2. Configured the jdbc/TradeSample DataSource to refer to our TRADEDB
database following directions in “Configure database” on page 92.
Run Trade2
Now we are ready to execute the Trade2 application:
1. Look in the application.xml file to find the Trade2 context root. It is
WebSphereSamples/TradeSample.
2. Start the Trade2 application on the test server, as described in “Run on
server” on page 96.
3. Go to http://localhost:8080/WebSphereSamples/TradeSample and you will
be able to play with Trade2.
a. The first time, you should generate sample data by selecting
Configuration -> Populate Trade Database.
b. Start trading stocks by selecting Go Trade! -> Log in from the Overview
page — Figure 12-19 shows a sample page.
Chapter 12. Migration examples
291
Figure 12-19 Trade2 in WebSphere Studio Application Developer test server
12.3.2 Using WebLogic deployment descriptors
We obtained the instructions for running Trade2 on WebLogic V6.1 from
http://www.bea.com/products/weblogic/server/BEA_WebLogic_Server_Trade2.
zip. These instructions describe how to do the following:
1. Create a Trade2 EAR file with no WebSphere dependencies. This requires:
– Removing WebSphere generated deployment code
– Removing WebSphere-specific deployment descriptors
– Disabling VisualAge for Java access beans
Although the Trade2 application uses access beans, it has been designed so
that they can be disabled. Unfortunately, this dependency cannot be
completely removed. You must continue to have the ivjejb35.jar in your
classpath to access com.ibm.ivj.ejb packages.
292
Migrating WebLogic Applications to WebSphere Advanced Edition V4
The other changes are:
– Comment out a couple of access bean finder methods
– Remove the FinderHelper Java classes
– Disable use of access beans by modifying the RunTimeMode variable in
the TradeConfig.java file from EJB to EJBNOACCESSBEAN.
We chose not to bother disabling the access beans, and instead just focused
on the deployment descriptors.
2. Install the provided WebLogic-specific deployment descriptors.
The fact that Trade2 runs on WebLogic with minimal source code changes is a
testament to its portability. The one exception is its use of proprietary access
beans. By comparison, Trade2 is more portable than the Pet Store because CMP
beans eliminate the need for embedded SQL statements.
Vendor-neutral EAR
We tried to create a vendor-neutral EAR file, that is, one with no vendor-specific
descriptors. We could not get WebSphere Studio Application Developer to do
this. It insists on adding WebSphere-dependent descriptor files. Instead, we
chose to write a simple batch script to create a vendor-neutral EAR file. It uses
the jar command to implement the WebLogic removal instructions summarized
above. The script is included with the additional materials for this redbook on the
Web. The results of importing the vendor-neutral TradeSample2.ear file into
WebSphere Studio Application Developer is shown in Figure 12-20 on page 294.
This figure shows the Web components deployment descriptors using the
Web.xml editor. The ibm-web-bnd.xmi and ibm-web-ext.xmi files have been
created as a side effect of the import. However, it is clear from the empty JNDI
Name column in Figure 12-20 that these deployment descriptors are incomplete.
This of course was expected, because these JNDI bindings are recorded in
vendor-specific deployment descriptors.
Chapter 12. Migration examples
293
Figure 12-20 Import of vendor-neutral version of Trade2
Converting WebLogic deployment descriptors
We decided to see how far we could get using the was40utils conversion
program to automatically convert the descriptors supplied by WebLogic. This
program only addresses deployed JNDI names, so it cannot help convert the
CMP deployment descriptors. Because we had some difficulty with its use in Pet
Store (see “Automated conversion of WebLogic descriptors” on page 285), we
thought we would give it a second try with Trade2. The was40utils conversion
program is described in “The was40utils conversion tool” on page 164. We used
it as follows:
1. Use the original web.xml and ejb-jar.xml files provide with the IBM Trade2
distribution.
These files already have the optional IDs required for WebSphere.
2. Convert the WebLogic weblogic.xml file to ibm-web-bnd.xmi using the
was40utils cvtwebwl command.
3. Convert the WebLogic weblogic-ejb-jar.xml file to ibm-ejb-jar-bnd.xmi using
the was40utils cvtwl command.
We had to correct a misspelled JNDI name in the distributed
weblogic-ejb-jar.xml file. The symbol TradeRegistryHome should be
RegistryHome.
4. Import the converted ibm-web-bnd.xmi and ibm-ejb-jar-bnd.xmi deployment
descriptor files into our vendor-neutral version of Trade2.
294
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-21 shows importing the ibm-web-bnd.xmi file using a variation of
the import described in Figure 12-14 on page 282.
Figure 12-21 Import of converted descriptor file
The conversion of the WebLogic descriptor files was successful. See the
additional materials for this redbook on the Web for more details. The results of
importing the ibm-web-bnd.xmi file is shown in the Web.xml Editor in
Figure 12-22 on page 296. You can see that the EJB references are now bound
to the JNDI names specified by the original WebLogic descriptors. The
DataSource references (not shown in the figure) are also bound properly.
Chapter 12. Migration examples
295
Figure 12-22 Trade2 with converted deployment descriptors
When we shift our view from the Trade Web component to the TradeEJBs
component, however, we discover that there is still a problem with deployed JNDI
names. None of the access beans listed in Figure 12-23 on page 297 had been
bound to JNDI names. By comparison, the original WebSphere deployment has
a DataSource JNDI name bound to each of the access beans. The reason for
these unbound resources is that Trade2 was deployed on WebLogic using a
vendor-specific ConnectionPool option in place of standard DataSources. You
can see this by looking at the beginning of weblogic-cmp-rdbms-jar-account.xml,
for example, where you find:
<weblogic-rdbms-bean>
<pool-name>tradePool</pool-name>
<table-name>TradeAccountBean</table-name>
We resolved this problem in the Bindings tab of the EJB Extension Editor by
entering a single JNDI name that applies to all of the access beans in a
component, as follows:
1. Select the name of the component.
2. Enter the JNDI name in the DataSource JNDI name field as shown in
Figure 12-23.
296
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-23 Use DataSource in place of WebLogic ConnectionPool
Alternatively, you can bind a JNDI resource name to each entity bean
individually. Just modify the above procedure by selecting the bean instead of the
component. This is the way the original Trade2 application is deployed.
All of the EJBs, EJB references, and resource references are now bound to
deployment JNDI names.
12.3.3 Top-down RDB mapping
The CMP entity beans of Trade2 must be mapped to the database as part of the
deployment process. Trade2 was originally constructed using a top-down
mapping of its entity beans to the underlying database. In this approach, you
start with the entity beans and generate table definitions from the fields of your
entity beans. In a realistic migration effort, the meet-in-the-middle approach is
more likely. In the meet-in-the-middle approach, your beans and your database
are already defined for you. Your goal is to create an RDB mapping that
preserves both the bean and the database definitions. See “Meet-in-the-middle
RDB mapping” on page 84 for a description of this mapping technique.
To create a top-down RDB mapping, do the following:
1. Select a project with CMP entity beans — TradeEJBs in this case.
2. Right-click Generate -> EJB to RDB Mapping to start the mapping editor
window.
Chapter 12. Migration examples
297
3. Select Top Down and click Next. See results in Figure 12-24 on page 299.
4. Enter the database name and schema — for us these are TRADEDB and
DB2ADMIN.
Note that the schema name is used here, whereas the database user ID and
password are used in the meet-in-the-middle approach.
5. Select Generate DDL and click Finish.
6. View the results using the mapping editor as shown in Figure 12-25 on
page 300. Right-click Map.mapxmi, then select Open With -> Mapping
Editor.
Notice in Figure 12-25 that the RDB mapping has created several new
deployment files:
򐂰 The Schema directory contains files for each of the database tables.
򐂰 The Map.mapxmi file contains the mapping.
򐂰 Table.ddl file contains SQL used to create the database tables.
298
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Figure 12-24 Top-down CMP mapping used by Trade2
Chapter 12. Migration examples
299
Figure 12-25 Results of top-down mapping
12.3.4 Create finder methods
To complete the deployment of our CMP entity beans, we must provide the
appropriate SQL for the finder methods. This is done through the Finders tab of
the EBJ Extension Editor. See “Create finders” on page 83 for a description of
this process. The SQL for the Trade2 finder methods is shown in Table 12-3.
Table 12-3 SQL for Trade2 finder methods
finder method name
SQL query
findNewUsers
userID like 'ru:%'
findByMax
findByMaximum
indx = (SELECT MAX(indx) FROM
TradeHoldingBean)
findByUserID
userID = ?
12.3.5 Deploy and run
The Trade2 application is now ready to deploy and run:
1. Generate deployment code — see “Generate deployment code” on page 88.
2. Create a test server — see 4.1.3, “Setup test server” on page 88.
300
Migrating WebLogic Applications to WebSphere Advanced Edition V4
3. Configure the server with a jdbc/TradeSample DataSource for the TRADEDB
database — see “Configure database” on page 92.
4. Start Trade2 on the test server — see “Run on server” on page 96.
12.3.6 Summary
Although we did not actually migrate the Trade2 application to another database
system, CMP beans offer distinct portability advantages over BMP beans. Even
though the Pet Store database migration to DB2 only required a single new Java
class, the code is non-trivial, containing over 350 lines. By comparison, migrating
a Trade2-like application to DB2 using WebSphere Studio Application Developer
requires only the following:
1. Deployment of a small number of SQL fragments for finder methods.
There are three such fragments in the Trade2 application.
2. A tool-assisted RDB mapping task
We examined top-down mapping in this example. A more realistic migration
would use the meet-in-the-middle approach. See 12.4, “Banking example” on
page 302 for an example of this approach. Although it is a more complex
mapping task, it can usually be accomplished without coding changes.
With regard to the automatic conversion of deployment descriptors, we had
better luck than we did with the Pet Store. Unfortunately, it appears that CMP
deployment will continue to require manual effort, in particular for
meet-in-the-middle mappings. However, the WebSphere Studio Application
Developer RDB mapping tools were very easy to use for this task.
We discovered several unexpected migration issues that are based on the use of
proprietary technologies:
򐂰 The BEA version of Trade2 uses a proprietary connection pool technology
instead of the standard DataSource.
򐂰 Trade2, written by IBM, relies on proprietary VisualAge for Java access
beans. Fortunately they can be disabled if desired.
򐂰 WebSphere Studio Application Developer does not seem to be able to
generate a completely vendor-neutral EAR file.
Proprietary technologies often represent difficult migration issues. Fortunately,
these particular problems were easily solved.
Chapter 12. Migration examples
301
12.4 Banking example
The banking application was written by BEA to run on WebLogic. It is a sample
application included in the WebLogic V6.1 documentation. Except for its small
size, this example comes closest to our original requirement of a realistic
application originally written for WebLogic.
A preliminary look at the banking application indicated the following interesting
migration issues:
1. It has CMP beans with field names that differ from the names of the
underlying database attributes. This suggests the use of a meet-in-the-middle
RDB mapping.
2. The source code is only provided in the exploded file system format, instead
of following the J2EE standard of being included in the EAR file. This is a
common migration issue.
Listed below is the approach we took to migrate the banking example:
1.
2.
3.
4.
5.
6.
7.
Deploy the application on BEA WebLogic Server using DB2 database
Import application in WebSphere Studio Application Developer
Fix compilation problems, do any code changes
Write deployment descriptors
Test the application
Export EAR
Deploy the EAR on WebSphere
12.4.1 Deploying on BEA WebLogic Server
See Chapter 3, “Installation and configuration” on page 35, for how to install and
configure BEA WebLogic Server.
We decided to deploy the example in exploded format for two reasons. First, we
did not have EAR file and second, the instructions for deploying the example in
exploded form were available on BEA WebLogic Server site.
The following site gives information about how to deploy an exploded J2EE
application on BEA WebLogic Server:
http://e-docs.bea.com/wls/docs61/deployment/index.html
Deployment steps are listed on the BEA site:
http://e-docs.bea.com/wls/docs61/deployment/deploymentapp.html.
We did a few changes to the deployment steps, which are listed below. Some
changes were to match our environment, while others were to correct the
deployment steps.
302
Migrating WebLogic Applications to WebSphere Advanced Edition V4
1. We changed the banking.ddl file provided in the ejb directory to that shown in
Example 12-1.
Example 12-1 banking.ddl
DROP TABLE BANK_ACCOUNT_BEAN_TABLE
CREATE TABLE BANK_ACCOUNT_BEAN_TABLE (id varchar(15) not null, bal float,
type varchar(15), primary key(id))
insert into BANK_ACCOUNT_BEAN_TABLE values ('6000', 35000.00,'savings')
insert into BANK_ACCOUNT_BEAN_TABLE values ('1000', 1500.00,'checking')
The table name was changed to BANK_ACCOUNT_BEAN_TABLE. In the
insert statement, quotes were added to the values of the first column, id. This
was required to match the varchar column definition.
2. The connection pool was created with the attributes shown in Table 12-4.
Table 12-4 ITSOConnectionPool
Property name
Value
Name
ITSOConnectionPool
URL
jdbc:db2:ITSO
Driver Class Name
COM.ibm.db2.jdbc.app.DB2Driver
Properties(key=value)
user=db2admin
password=db2admin
ACL Name
weblogic.allow.reserve.jdbc.connectionPo
ol.ITSOConnectionPool=everyone
Maximum Capacity
2
3. We configured a new startup class, RMIServerLogger, as shown in
Table 12-5.
Table 12-5 Startup class configuration
Property name
Value
Name
RMIServerLogger
ClassName
examples.tutorials.migration.banking.RMILoggerImpl
This step was missing in the original setup instructions.
4. The following values were updated in the weblogic-cmp-rdbms-jar.xml file for
AccountBean EJB:
<pool-name>ITSOConnectionPool</pool-name>
<table-name>BANK_ACCOUNT_BEAN_TABLE</table-name>
Chapter 12. Migration examples
303
5. As shown in Example 12-2, the column names were updated for
AccountBean in the weblogic-cmp-rdbms-jar.xml file. This step is missing
from the original deployment document.
Example 12-2 Field mappings in weblogic-cmp-rdbms-jar.xml
<field-map>
<cmp-field>accountId</cmp-field>
<dbms-column>id</dbms-column>
</field-map>
<field-map>
<cmp-field>balance</cmp-field>
<dbms-column>bal</dbms-column>
</field-map>
<field-map>
<cmp-field>accountType</cmp-field>
<dbms-column>type</dbms-column>
</field-map>
6. We used weblogic.ant.taskdefs.ear.DDInit to create the application.xml file.
We had to update the value of the context-root element to banking. Our
application.xml is shown in Example 12-3.
Example 12-3 application.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application
1.2//EN' 'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>
<application>
<display-name></display-name>
<module>
<ejb>ejb</ejb>
</module>
<module>
<web>
<web-uri>web</web-uri>
<context-root>banking</context-root>
</web>
</module>
</application>
7. The deployment document requires that the servlet and servlet-mapping
elements be removed from the web.xml file. We had to put them back. Also
the servlet mapping was updated for BankAppServlet. See Example 12-4.
Example 12-4 Servlet mapping for BankAppServlet
<servlet-mapping>
<servlet-name>BankAppServlet</servlet-name>
304
Migrating WebLogic Applications to WebSphere Advanced Edition V4
<url-pattern>/banking</url-pattern>
</servlet-mapping>
8. We changed the URL for looking up RMILogger, since we set up a separate
managed server to run the example (See Chapter 3, “Installation and
configuration” on page 35 to set up a managed server). We changed the port
to 8001.
theLogger =
(RMILogger)Naming.lookup("rmi://localhost:8001/RMILoggerServer");
9. We also changed the lookupHome method in BankAppServlet to use the
appropriate JNDI name for AccountHome as specified in the
weblogic-ejb-jar.xml. Normally you would fix it in weblogic-ejb-jar.xml file, but
since the deployment steps explicitly require setting the particular JNDI name,
we thought it was a bug in the Servlet.
Object home = (AccountHome) ctx.lookup("AccountBean.AccountHome");
With the above changes we got the banking sample running in our WebLogic
server. The modified code is available in the dev directory. The deploy directory
contains the application in exploded format and is ready to deploy. The
descriptors directory contains modified descriptors. See 12.4.11, “Additional
materials” on page 315 for more details.
12.4.2 Importing into WebSphere Studio Application Developer
As explained in “Tools strategy” on page 28, there are many ways to import the
code into WebSphere Studio Application Developer. For the banking example,
we used alternative 3, which is to use Ant to create the EAR file for import
purposes. We wrote an Ant script to create an EAR file with Java code and used
the generated EAR file to import the code into WebSphere Studio Application
Developer. If you used Ant scripts to deploy your applications in WebLogic, this is
a better option, since you can tweak the existing Ant script to include source code
in the EAR file.
See Chapter 4, “Development and migration tools” on page 67 for information
about installing and using Ant. You can find the build files we used to create the
EAR file in the additional materials for this redbook on the Web. See “Additional
materials” on page 315 for details about the Ant build files. In the additional
materials, you will also find a descriptors folder that contains all the modified
deployment descriptors. Please note that the application.xml file was updated to
refer to ejb.jar and web.war. The modified application.xml file is stored as
application_ear.xml in the descriptors directory. Also we copied WebLogic
specific descriptors into the descriptors folder.
Chapter 12. Migration examples
305
We imported the banking.ear file according to the directions found in “Import
EAR file” on page 72. In the process, we insured that the web.war manifest
included ejb.jar as a dependency.
12.4.3 Error analysis
Figure 12-26 shows the results of importing the banking.ear file. This figure
shows 37 errors in the Task window. To help analyze these errors, we used
resource filtering, described in “Filter by resource” on page 78. Now when you
select individual projects, you will find that there are 16 errors in BankingAppEJB
and 21 in BankingAppWeb.
Figure 12-26 Problems after importing banking.ear
You will notice that many of these errors are due to missing WebLogic classes.
You have to fix the references and migrate the code as explained in earlier
chapters. For example, weblogic.rmi.Remote is flagged as undefined in
Figure 12-26. When we changed the references of weblogic.rmi to java.rmi in
RMILogger, RMILoggerImpl, BankAppServlet, this brought down the total error
count to 22.
There are a few errors in BankingAppWeb that are due to invalid HTML syntax
and are listed as warnings. Although fixing these warnings is not required, it is
always a good practice to fix warnings in HTML and JSP files whenever you can.
That way you do not have tons of tasks in your task window. One such example
is in login.html, shown in Example 12-5.
306
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Example 12-5 Fixing login.html
<p><img src="images/BEA_Button_Final_web.gif" align=right></p>
<body>
<form ACTION="banking" METHOD="POST">
If you open the login.html with Source Editor, and fix the following two lines, it will
fix five errors:
򐂰 The </p> was missing in the first line.
򐂰 The <body> tag included invalid attributes such as marginwidth and
topmargin.
Basically all the attributes for margins were removed from the <body> tag and
the paragraph above the <body> tag was ended with </p>. Do the same thing for
AccountDetail.jsp and error.jsp and it will bring the total error count down to 7.
The remaining two errors in AccountDetail.jsp can be ignored: we do not have
trans.gif, which indeed is an error, and the other is due to a null action specified
in the form that is populated by JavaScript when the user clicks the Deposit or
Withdraw buttons.
12.4.4 Migrating deprecated and proprietary features
We changed a small amount of code in the banking example in order to migrate
away from using the following two features.
1. Proprietary WebLogic startup class
WebSphere does not support startup classes. A more standard way to
achieve the same behavior is to put the initialization code for the startup class
into the init method of an appropriate servlet. To this end, we moved an
upgraded version of the code from RMILoggerImpl.main into the init method
of BankAppServlet, as shown in Example 12-6.
2. Deprecated RMIRegistry support
As noted in the comments in the BankAppServlet, the use of JNDI is
preferred over the more traditional RMI support. As part of this migration
example, we converted to using JNDI standard. See 7.4.4, “Conversion of
WebLogic RMI” on page 165 for full details. Example 12-6 and Example 12-7
show the converted code.
Chapter 12. Migration examples
307
Example 12-6 BankAppServlet.init method
/**
* This method performs servlet initialization. The RMI Logger stub
* is retrieved by doing a lookup for the RMILoggerServer.
*
* @param config
ServletConfig
*/
public void init(ServletConfig config) throws ServletException {
super.init(config);
try {
Context ctx = getInitialContext();
Object anLogger = null;
// following code adapted from RMILoggerImpl.main WebLogic startup class
try {
anLogger = ctx.lookup("RMILoggerServer");
} catch (NamingException e) {
RMILogger newLogger = new RMILoggerImpl("RMILoggerServer");
PortableRemoteObject.exportObject(newLogger);
ctx.bind("RMILoggerServer", newLogger);
anLogger = (RMILogger) ctx.lookup("RMILoggerServer");
}
theLogger = (RMILogger) PortableRemoteObject.narrow(anLogger,
RMILogger.class);
System.out.println("Successfully connected to RMILoggerServer");
} catch (RemoteException e) {
new ServletException("Error connecting to RMILoggerServer", e);
} catch (NamingException e) {
new ServletException("Error connecting to RMILoggerServer", e);
}
}
We also modified the getInitialContext method as shown in Example 12-7.
Example 12-7 BankAppServlet.getInitialContext method
private Context getInitialContext()
throws java.rmi.RemoteException, NamingException {
try {
// Get an InitialContext
Properties h = new Properties();
//h.put(Context.INITIAL_CONTEXT_FACTORY,
// "weblogic.jndi.WLInitialContextFactory");
return new InitialContext(h);
} catch (NamingException ne) {
StringBuffer aSB = new StringBuffer();
aSB.append("We were unable to get a connection to the WebLogic server");
308
Migrating WebLogic Applications to WebSphere Advanced Edition V4
aSB.append("Please make sure that the server is running.");
theLogger.log(aSB.toString());
throw ne;
}
}
Basically, we commented out the line that specified the context factory.
12.4.5 Writing deployment descriptors
When the EAR file was imported, WebSphere-specific deployment descriptors
for BankingAppWeb were automatically created. See the ibm-web-bnd.xmi and
ibm-web-ext.xmi files under WEF-INF folder. But there are two errors in web.xml
descriptor. Both errors are reported as:
The jsp-file "xxx.jsp" referenced by servlet xxx must be a full
absolute path.
As per http://java.sun.com/j2ee/dtds/web-app_2_2.dtd, the element
<jsp-file> should contain the full path to a JSP file within the Web application. But
WebSphere Studio Application Developer requires the full absolute path, which
means there should be a leading ‘/’ in the value of <jsp-file> tag.
1. Double-click one of the error lines, and it opens Web.xml Editor.
2. Select the Source tab.
3. Add ‘/’ in front of AccountDetail.jsp and error.jsp as shown in Example 12-8.
4. Save your changes.
Example 12-8 Fixing <jsp-file> tags
<servlet>
<servlet-name>AccountDetail</servlet-name>
<jsp-file>/AccountDetail.jsp</jsp-file>
</servlet>
<servlet>
<servlet-name>error</servlet-name>
<jsp-file>/error.jsp</jsp-file>
</servlet>
The remaining three errors are in BankingAppEJB and are of type:
Either a finder descriptor, or a matching custom finder method on the
xxx class, must be defined
Chapter 12. Migration examples
309
This is due to missing finder descriptors. Use the procedure outlined in “Create
finders” on page 83 to generate the finder methods. The SQL for these methods
is shown in Table 12-6.
Table 12-6 SQL for banking finder methods
Finder method name
SQL query
findAccount
balance = $0
findBigAccounts
balance > $0
findNullAccounts
balance IS NULL
At this time you must also specify the bindings for CMP entity beans:
1. Open the Bindings tab. This is shown in Figure 12-23 on page 297.
2. Select the ejb.jar component.
3. Enter jdbc/ITSODataSource in the JNDI name for DataSource.
Instead of setting the DataSource for ejb.jar, you could also set it for individual
entity beans, in which case it would override the settings at the ejb.jar level.
Select AccountBean and update the JNDI name to AccountBean.AccountHome.
When you save the changes, WebSphere Studio Application Developer will
create the ibm-ejb-jar-ext.xmi and ibm-ejb-jar-bnd.xmi files.
12.4.6 Meet-in-the-middle RDB mapping
The following meet-in-the-middle procedure was used to map the CMP
AccountBean to the BANK_ACCOUNT_BEAN_TABLE database table.
1. Follow the procedure described in “Meet-in-the-middle RDB mapping” on
page 84, choosing the manual mapping option.
2. Select AccountBean in the J2EE perspective.
3. Click Open -> Mapping Editor to complete manual mapping. See the editor
in Figure 12-27 on page 311.
4. Select AccountBean on left and Bank_Account_Bean_Table on the right.
5. Right-click and select Create Mapping.
6. Expand the bean and the table to see their attributes.
7. For each pair of attributes that you need to map:
a. Select the bean field on the left.
b. Select the database attribute on the right.
310
Migrating WebLogic Applications to WebSphere Advanced Edition V4
c. Right-click and select Create Mapping.
d. Repeat this process for each of the following attribute pairs:
•
accountId <-> id
•
balance <->bal
•
accountType <-> type
8. Save the results.
After completing mappings, your view would look like Figure 12-27.
Figure 12-27 EJB to RDB Mapping (complete)
12.4.7 Generating RMI stubs and ties
The banking application uses RMI classes. Generating deployment code involves
a few extra steps:
1. Follow the instructions in “Generate deployment code” on page 88 to create
deployment code for AccountBean in ejb-jar module.
2. Run rmic to generate RMI stubs and ties with the following command:
Chapter 12. Migration examples
311
rmic -iiop -keep
examples.tutorials.migration.banking.RMILoggerImpl
3. Compile RMI stubs and ties:
a. Export the RMILogger and RMILoggerImpl in c:\banking\rmic\src.
b. Run the script _rmic.cmd to compile and generate stubs and ties for the
RMI classes.
4. Import the generated Java classes as shown in Figure 12-28 on page 312.
You are now ready to test the application.
Figure 12-28 Import RMI stubs and ties
312
Migrating WebLogic Applications to WebSphere Advanced Edition V4
12.4.8 Testing application
Test the banking application as follows:
1. Set up the WebSphere Studio Application Developer test server according to
directions found in 4.1.3, “Setup test server” on page 88.
2. Configure the banking ITSODataSource using instructions given in “Configure
database” on page 92 and the data in Table 12-7 on page 313.
3. Start the Banking Server following the directions in “Run on server” on
page 96.
4. Point you browser to http://localhost:8080/login.html, and enter 1000 or
6000 as the account number.
5. Test withdrawal and deposit functions as shown in Figure 12-29 on page 314.
Table 12-7 ITSODataSource
Property name
Value
Name
ITSODataSource
JNDI name
jdbc/ITSODataSource
Database name
ITSO
Default user ID
db2admin
Default user password
db2admin
12.4.9 Deploying banking EAR on WebSphere
Deploy on WebSphere as follows:
1. Follow the steps given in “Export EAR file” on page 97, making sure you
export the source code as part of the EAR.
2. Deploy to WebSphere Application Server, Advanced Edition according to the
steps in “Deploy on WebSphere” on page 98.
Do not regenerate the deployment code, because that was already done
under WebSphere Studio Application Developer.
3. Start the ITSO Server. If it is already running, just start the BankingApp.
4. Open a Web browser and enter: http://localhost/banking/login.html.
Figure 12-29 shows a sample browser view of the banking application running on
the WebSphere server.
Chapter 12. Migration examples
313
Figure 12-29 Banking application running on WebSphere server
12.4.10 Summary
We successfully migrated this simple WebLogic application to run on WebSphere
Application Server, Advanced Edition. Although it took a little extra work to get
the Java source code into the WebSphere Studio Application Developer
environment, these tools simplified the overall migration task. The
meet-in-the-middle RDB mapping tool was especially easy to use.
Although it is possible to import source code into WebSphere Studio Application
Developer in several different ways, we chose to use an Ant script to construct an
EAR file with source code. The EAR with its source code is then easily imported.
Since WebLogic supports the exploded file system format, we suspect this
technique will be useful in other WebLogic migration efforts.
One surprise in this example was the use of RMI and the RMIRegistry. These
interfaces were deprecated with the introduction of RMI over IIOP and the JNDI
environment context. It is not unusual to find obsolete code like this during a
migration effort. The ideal approach is to upgrade the code as part of the
migration. We only took the first steps toward this ideal.
1. The RMIRegistry lookups were replaced by JNDI calls, but we did not convert
completely to the JNDI environment context.
2. We retained the remaining RMI class usage and simply modified the build
process. A complete upgrade to RMI over IIOP should be done.
314
Migrating WebLogic Applications to WebSphere Advanced Edition V4
One additional note is worth mentioning about this example. By comparing the
two deployments — one for WebLogic and one WebSphere — it is clear that
there is a definite style difference between the tools used for each. The
WebLogic style uses line-oriented commands and general-purpose editors, while
WebSphere Studio Application Developer uses window-based tools and
special-purpose editors. While WebLogic developers may be more comfortable
with the former, the latter offers a higher degree of automation and more validity
checking.
12.4.11 Additional materials
Additional materials for this sample are located in the examples/banking
directory of the additional materials for this redbook on the Web. Table 12-8
shows the organization of these files:
Table 12-8 Additional materials for banking example
File/Directory name
Description
banking.zip
Original example downloaded from
WebLogic.
http://e-docs.bea.com/wls/docs61/sample
s.html
dev
This directory contains modified code.
deploy
This directory contains deployed sample
in the exploded form. This is a resultant
directory after following steps outlined on
BEA site:
http://e-docs.bea.com/wls/docs61/dep
loyment/deploymentapp.html.
descriptors
This directory contains deployment
descriptors for EJB and Web modules and
for the application itself. These are copied
from the deploy directory once everything
is working. It also contains the
application-ear.xml file, which is used for
creating the EAR file.
bin
This directory contains Ant build files and
scripts. They are described in Table 12-9.
bin/log
This directory contains logs created by
individual scripts in the bin directory.
package
Contains the EAR file for deployment.
Chapter 12. Migration examples
315
File/Directory name
Description
wsad
Contains the EAR file for importing code in
WebSphere Studio Application Developer.
rmic
Contains the _rmic.cmd and src, build
directory used for creating stub and tie for
RMILoggerImpl.
Table 12-9 list the contents of the bin directory.
Table 12-9 Contents of bin directory
File name(s)
Description
setEnv.cmd
This is an altered version of setEnv.cmd
file available in
%WL_HOME%\config\mydomain. It adds
the deploy directory to the classpath.
generate_descriptors.cmd
This file generates deployment
descriptors for EJB and Web modules. It
also generates a deployment descriptor
for the banking application.
create_ear.cmd
This file creates the banking.ear file in the
package subdirectory for deployment
purposes and is a demo of how scripts can
be written for simple applications.
build.xml, build_ejb.xml and
build_web.xml
These files are described in detail below.
Ant build files:
򐂰 build.xml: The root build file is build.xml. It calls Ant with two other build files in
the directory, build_ejb.xml and build_web.xml.
The tasks defined in build.xml files are:
316
init
Creates build directory
package
Calls package task of EJB and Web module. Creates EAR
with only class files.
wsad
Calls wsad task of EJB and Web modules. Creates EAR with
only class files.
genDesc
Calls genDesc task of EJB and Web modules. Generates
application.xml
clean
Deletes build, package and wsad directories
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 build_ejb.xml:
init
Creates build/ejb directory
compile
Compiles source code in src/ejb and puts class files into
build/ejb
copyDesc
Copies descriptors from descriptors/ejb directory into
build/ejb/META-INF directory
package
Creates package/lib/ejb.jar
copySrc
Copies source from src/ejb directory build/ejb.
wsad
Creates wsad/lib/ejb.jar.
genDesc
Generates ejb-jar.xml, weblogic-cmp-rdbms-jar.xml and
weblogic-ejb-jar.xml
clean
Deletes build/ejb, package/lib/ejb.jar and wsad/lib/ejb.jar
򐂰 build_web.xml:
init
Creates build/web directory
compile
Compiles source code in src/web and puts class files into
build/web/WEB-INF/classes
copyWebRes
Copies resources from web/html and web/images folder to
appropriate location under build directory.
copyDesc
Copies descriptors from descriptors/web directory into
build/web/WEB-INF directory
package
Creates package/lib/web.jar
copySrc
Copies source from src/web directory
build/web/WEB-INF/classes.
wsad
Creates wsad/lib/web.jar.
genDesc
Generates web.xml and weblogic.xml
clean
Deletes build/web, package/lib/web.jar and wsad/lib/web.jar
Chapter 12. Migration examples
317
318
Migrating WebLogic Applications to WebSphere Advanced Edition V4
A
Appendix A.
Additional material
Note: Redpiece readers please note that the additional material is note
currently availble. It will nbe released when the book is published.
This redbook refers to additional material that can be downloaded from the
Internet as described below.
Locating the Web material
The Web material associated with this redbook is available in softcopy on the
Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG246179
Alternatively, you can go to the IBM Redbooks Web site at:
ibm.com/redbooks
Select Additional materials and open the directory that corresponds with the
redbook form number, SG 24-6179.
© Copyright IBM Corp. 2002
319
Using the Web material
The additional Web material that accompanies this redbook includes the
following files:
File name
sg246179.zip
Description
Zipped code samples
System requirements for downloading the Web material
The following system configuration is recommended:
Hard disk space:
Operating System:
40 MB
Windows NT or 2000
How to use the Web material
Create a subdirectory (folder) on your workstation, and unzip the contents of the
Web material zip file into this folder.
320
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Abbreviations and acronyms
API
Application Programming
interface
JNDI
Java Naming and Directory
Interface
BMP
bean-managed-persistence
JNLP
CMP
container-managed-persisten
ce
Java Network Launching
Protocol
JSP
JavaServer Pages
CTS
Compatibility Test Suites
JTA
Java Transaction API
DoS
Denial of Service
JTS
Java Transaction Service
EAR
Enterprise Application Archive
LDAP
EIS
Enterprise Information
Systems
Lightweight Directory Access
Protocol
RMI
Remote method invocation
EJB
Enterprise JavaBean
RMIC
RMI Compiler
EJB-QL
EJB Query Language
WLQL
WebLogic Query Language
ENC
Environment naming context
XMI
XML Metadata Interchange
HTML
HyperText Markup Language
XML
eXtensible Markup Language
HTTP
HyperText Transfer Protocol
IBM
International Business
Machines Corporation
IIOP
Internet Inter-ORB Protocol
ITSO
International Technical
Support Organization
J2EE
Java 2 Platform, Enterprise
Edition
J2SE
Java 2 Platform, Standard
Edition
JAAS
Java Authentication and
Authorization Service
JAF
Java Activation Framework
JAXM
Java API for XML Messaging
JAXP
Java API for XML Processing
JCA
J2EE Connector architecture
JDBC
Java database connectivity
JDK
Java Development Kit
JMS
Java Message Service
© Copyright IBM Corp. 2002
321
322
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks”
on page 325.
򐂰 WebSphere V3.5 Handbook, SG24-6161
򐂰 IBM WebSphere V4.0 Advanced Edition Handbook, SG24-6176
򐂰 WebSphere Version 4 Application Development Handbook, SG24-6134
򐂰 Migrating WebLogic Applications to WebSphere Advanced Edition,
SG24-5956
Referenced Web sites
These Web sites are also relevant as further information sources:
򐂰 Java 2 Platform, Enterprise Edition - J2EE 1.2 Compatibility
http://java.sun.com/j2ee/1.2_compatibility.html
򐂰 Java 2 Platform, Enterprise Edition - Compatibility
http://java.sun.com/j2ee/compatibility.html
򐂰 Java 2 SDK, Standard Edition V1.3.1 release notes
http://java.sun.com/j2se/1.3/relnotes.html
򐂰 WebSphere preview technologies - Other packages
http://www7b.boulder.ibm.com/wsdd/wspvtext-info.html
򐂰 Java Community Process
http://www.jcp.org
򐂰 DB2 Universal Database - product overview
http://www-3.ibm.com/software/data/db2/udb/
򐂰 Downloads BEA WebLogic Server
http://commerce.bea.com/downloads/weblogic_server.jsp
© Copyright IBM Corp. 2002
323
򐂰 WebSphere Application Server supported hardware and software
http://www.ibm.com/software/webservers/appserv/doc/latest/prereq.html
򐂰 WebSphere Application Server support
http://www-3.ibm.com/software/webservers/appserv/support.html
򐂰 IBM WebSphere Studio Workbench product overview:
http://ibm.com/software/ad/workbench/
򐂰 Home page of Eclipse.org:
http://www.eclipse.org
򐂰 J2EE Blueprints - Transaction management
http://java.sun.com/blueprints/guidelines/designing_enterprise_applications
/transaction_management/index.html
򐂰 J2EE Tutorial - Transactions
http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/Transaction.html
򐂰 Java Transaction API and BEA WebLogic Server extensions
http://e-docs.bea.com/wls/docs61/jta/jtaapi.html
򐂰 JSR 95: J2EE Activity Service for Extended Transaction
http://jcp.org/jsr/detail/95.jsp
򐂰 JSR 156: XML Transactioning API for Java (JAXTX)
http://jcp.org/jsr/detail/156.jsp
򐂰 Java Naming and Directory Interface architecture and features
http://robocode.alphaworks.ibm.com/docs/jdk1.3/guide/jndi/
򐂰 JNDI service providers
http://java.sun.com/products/jndi/serviceproviders.html
򐂰 Jakarta ORO
http://jakarta.apache.org/oro/index.html
򐂰 BEA WebLogic Server welogic.xml deployment descriptor elements
http://e-docs.bea.com/wls/docs61/webapp/weblogic_xml.html
򐂰 Apache Ant
http://jakarta.apache.org/ant/index.html
򐂰 Packaging BEA WebLogic Server J2EE applications
http://e-docs.bea.com/wls/docs61/programming/packaging.html
324
Migrating WebLogic Applications to WebSphere Advanced Edition V4
򐂰 BEA WebLogic Server assembling and configuring applications
http://e-docs.bea.com/wls/docs61/webapp/index.html
򐂰 ejbinfo.com
http://www.ejbinfo.com
How to get IBM Redbooks
You can order hardcopy Redbooks, as well as view, download, or search for
Redbooks at the following Web site:
ibm.com/redbooks
You can also download additional materials (code samples or diskette/CD-ROM
images) from that site.
IBM Redbooks collections
Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the
Redbooks Web site for information about all the CD-ROMs offered, as well as
updates and formats.
Related publications
325
326
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Index
Symbols
<ejb-ref> 152
<env-entry> 151
<resource-ref> 151
A
AAT 29, 101, 128, 175, 190, 208, 252, 255
access control 112
ACID 137
ACLs 114
adapters 23
Ant 13, 29, 108, 253, 305
Apache Jakarta project 109
Apache Software Foundation 109
applets 9
application
adaptable 3
configuration 9, 11
portability 2
application assembly 246, 248
Application Assembly Tool 67, 79, 101, 207–208,
252
application.xml 79, 121, 247, 254, 257
application_1_2.dtd 246
application-client.xml 247
application-client_1_2.dtd 248
artifacts 5, 9–10
audit 112
authentication 23, 112, 114
authorization 23, 116
browser 6
C
CDATA 219
classpath problems 275
classpaths 9
Client application 247–248
client-application-runtime.xml 248
Cloudscape 180
CMP 196, 218, 230, 242
field mappings 218
compileCommand 184
compileFlags 184
compilerclass 184
compilerSupportsEncoding 185
confidentiality 112
configuration 9
connection 141, 232
connection pooling 141, 232–233, 235–236
ConnectionFactory 24
ConnectionManager 233
container-managed persistence 196
containers 6, 195
Context.INITIAL_CONTEXT_FACTORY 203
Context.PROVIDER_URL 203
cookies 189
CORBA 150
CTS 18
CVS 63
D
B
banking example 267, 302
BEA WebLogic Server 4
features 18
installation 41
RDBMS Persistence 242
verification 42
best practices 3, 5, 32, 248
bindings 81, 104, 211
blueprint 267
BMP 242–243
© Copyright IBM Corp. 2002
data integrity 112
database 10, 137, 229, 237
database connection 149
DataSource 56, 92, 98, 141, 148–149, 151, 196,
232, 237–238, 284
close 236
connecting 234
getConnection 236
naming 233
DB2 37, 237, 280, 290
installation 37
verification 40
327
dbKona 240
DBMS 137
debug perspective 214
Denial of Service 111
dependencies 9–10
deployment 21, 98, 245, 255
EAR 191
generate code 88
secure EAR 132
deployment code 278
deployment descriptors 3, 9, 70, 79, 147, 151,
196–197, 204, 246, 292
application 246, 248, 257
Client application 248
conversion 164, 285
DTD 247
EJB 104, 248, 258
IBM extended 79
migration 257
naming 148
Pet Store 283
vendor extensions 156, 197, 248
Web 261
Web application 248
WebLogic extensions 157, 175, 205
WebSphere extensions 158, 206
development
environment 36
DHTML 107
DoS 111
dosetattribute 186
DriverManager 232–233, 237
DTD 246
E
EAR 4, 6, 9, 21, 29, 121, 128, 132, 191, 208, 214,
248, 255
deploy 191
export 97
import 72
EJB 3, 19, 137, 195, 230, 247, 255
2.0 24
deployment descriptors 104
editor 80
editors 79
field mappings 222
finders 83, 198, 218–219
home 148–149
328
IBM extension editor 80
JAR 105
query language 4
RDB mapping 84
references 81
test client 96
EJB JAR 214
EJB QL 24, 219
ejbBindings 207
EJBDeploy 101, 105, 255
ejb-jar.xml 81, 104, 123, 151, 204, 207, 215, 251,
269
ejb-jar_1_1.dtd 247
ejb-link 170
ejb-ref 205–206
ENC 151–152
encoding 184
Enterprise JavaBeans 3, 6, 70, 137, 195
environment variables 148–149
error pages 124, 178
errors 76
events 192
F
feature comparison 19
features 20
field mappings 219
fileRealm.properties 114
filter by resource 78
filter by type 77, 269
filters 192
finders 198, 218–219, 300
flat transactions 138
flexibility 11, 113
flush attribute 24
focus 5
H
home interface 198, 219, 251
HTML 9, 107
htmlKona 240
HTTP 6
I
ibm-application-bnd.xmi 124–125, 248
ibm-application-client-bnd.xmi 248
ibm-application-ext.xmi 80, 116, 124, 248, 257
Migrating WebLogic Applications to WebSphere Advanced Edition V4
ibm-ejb-access-bean.xmi 248
ibm-ejb-jar-bnd.xmi 80, 104, 125, 156, 207, 211,
248, 259, 261
ibm-ejb-jar-ext.xmi 80, 104, 248, 259, 261
ibm-ejb-jar-jdbc.xmi 219
ibm-ext-bnd.xmi 190
ibm-web-bnd.xmi 124, 156, 248, 262
ibm-web-ext.xmi 124, 190, 248, 262
IDE 13
IIOP 235
implementation levels 18
Informix 237
InitialContext 149, 202, 234–235
zero argument 203, 238
installation 35
BEA WebLogic Server 41
DB2 37
WebSphere Application Server 45
WebSphere Studio Application Developer 62
InstantDB 237
interoperability 113
interpretation 11
isModified 221
ISO-8859-1 269
isolation 113
J
J2C 19
J2EE 2, 15, 19, 125
1.2 18
1.2 features 20
1.2 specification 5
1.3 18, 21
application 248
application assembly 246
artifacts 9
business object standard 241
deployment 246
deployment descriptors 9
naming 148
naming context 149
security 112
specification 2, 9
transactions 135
J2EE Compatibility Test Suite 18
J2EE Connector architecture 23
J2EE perspective 214
J2SE 8, 12, 19
JAAS 8, 19, 23
JAF 8, 19
JAR 3, 9, 29, 250
Java 2 Platform, Enterprise Edition 2, 8, 68
Java 2 Platform, Standard Edition 8
Java Activation Framework 8
Java API for XML Messaging 8
Java API for XML Parsing 8
Java Authentication and Authorization Service 8
Java Data Objects 241
JDO 241
Java Message Service 8, 137
Java Naming and Directory Interface 3, 8
Java Network Launching Protocol 8
Java Servlets 6, 8–9, 19, 70, 107, 173, 176, 192
2.3 25
events 192
filters 192
mappings 175
Java Specification Request 25, 145
Java technologies 7
Java Transaction AP 8
Java Transaction API 136
Java Transaction Service 136
Java Transaction Services 233
java.rmi.AccessException 120
java.rmi.ServerException 120
JavaIDL 23
JavaMail 8, 19
JavaScript 107
JavaServer Pages 3, 6, 8–9, 70, 107, 173, 179, 193
parameters 184
XML syntax 193
JAXM 8
JAXP 8, 19, 23
JAX-RPC 8
JAXTX 145
JCA 19, 23
JDBC 8, 12, 19, 229–231
driver 48, 56, 92
driver properties 237
DriverManager 232
drivers 232
provider 98
RowSets 25
Standard Extension 8
jdbcKona 239
JDK 250
JDO 241
Index
329
jDriver 239
JMS 8, 19, 24, 137
JNDI 3, 8–9, 19, 21, 23, 81, 130, 141, 147–148,
197–198, 202, 205, 207, 232, 234, 283
environment variables 148
factory objects 148
futures 171
global name 154, 205
LinkRef 153
local name 154, 205
lookup 148, 202
migration 160
JNLP 8, 25
JRE 203
JSP 3, 19
1.2 24
editors 107
expression 183
jsp.repeatTag.ignoreException 187
JSR 25, 145
JSR 156 XML Transactioning API for Java 145
JSR 95 J2EE Activity Service for Extended Transaction 145
JTA 8, 19, 136, 237
JTS 136, 233
JUnit 29, 109
database 280
deployment descriptors 257
examples 14–15, 176, 265
guide 3
issues 10, 15, 19, 21, 237, 265
JDBC drivers 237
JNDI 160
process 15, 26, 265
project 30
staging 5
strategy 14, 17
tools 12, 14–15, 28
modules 249
N
keepgenerated 185
name overloading 160
naming 147, 284
context 148
convention 161
DataSource 233
deploy time binding 148
deployment descriptor 148
indirect lookup 148
J2EE standard 148
migration recommendations 166
overloading 160
Pet Store 284
portability 163
narrow 150, 198
L
O
LDAP 114, 235
lenient 20
load balancing 6
local beans 241
LTPA 114
objectives 2
Oracle 237
K
M
manifest 275
Map.mapxmi 248
mapping 84, 297, 310
meet in the middle 84
mappings 207
message-driven beans 24
META-INF 249
migration 280
basic steps 27
330
P
packagePrefix 185
packaging 251, 254
pageCheckSeconds 186
persistence 229–230
persistence manager 244
perspective 71, 214
debug 214
J2EE 72, 214
server 89
Web 214
Pet Store 267–268
deployment descriptors 283
Migrating WebLogic Applications to WebSphere Advanced Edition V4
naming 284
pilot 30
Pluggable Authentication Model 23
plug-in 53
generate 54
portability 2–3, 15, 113
JDBC 238
naming 163
PortableRemoteObject 150, 198
precompile 186
prerequisites 237
preview 18, 21
privacy 112
programming restrictions 11
projects 214
Q
quality 5
R
Redbooks Web site 325
Contact us xiii
references 251, 284
EJB 81
resource 82
remote interface 198
repudiation 112
requests 6
resource
references 82
resource adapters 23
resource managers 137
RMI 150, 231, 255–256, 311
RMI/IIOP 8, 19, 197
RMIC 88
rmic command 256
S
schema 84, 227
Schema.dbxmi 248
scripts 13
security 6, 9, 111, 196, 257
access control 112
audit 112
authentication 112
confidentiality 112
configuration 21
constraints 125
data integrity 112
deployment 132
flexibility 113
interoperability 113
isolation 113
J2EE 112
J2EE applications 125
non-repudiation 112
portability 113
privacy 112
realm 114
role mapping 257
transparency 113
using AAT 128
WebSphere Studio Application Developer 120
session 206
skills 30
SQL Server 237
SSL 116
staging directory structure 249
strict 20
stubs 255, 311
Sybase 237
syntax problems 268
T
tag libraries 9, 181, 188, 253
technology restrictions 11
test server 88
testing
banking example 313
environment 36
tier 6
ties 255, 311
tools 10, 12, 14–15, 28, 67, 101
AAT 101, 208
WebSphere Studio Application Developer 214
TopLink 231, 242–243
Trade2 267, 289
training 30
transactions 6, 135, 196
ACID properties 137
context 139
demarcation 139
flat 138
JTA 138
Non JTA 137
Index
331
one-phase 137
resource managers 137
synchronization 139
two-phase 138
WebLogic extensions 141
transparency 113
two-phase commit 138, 231
U
UDB 37
URL rewriting 188
user interface 6
user registry 114
user roles 116
user sessions 6
UTC 96
V
verbose 186
version mismatch 11
views 214
VisualAge for Java 70, 106
VisualCafe 30
W
WAR 9, 176, 190, 208
was40utils 164, 285, 294
Web application 247–248
Web perspective 214
Web server 9
Web services 8, 25, 69
web.xml 82, 122, 125, 151, 174, 187, 247
validation 175
web-app_2.2.dtd 125
web-app_2.3.dtd 125
web-app_2_2.dtd 174, 247
web-app_2_3.dtd 174
WebGain 30, 242
WEB-INF 249
WebLogic
RMI 165
WebLogic Query Language 219
weblogic.ant.taskdefs.ear.DDInit 254
weblogic.ant.taskdefs.ejb.DDInit 251
weblogic.ant.taskdefs.ejb20.DDInit 251
weblogic.ant.taskdefs.war.DDInit 251
weblogic.properties 233
332
weblogic.xml 156, 175, 190, 248, 262
weblogic-cmp-rdbms.xml 218
weblogic-cmp-rdbms-jar.xml 261
weblogic-ejb-jar.xml 156, 205, 248, 259
weblogic-rdbms-bean 219
WebSphere
plug-in 53
WebSphere Administrative Console 49, 114
WebSphere Application Server 4, 70
configuration 51
features 18
installation 45
verification 49
WebSphere Studio 107
WebSphere Studio Application Developer 28–29,
62, 67, 175–176, 187, 207, 214, 252, 255, 261
EJB editors 79
EJB field mapping 222
export EAR 97
filters 77
import EAR 72
installation 62
J2EE perspective 80
locate errors 76
perspective 71
projects 70, 214
security 120
test server 88
verification 65
WebSphere Studio Workbench 68
WebSphere Technology for Developers 18
WLQL 219
workingDir 186
X
XA 142
Xalan 23
XAResource 139, 141
Xerces 23
XMI 157
XML 9, 69, 108, 157, 190, 193, 219
editor 251
parsers 23
XML Metadata Interchange 157
XSLT 23
Migrating WebLogic Applications to WebSphere Advanced Edition V4
Migrating WebLogic Applications to WebSphere Advanced Edition V4
(0.5” spine)
0.475”<->0.875”
250 <-> 459 pages
Back cover
®
Migrating WebLogic
Applications to WebSphere
Advanced Edition V4
Understanding
migration issues and
preparing a
migration strategy
Guidelines for
writing portable
applications
Completing and
implementing a
migration
This redbook will help you plan and execute the migration of
Java 2 Platform, Enterprise Edition (J2EE) applications
developed for BEA WebLogic Server, so that they will run on
WebSphere Application Server, Advanced Edition V4. This
redbook is an update of the redbook Migrating WebLogic
Applications to WebSphere Advanced Edition, SG24-5956.
Since the previous redbook was published, new versions of
both WebLogic and WebSphere have been released and both
products have been certified as complying with the Java 2
Platform, Enterprise Edition specification. We discuss the
major differences between these new implementations of
WebLogic and WebSphere, provide guidance to developers on
how to deploy existing WebLogic applications on WebSphere,
and discuss how to design new J2EE applications that will be
portable for deployment on WebSphere or WebLogic.
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
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-6179-00
ISBN 0738425451

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