Migrating WebLogic Applications to WebSphere V5 Front cover

Front cover
Migrating WebLogic
Applications to
WebSphere V5
Understanding migration issues and
preparing a migration strategy
Guidelines for writing portable
applications
Implementing a
migration
Bill Moore
Leigh Power
ibm.com/redbooks
Redpaper
International Technical Support Organization
Migrating WebLogic Applications to WebSphere V5
January 2003
Note: Before using this information and the product it supports, read the information in
“Notices” on page vii.
First Edition (January 2003)
This edition applies to Version 5 of WebSphere Application Server.
Note: This book is based on a pre-GA version of a product and may not apply when the
product becomes generally available. We recommend that you consult the product
documentation or follow-on versions of this redbook for more current information.
© Copyright International Business Machines Corporation 2003. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The team that wrote this Redpaper . . . . . . . . . . . . . . . . . .
Become a published author . . . . . . . . . . . . . . . . . . . . . . . .
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.......
.......
.......
.......
......
......
......
......
. . . ix
. . . ix
...x
...x
Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Our objective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 How we wrote this paper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 How to use this paper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Chapter 2. J2EE standards and product features . . . . . . . . . . . . . . . . . . . . 5
2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 J2EE 1.3 standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3 Product features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.1 WebSphere Application Server V5 . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.2 WebSphere Studio Application Developer V5. . . . . . . . . . . . . . . . . . . 8
2.4 Selected features and migration examples . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5 Technology introductions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.1 Local beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.5.2 CMP 2.0 and CMR with cascade delete . . . . . . . . . . . . . . . . . . . . . . 12
2.5.3 MDB and Embedded JMS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.5.4 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.5.5 J2EE form-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 3. Migration tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2 Tools installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.2.1 WebSphere Studio Application Developer V5. . . . . . . . . . . . . . . . . . 21
3.2.2 WebSphere Application Server V5 . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.2.3 DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.3 WebSphere Studio Application Developer . . . . . . . . . . . . . . . . . . . . . . . . 25
3.3.1 Simplified folder structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.3.2 Import and export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.3.3 Project checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.3.4 Server folder checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
© Copyright IBM Corp. 2003. All rights reserved.
iii
3.3.5 Application client modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.3.6 Javadoc export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.3.7 Create new file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.3.8 Using type hierarchy browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.3.9 Finding Find/Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.3.10 Java Browsing perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.4 Deployment Descriptor editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.4.1 CMP 2.0 deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.4.2 Bind global JNDI name to EJB home . . . . . . . . . . . . . . . . . . . . . . . . 59
3.4.3 Bind local JNDI name to EJB reference . . . . . . . . . . . . . . . . . . . . . . 60
3.4.4 EJB QL finders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.4.5 Other deployment descriptor editors . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.4.6 RDB mapping with CMR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
3.5 Test server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
3.5.1 Test server setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
3.5.2 Create [CMP-ready] DataSource . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.5.3 Configure a JDBC provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.6 WebSphere Administrative Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.6.1 Launching the Administrative Console . . . . . . . . . . . . . . . . . . . . . . . 82
3.6.2 Administrative Console login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.6.3 Run the Administrative Console in test server . . . . . . . . . . . . . . . . . 84
3.6.4 Install EAR into WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.7 AAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
3.8 Automation tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Chapter 4. Migration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
4.2 Migration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.2.1 Learn the new tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.2.2 Verify baseline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.2.3 Stage source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.2.4 Portable shared JAR files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.2.5 Project and server folder checkpoints . . . . . . . . . . . . . . . . . . . . . . . 103
4.3 Follow the standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.3.1 PortableRemoteObject narrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.3.2 EJB references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.3.3 EJB references to local interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.3.4 Syntax and completeness errors. . . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.3.5 Invalid exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4.4 J2EE 1.3 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
4.4.1 Deployment of CMP 2.0 connection factory . . . . . . . . . . . . . . . . . . 113
4.4.2 Deployment of MDB/JMS listener port . . . . . . . . . . . . . . . . . . . . . . 113
4.4.3 Use of local interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
iv
Migrating WebLogic Applications to WebSphere V5
4.4.4 J2EE form-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
4.4.5 ejb-link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
4.5 Client portability issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.5.1 Lightweight application client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.5.2 The t3 protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
4.5.3 Portable JNDI InitialContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4.5.4 EJB interfaces and stubs for lightweight clients . . . . . . . . . . . . . . . 121
4.5.5 Portable environment variables in lightweight clients . . . . . . . . . . . 122
4.6 Data mapping issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.6.1 Impact of CMP 2.0 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.6.2 Decoupling database conversion . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Chapter 5. Migration examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.2 One2many example — CMP 2.0 with CMR . . . . . . . . . . . . . . . . . . . . . . 126
5.2.1 Verify baseline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5.2.2 Stage source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.2.3 Import source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
5.2.4 EJB 2.0 deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.2.5 Migrate application client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.2.6 Test and debug cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.2.7 Meet-in-the-middle RDB mapping . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.2.8 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
5.3 Message example — MDB and JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
5.3.1 Stage source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
5.3.2 Import source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
5.3.3 Deploy MDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
5.3.4 Configure JMS service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
5.3.5 Migrate client code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
5.3.6 Test cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
5.3.7 JMS queue variation on the message example . . . . . . . . . . . . . . . 186
5.3.8 Standard J2EE application client . . . . . . . . . . . . . . . . . . . . . . . . . . 194
5.3.9 Lightweight JMS client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
5.3.10 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
5.4 Filters example — servlet filters and authentication . . . . . . . . . . . . . . . . 203
5.4.1 Stage source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
5.4.2 Import source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
5.4.3 Deploy and test filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
5.4.4 Convert to portable form-based J2EE authentication . . . . . . . . . . . 220
5.4.5 Secure session tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
5.4.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Contents
v
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
System requirements for downloading the Web material . . . . . . . . . . . . . 238
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Related publications . . . . . . . . . . . . . . . . . . . . . .
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . .
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . .
IBM Redbooks collections . . . . . . . . . . . . . . . . .
......
......
......
......
......
.......
.......
.......
.......
.......
......
......
......
......
......
.
.
.
.
.
241
241
241
242
242
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
vi
Migrating WebLogic Applications to WebSphere V5
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. 2003. All rights reserved.
vii
Trademarks
The following terms are trademarks of International Business Machines Corporation and Lotus Development
Corporation in the United States, other countries, or both:
VisualAge®
Notes®
DB2®
WebSphere®
Redbooks(logo)™
IBM®
Word Pro
SP™
Lotus®
Tivoli®
MQSeries®
The following terms are trademarks of other companies:
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.
Other company, product, and service names may be trademarks or service marks of others.
viii
Migrating WebLogic Applications to WebSphere V5
Preface
This Redpaper is a preliminary discussion of some of the issues we expect that
developers will encounter when migrating Java 2 Platform, Enterprise Edition
applications from BEA WebLogic Server to WebSphere Application Server V5.
The Redpaper builds on the work done in the redbook Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179. We expect our
readers to be familiar with the contents of these IBM Redbooks. When we wrote
this Redpaper we were using a beta version of WebSphere Application Server
V5, so we have tried to identify only the major differences between WebLogic
and WebSphere, and to identify the areas that will have the highest likelihood of
providing migration challenges.
Our aim is to provide practical guidance to developers who have to deploy
existing WebLogic applications on WebSphere and to discuss how to design and
develop J2EE applications that will be portable and adaptable.
The team that wrote this Redpaper
This Redpaper 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 18 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.
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. Leigh is an author of two previous Redbooks on this topic.
© Copyright IBM Corp. 2003. All rights reserved.
ix
Thanks to the following people for their contributions to this project:
Ueli Wahli
International Technical Support Organization, San Jose Center
Mark Endrei
International Technical Support Organization, Raleigh Center
Eric Erpenbach
Roman Kharkoski
IBM USA
Wayne Beaton
IBM Canada
Wouter Denayer
IBM Belgium
Become a published author
Join us for a two- to six-week residency program! Help write an IBM Redbook
dealing with specific products or solutions, while getting hands-on experience
with leading-edge technologies. You'll team with IBM technical professionals,
Business Partners and/or customers.
Your efforts will help increase product acceptance and customer satisfaction. As
a bonus, you'll develop a network of contacts in IBM development labs, and
increase your productivity and marketability.
Find out more about the residency program, browse the residency index, and
apply online at:
ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us!
We want our papers to be as helpful as possible. Send us your comments about
this Redpaper 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:
x
Migrating WebLogic Applications to WebSphere V5
[email protected]
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 662
P.O. Box 12195
Research Triangle Park, NC 27709-2195
Preface
xi
xii
Migrating WebLogic Applications to WebSphere V5
1
Chapter 1.
Introduction
This chapter presents our focus and summarizes the contents of this Redpaper.
It also describes the process we used to identify migration issues and write this
paper.
© Copyright IBM Corp. 2003. All rights reserved.
1
1.1 Our objective
This Redpaper is the latest in a series on migrating J2EE applications from BEA
WebLogic Server to IBM WebSphere Application Server. The previous redbook,
Migrating WebLogic Applications to WebSphere Advanced Edition V4,
SG24-6179, focused on migrating applications from WebLogic V6.1 to
WebSphere V4.0. This paper is focused on migrating applications from
WebLogic V7.0 to WebSphere V5.0. Both of these products are J2EE 1.3
compliant servers.
The migration of an enterprise information system is generally an expensive,
complex activity that should not be taken lightly. We do not pretend to offer final
and comprehensive solutions. The best we can do with a Redpaper like this is
provide some guideposts and warnings for the real effort. We do this largely by
working through the details of several small migration examples. By describing
our experience and showing what tools we used, we hope to better prepare you
for tackling your own migration tasks.
This paper has the general goal of being a practical guide to J2EE professionals.
We identify specific migration issues and make specific recommendation
regarding the following:
򐂰 Migration tools.
򐂰 Migration process.
򐂰 Best practices — making applications more portable and more adaptable.
1.1.1 Limitations
This paper differs somewhat from our previous efforts in its scope and timing. By
writing this paper earlier in the product cycle, we have accepted the following
limitations. Please keep these limitations in mind as you use this paper.
򐂰 This paper is organized as an update to Migrating WebLogic Applications to
WebSphere Advanced Edition V4, SG24-6179. We try not to repeat
information that is still relevant. You may wish to have a copy of the earlier
redbook available for reference.
򐂰 We have used beta versions of WebSphere and its tools. The released
version of these products will have corrections and improvements, so expect
minor differences when following our examples.
򐂰 This is a smaller paper with less comprehensive coverage. Technically, we
have tried to choose an interesting subset of:
򐂰 New features of J2EE 1.3.
򐂰 New features of WebSphere Studio Application Developer.
2
Migrating WebLogic Applications to WebSphere V5
1.2 How we wrote this paper
This paper is organized around the migration of a set of examples.
1. Based on our knowledge of J2EE 1.3, we selected a small set of examples
that cover an interesting subset of new features in J2EE 1.3. This subset was
also constrained by available resources.
2. We migrated each example using the tool set of WebSphere Studio
Application Developer, along with several other tools. In the process, we
documented:
򐂰 The step-by-step migration process.
򐂰 Our specific use of tools.
򐂰 The migration issues we identified along the way.
3. As a last step, we analyzed, categorized, and expanded on the migration
issues we encountered.
1.3 How to use this paper
Of course we hope you take the time to read the entire paper, but depending on
your time and interest, each chapter can be read separately. Each chapter’s
contents should be obvious from its name.
򐂰 Chapter 2, “J2EE standards and product features” on page 5, highlights new
features in the J2EE 1.3 specifications, and new features in the WebLogic and
WebSphere products. This chapter also identifies the subset of features
chosen for our migration examples.
򐂰 Chapter 3, “Migration tools” on page 19, presents our use of the migration
tools. It also includes their installation. Read this chapter if you are interested
in the new look and feel, and the new features of WebSphere Studio
Application Developer.
򐂰 Chapter 4, “Migration issues” on page 97, lists and analyzes the migration
issues we discovered. By itself, this chapter provides our results without
saying how we got there. It also includes advice on portability and best
practices.
򐂰 Chapter 5, “Migration examples” on page 125, presents the migration
examples, step-by-step. If you plan to do a real migration, this chapter offers
detailed examples on how to proceed.
Chapter 1. Introduction
3
4
Migrating WebLogic Applications to WebSphere V5
2
Chapter 2.
J2EE standards and product
features
This chapter sets the context for the rest of the Redpaper. We select a few J2EE
1.3 features for study, and identify examples to help us discover associated
migration issues. We then outline the technologies used by these examples.
© Copyright IBM Corp. 2003. All rights reserved.
5
2.1 Introduction
J2EE 1.3 encompasses a rich set of new features, far too many to cover in
depth. Given our focus, we quickly selected an interesting subset of features to
study for potential migration problems. This was done in parallel with choosing a
few small migration examples that exercise the features. We chose examples
that were designed to run on WebLogic V7. This chapter presents the results of
this selection process.
򐂰 Features that are new to J2EE 1.3.
We list only the new features here. Some of these are covered briefly in the
previous redbook, but you should refer to official specifications for detailed
coverage.
򐂰 WebLogic and WebSphere server products and tools.
Migration is all about differences in implementation and tools support. We list
the kinds of differences we look for, and survey the new features of the
supporting tools.
򐂰 J2EE 1.3 features selected for study.
This is the results of our selection process. We introduce the underlying
technologies and identify the specific migration examples.
2.2 J2EE 1.3 standards
Table 2-1 lists the J2EE 1.3 technologies and their version levels. This table is
adapted from Chapter 2 of Migrating WebLogic Applications to WebSphere
Advanced Edition V4, SG24-6179. A short description of each technology can be
found there.
Table 2-1 J2EE 1.3 technologies
Technology
6
WebSphere
V5.0
WebLogic
7.0
Java 2 Platform, Enterprise Edition (J2EE)
1.3
1.3
Java 2 Platform, Standard Edition (J2SE)
1.3.1
1.3.1
Enterprise JavaBeans (EJB)
2.0
2.0
JavaServer Pages (JSP)
1.2
1.2
Java Servlets
2.3
2.3
Java Authentication and Authorization
Service (JAAS)
1.0
1.0
Migrating WebLogic Applications to WebSphere V5
Technology
WebSphere
V5.0
WebLogic
7.0
1.0.1
1.0.1
JavaMail
1.2
1.1.3
Java API for XML Parsing (JAXP)
1.1
1.1
J2EE Connector Architecture (JCA)
1.0
1.0
JDBC Standard Extension (JDBC)
2.0
2.0
1.0.2
1.0.2
part J2SE 1.3
part J2SE 1.3
1.0.1
1.0.1
part J2SE 1.3
part J2SE 1.3
Java Activation Framework (JAF)
Java Message Service (JMS)
Java Naming and Directory Interface (JNDI)
Java Transaction API (JTA)
RMI-IIOP
The following is a list of significant new features in J2EE 1.3. This is not a
comprehensive list of new features. It includes features we believe offer the most
value to migration efforts. We used this list as a starting point for selecting
migration examples. See 2.5, “Technology introductions” on page 10, for the
specific technologies used in our examples.
򐂰 EJB 2.0 features:
–
–
–
–
–
–
Local beans.
CMP 2.0.
Container managed relationships (CMR).
EJB subclassing.
EJB QL.
Message-driven beans (MDB).
򐂰 JSP and Servlets:
–
–
–
–
–
Filters and events.
Dynamic XML parsing (JAXP).
JSP flush, iteration, try/catch, tag library validator.
Tag library standardization.
Form-base authentication.
򐂰 Other J2EE 1.3 features:
–
–
–
–
Improved inter-server interoperability.
Authentication and security (JAAS).
Connectors (JCA).
CMP improvements.
Chapter 2. J2EE standards and product features
7
2.3 Product features
Both the BEA WebLogic Server V7.0 and the WebSphere Application Server
V5.0 fully comply with the J2EE 1.3 specifications. From a migration perspective,
we expect that these features will work as advertised. For migrations, we are
more interested in answering the following kinds of questions:
򐂰 Are there any incompatibilities in the standard deployment descriptors?
򐂰 Are there significant differences in the extended deployment descriptors?
򐂰 What is required to get a typical WebLogic example imported into WebSphere
Studio Application Developer for migration?
򐂰 What is required to migrate deployment descriptors?
򐂰 To what extent do typical WebLogic applications embrace the J2EE 1.3
standards?
Both of the WebLogic and WebSphere servers also support and promote the
popular new area of Web services. Since the standards in this area are rapidly
changing, we chose not to cover the migration of Web services in this paper.
2.3.1 WebSphere Application Server V5
Although the WebSphere Studio Application Developer tool set satisfied most of
our migration needs, we also used the WebSphere Administrative Console of
WebSphere Application Server V5. The following features are noticeable
improvements to WebSphere Application Server V5:
򐂰 DB2 is not required for WebSphere V5.
򐂰 The WebSphere Administrative Console is browser based.
򐂰 WebSphere V5 includes Embedded Messaging JMS support.
2.3.2 WebSphere Studio Application Developer V5
WebSphere Studio Application Developer V5 is our primary migration platform.
By comparison with V4 of this product, it has more tools and a new look and feel.
򐂰 Full support for both J2EE 1.2 and J2EE 1.3 applications.
򐂰 Full support for both WebSphere V4 and WebSphere V5.
򐂰 A new look and feel, based on Eclipse 2.0.
Most of the contents of Chapter 3, “Migration tools” on page 19, are devoted to
WebSphere Studio Application Developer. It covers the following:
򐂰 Tools we found handy during migrations.
򐂰 Specific instructions on how to locate and use various features.
򐂰 Examples of the new look and feel.
8
Migrating WebLogic Applications to WebSphere V5
Here is a list of its new file types, projects, perspectives, and wizards. This list
provides a quick survey of the new WebSphere Studio Application Developer
features. We cover a few of these new features in Chapter 3, “Migration tools” on
page 19.
򐂰 New file types for import or export:
– Existing project into workspace for ClearCase source control.
– External plug-ins and fragments for the Plug-in Development Environment
(PDE).
– HTTP Recording for creating HTTP test cases.
– RAR file for resource adapters for connection architecture.
– Symptom database file for application profiling (database).
– Team project set for sharing resources under version control.
– WebSphere log file for application profiling based on XML symptom
database.
– XML log file for application profiling.
– Javadoc for generating Javadoc files.
򐂰 New perspectives:
– Java browsing supports Java development with a VisualAge for Java look
and feel.
– Component test supports design, execute, and analysis of test cases.
– CVS repository exploring support team programming.
– Install/update manages eclipse updates.
– XSL debug supports XSL debugging.
– Help is gone — it has been integrated with Search.
– Scripts are gone.
򐂰 New project types:
– J2EE Connector Project.
– Plug-in Feature Project Development replaces Plug-in Component Project.
򐂰 New wizards:
– Component Test wizard for TestCase and Host.
– Data wizard for Java Stored Procedure, SQL Stored Procedure, MQSeries
User-Defined Function, and SQL User-Defined Function.
– J2EE Connector Project wizard.
– Java Source Folder wizard.
Chapter 2. J2EE standards and product features
9
– Java JUnit — TestCase and TestSuite wizards.
– Symptom Database wizard.
– Web — Life-cycle Listener, and Filter wizards.
– Web Services — DADX (create file) and Unit Test UDDI wizards.
– XML — Java Bean XML/XSL Client, XPath, XSL Debug and Transform,
and Compile wizards.
– XSL wizard.
– Various updated wizards for editing deployment descriptors.
2.4 Selected features and migration examples
For Chapter 5, “Migration examples” on page 125, we chose three examples
from the WebLogic V7 distribution. Together, these examples cover six of the
new J2EE technologies listed above, in addition to one of the new WebSphere
Application Server features. With all of the related deployment descriptors and
server configurations, these three small examples generated a lot of migration
issues. We also addressed migration issues of lightweight and standard J2EE
application clients. For a complete list of the issues, see Chapter 4, “Migration
issues” on page 97.
1. One2many example:
– Local beans.
– CMP 2.0 with CMR.
– CMR and cascade delete.
2. Message example:
– MDB using WebSphere Embedded JMS.
3. Filters example:
– Filters.
– J2EE form-based authentication.
2.5 Technology introductions
This section contains a very high level introduction to the technologies used by
our migration examples. Please refer to the appropriate specifications and
product documentation for complete details.
10
Migrating WebLogic Applications to WebSphere V5
2.5.1 Local beans
EJB local interfaces are part of the EJB 2.0 specification.
Local beans are collocated in the same JVM as their clients. They eliminate
network latency and support a more tightly coupled programming model. In
particular, CMR requires local beans. Strictly speaking, a bean is not local.
Instead, a bean may have local home and component interfaces. Indeed, a bean
can have both remote and local interfaces, but normally only one or the other
makes sense. Session, entity, and message-driven beans can have local
interfaces.
Programming model
Compared with remote interfaces, the programming model for local interfaces
has the following important differences:
򐂰 The pass by reference protocol is used for parameters that are passed into
and returned from methods in local interfaces. Restrictions apply regarding
sharing of these parameters.
򐂰 Local interface methods must not throw a RemoteException. This exception
only makes sense for remote interfaces.
Clients must continue to obey the following protocols with local interfaces:
򐂰 Local method calls are still handled indirectly through the container, so the
container continues to manage security, transactions, and other EJB services.
Therefore, clients must only invoke methods through a bean’s interface
definition. Direct method invocation is invalid.
򐂰 Clients must continue to use local JNDI lookups and EJB references to
access local homes. However, the PortableRemoteObject narrow casting
protocol is not required, because remote stubs are not present.
Declaration and deployment
Local home and component interfaces are declared by extending the following
new interface types, respectively:
򐂰 EJBLocalHome.
򐂰 EJBLocalObject.
The EJB classes continue to extend the Entity type.
Deployment of local interfaces is supported by the following new deployment
descriptors:
򐂰 Local home and component interfaces must be deployed using, respectively:
– local-home
Chapter 2. J2EE standards and product features
11
– local
򐂰 Clients of local interfaces must deploy their EJB references with ejb-local-ref.
Since local interfaces are not available remotely, the following issues arise:
򐂰 Are the extended deployment descriptors for global JNDI names still needed?
򐂰 Can the standard ejb-link deployment descriptor be used instead?
Each vendor has taken a different position on these issues. We discuss them in
4.4.5, “ejb-link” on page 115.
2.5.2 CMP 2.0 and CMR with cascade delete
CMP 2.0 is part of the EJB 2.0 specification.
By comparison with CMP 1.x, the major features of CMP 2.0 are:
򐂰 Container Managed Relationships (CMR), including the following options:
– One-one, one-many, and many-many
– Uni-directional and bi-directional
– Cascade delete — instance deleted when relation deleted
򐂰 Container management of fields — in effect, CMF.
The deployment descriptors define an abstract persistence schema that includes
fields and relationships. The container manages their representation and data
mapping. The developer provides an abstract class for the entity, and the
container generates a concrete implementation as a subclass. Fields are no
longer defined in the entity’s Java code.
EJB 2.0 supports both CMP 2.0 and CMP 1.x, so each entity must declare which
model it uses.
Programming model
In addition to using abstract classes, developers must use local interfaces,
provide abstract setters and getters, and adhere to other restrictions.
򐂰 Relationships
– If an entity is the target of a relationship, it must use a local interface.
Being a target means that you can navigate to the bean by means of a
relationship.
– Collection and Set types are used for one-many and many-many
relationships.
– Local interface types, and their collections, can only be used for the types
of relationships. They cannot be used as the types of CMP fields.
12
Migrating WebLogic Applications to WebSphere V5
򐂰 Fields
– CMP fields and relationships are virtual, and must be represented in the
bean as getters and setters. In this context, virtual means they are
implemented in the container.
– Getters and setters are abstract methods with prescribed names.
Concrete implementations are provided by the container.
򐂰 There are other restrictions and features:
– RemoteException, deprecated in EJB 1.1, is now outlawed.
– Setter and getters, among other things, must not be exposed through
remote interfaces.
– Entity beans and their interfaces may have superclasses and super
interfaces, respectively.
FInders and selectors have a similar programming model:
򐂰 Queries are specified by deployment descriptors using the new EJB QL.
򐂰 Queries range over the fields and relationships of the abstract persistence
schema.
򐂰 The container generates all code.
Declaration and deployment
Relationship and field names must be valid Java identifiers and must have initial
lowercase. You must use deployment descriptors to define relationships and
fields. Together, these definitions make up the abstract persistence schema.
򐂰 A field is defined by the cmp-field in the entity descriptor, just as for CMP 1.x.
򐂰 A relationship is defined by the new cmr-field in the new ejb-relationship-role
descriptors.
Here are a few of the other new deployment descriptor elements for CMP 2.0:
򐂰
򐂰
򐂰
򐂰
򐂰
cmp-version
relationships
ejb-relation
multiplicity
cascade-delete
2.5.3 MDB and Embedded JMS
Message-driven beans are part of the EJB 2.0 specification. The Embedded
Messaging JMS support is described in the WebSphere V5 documentation. The
WebSphere Studio Application Developer help also provides information on the
internal WebSphere JMS.
Chapter 2. J2EE standards and product features
13
An MDB is an asynchronous message consumer of JMS messages. The
purpose of an MDB is to make it easy to build a JMS Message Listener. An MDB
is invoked by the container whenever a JMS message arrives for the bean. An
MDB client program is just a JMS client program. It has no special knowledge
about the consumer of the messages it produces.
Programming model
An MDB is similar to a stateless session bean in that it has no conversational
state. Session beans, however, cannot be used as JMS Message Listeners. An
MDB must implement the following interfaces:
򐂰 javax.ejb.MessageDrivenBean.
򐂰 javax.jms.MessageListener.
An MDB has the following special features:
򐂰 It has no home interface and no component interface. Except for JMS
messages, an MDB is basically invisible to the outside world. There is no way
to call it.
򐂰 The heart of an MDB is its onMessage method. The container calls this
method once for each JMS message, and passes in the message for
processing.
򐂰 An MDB must not throw application exceptions or the RemoteException.
򐂰 Message acknowledgment is handled by the container, so it should not be
implemented in the MDB itself.
An MDB client knows nothing about the MDB. It just generates JMS messages
for a JMS provider service. It uses JNDI to locate its JMS connection factory and
destination objects.
Declaration and deployment
Messaging models are publish/subscribe or point-to-point. Configuring and
deploying an MDB requires some knowledge of JMS concepts. For example, a
destination can be either a queue or a topic destination. A highly reliable service
might be configured as a durable queue, as opposed to a nondurable topic.
Here are some of the standard deployment descriptor elements for MDBs:
򐂰
򐂰
򐂰
򐂰
򐂰
14
message-driven
message-driven-destination
acknowledge-mode
subscription-durability
message-selector
Migrating WebLogic Applications to WebSphere V5
Extended deployment descriptors depend on the vendor. In general, an extended
descriptor is needed to tell the container how to connect an MDB to its JMS
provider and destination. WebLogic and WebLogic use different approaches. We
discuss this in 4.4.2, “Deployment of MDB/JMS listener port” on page 113.
2.5.4 Filters
Filters are described in the Java Servlet 2.3 specification.
Filters improve the modularization of certain kinds of general-purpose Web
processing, such as authentication, logging, auditing, compression, and
encryption.
򐂰 Each filter is mapped to a servlet or a URL pattern.
򐂰 A filter gets control before and after the invocation of its mapped resource.
– It can perform pre- and port-processing of the HTTP ServletRequest and
ServletResponse objects.
– It can block the invocation of the mapped resource altogether.
򐂰 A chain of filters for the same resource is invoked in a nested fashion with the
associated resource being the innermost invocation.
Programming model
A filter must implement the javax.servlet.Filter interface.
The doFilter method is the heart of a filter. It is passed the following parameters:
򐂰 The ServletRequest object.
򐂰 The ServletResponse object.
򐂰 A FilterChain object, which supports the invocation of the next filter in the
chain, or of the mapped resource itself.
A doFilter method is responsible for invoking doFilter on the FilterChain object in
order to complete the chain. It blocks completion of the chain by just not invoking
doFilter on the FilterChain object. Pre- and post-processing correspond to
processing before and after the invocation of the nested doFilter method.
Declaration and deployment
FIlters are packaged in the Web Archive along with static content and servlets.
A filter must be declared in the web.xml deployment descriptor file along with its
resource mapping. The order of invocation of filters for a particular resource
follows the order of their declaration in the deployment descriptor.
Chapter 2. J2EE standards and product features
15
Here are the major standard deployment descriptor elements for filters:
򐂰 filter
򐂰 filter-class
򐂰 filter-mapping
2.5.5 J2EE form-based authentication
Form-based authentication is described in the Java Servlet 2.3 specification.
This feature provides a portable implementation of the common
user ID/password Web authentication protocol.
򐂰 Developers control the look and feel of the login screen by writing two pages:
– A login page.
– A login error page.
򐂰 The container handles the authentication logic:
– Check user's authentication on attempt to access a protected resource.
– If user has not been authenticated yet, present login page, and error page
if needed.
– Use container-defined authentication mechanism.
– Redirect request to resource only if authenticated.
Programming model
The Web developer designs the login and login error pages using the HTML form
construct. These can be HTML or JSP pages. The standard requires the use of
the following specific identifiers:
򐂰 j_username and j_password for the named fields in the form.
򐂰 j_security_check for the form action.
Declaration and deployment
Two standard deployments and one extended deployment are needed:
򐂰 Standard deployment of form-based authentication.
򐂰 Standard deployment to define protected resources.
򐂰 Extended deployment to bind protected resources to the container-provided
authentication mechanism.
Standard deployment of the form uses the following descriptor elements:
򐂰 login-config
򐂰 form-error-page
򐂰 form-login-page
16
Migrating WebLogic Applications to WebSphere V5
Standard deployment of a protected resource uses the following descriptor
elements:
򐂰 security-constraint
򐂰 role-name
WebSphere extended deployment involves the following:
򐂰 Enable security.
򐂰 Bind role-name to authentication mechanism.
See “Do WebSphere part of deployment” on page 227 for details on extended
deployment for WebSphere.
Chapter 2. J2EE standards and product features
17
18
Migrating WebLogic Applications to WebSphere V5
3
Chapter 3.
Migration tools
This chapter describes tools used to help migrate BEA WebLogic Server
applications to WebSphere Application Server. WebSphere Studio Application
Developer is our tool of choice for this task. We also describe other useful tools,
and provide a brief list of promising automation tools.
© Copyright IBM Corp. 2003. All rights reserved.
19
3.1 Introduction
This chapter describes tools and procedures that we found useful for migrating
the examples in Chapter 5, “Migration examples” on page 125. Most of these
tools are in WebSphere Studio Application Developer. They should be useful for
any major migration effort.
This chapter is an update to Chapters 3 and 4 of Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179. We try not repeat
content that has not changed for WebSphere Studio Application Developer V5.
We include the following:
򐂰 New features of the tools that we used.
򐂰 Old features that we used and have changed significantly, possibly just with
regard to their look and feel.
򐂰 A few additional new features we did not use, but think some users will find
appealing.
Although we cover a lot of material, this is not a reference book. You should refer
to the appropriate product documentation for complete, up-to-date features and
details. Also keep in mind that we used beta versions of software for our work.
The release versions of these tools will undoubtedly be different in some details.
In particular, you may find differences in various menu options, tabs, and page
layouts. We have documented a few defects that are most probably beta defects.
Hopefully, you will not see them in the release products, but if you do, you will
know how to overcome them.
This chapter has been organized into the following sections:
1. Tools installation.
We had very few problems installing the tools, so this is a short section.
2. WebSphere Studio Application Developer.
Most of this chapter is about features we used in WebSphere Studio
Application Developer V5, so this is a large section. You may just want to skim
this material at first, and then study details of individual tasks when they are
referenced in the context of the migration examples.
3. WebSphere Studio Application Developer test server.
We found that most of our testing could be done with the WebSphere Studio
Application Developer test server. In general, we do not cover the
corresponding tasks in WebSphere Application Server.
20
Migrating WebLogic Applications to WebSphere V5
4. WebSphere Administrative Console.
We provide a glimpse of the new browser-based Administrative Console of
WebSphere Application Server V5. This console is also available from within
WebSphere Studio Application Developer, and is the only way to perform
certain WebSphere Studio Application Developer test configurations. We
used WebSphere more extensively in 5.3.7, “JMS queue variation on the
message example” on page 186, so you may wish to skim that section too.
5. Application Assembly Tool (AAT).
We give just a glimpse.
6. Automation tools.
A short list of other promising migration technologies.
3.2 Tools installation
For the most part, the tools installed without problems. Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179 should be
referenced for details of these installations. We mention a few items here that are
new, or are common errors that we bumped into.
3.2.1 WebSphere Studio Application Developer V5
Since our installation of the beta version of this software did not follow the
standard installation process, we do not describe it here. However, based on past
experience, this is a straightforward, error-free process. Be patient. It takes a
while to install.
The underlying Eclipse 2.0 has a different look and feel. See the new startup
window in Figure 3-1 on page 22.
Chapter 3. Migration tools
21
Figure 3-1 WebSphere Studio Application Developer based on Eclipse 2.0
3.2.2 WebSphere Application Server V5
A major difference in installation is that you do not have to install DB2.
WebSphere V4 required DB2 as a prerequisite. WebSphere V5 uses flat files for
configuration objects, so DB2 is not required.
You must enter a user ID/password during installation. This is used for Windows
services for the application server and for the HTTP server. Make sure this
account has administrator privileges and the following user rights:
򐂰 Can act as part of the operating system.
򐂰 Log on as a service.
We had a problem getting the Installer.exe to launch by simply double-clicking
the Install.bat. It could not find the JVM. This appears to be a Windows-related
problem that some users experience. We used the following workaround:
1. Open a command prompt.
2. cd to the folder containing the Install.bat script.
3. Enter the Install command in the command prompt.
22
Migrating WebLogic Applications to WebSphere V5
Be patient. The install takes a while, and there are some long pauses. Figure 3-2
on page 24 lists all of the features that install with the typical installation.
Embedded Messaging supports the new MDBs. You may want to take a look at
the distributed CMP 2.0 and MDB samples when you complete the install.
One of the first things you will notice about WebSphere V5 is its new
browser-based Administrative Console. See Figure 3-45 on page 82 for its initial
Web page.
Chapter 3. Migration tools
23
Figure 3-2 WebSphere Application Server V5 installed features
24
Migrating WebLogic Applications to WebSphere V5
3.2.3 DB2
We installed DB2 for testing the one2many example. As mentioned above, it is
no longer needed for WebSphere Application Server V5. The installation follows
the instructions in Migrating WebLogic Applications to WebSphere Advanced
Edition V4, SG24-6179. Two aspects of this installation deserve emphasizing:
򐂰 Make sure the installation account has administrative privileges and supports
the following user rights.
–
–
–
–
Act as part of the operating system.
Create token object.
Increase quotas.
Replace a process level token.
򐂰 After the installation, follow the instructions to upgrade the installation to use
the JDBC 2.0 driver:
a. Stop all DB2 services.
b. Run the usejdbc2.bat script located in the java12 folder.
c. Restart the DB2 services.
3.3 WebSphere Studio Application Developer
This section, along with the next two sections, describe WebSphere Studio
Application Developer V5 tasks that we found helpful during our migration efforts.
Most of the detailed examples come directly from Chapter 5, “Migration
examples” on page 125. They are collected here for easy reference.
This is an update of similar tasks found in Chapter 4 of Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179.
򐂰 Unchanged tasks.
The following tasks are essentially unchanged and are therefore not detailed
in this Redpaper:
–
–
–
–
Import and export EAR.
Locate errors using the task list.
Filter task messages by type and by resource.
Generate deployment code.
򐂰 Changed tasks.
The following tasks are updated here because of content or look and feel:
–
–
–
–
EJB deployment editors.
Create finders.
RDB mapping.
Test server setup.
Chapter 3. Migration tools
25
– DataSource creation.
򐂰 New tasks.
These tasks are new, either because they support new product features, or
because we recently discovered their usefulness for migrations efforts.
– Specialized uses of import and export:
•
•
•
Project and server checkpoints.
Application client JARs.
Javadocs.
– Create new file.
– Browsing type hierarchies.
– Find/Replace.
– Configuring JDBC providers.
3.3.1 Simplified folder structure
WebSphere Studio Application Developer V5 has simplified the EJB folder
structure. In the J2EE Navigator, you will notice the following changes:
򐂰 The bin folder is gone for EJB projects.
This is a major improvement that normalizes the organization of EJB projects
with that of Java projects. In V4, there were two major folders — bin and
ejbModule. They had duplicate structures and were easily confused. The bin
was for compiled classes, while the ejbModule was for source code. A
modification to a deployment descriptor, erroneously made in the bin folder,
was easily lost.
In V5, class files and Java files are combined into the same folder. The class
files are not visible in the J2EE Navigator, but are visible in the Resource
Navigator. Figure 3-17 on page 46 shows a simple J2EE Navigator view.
Figure 3-15 on page 42 shows a simple Resource Navigator view with class
files. Also notice that the compact icon
is used for packages in the J2EE
Navigator instead of the expanded folder structure.
򐂰 The JAR files have been added to the J2EE Navigator view.
򐂰 The EJB meta-inf folder has replaced the V4 Schema folder. It has data
mapping folders nested within a new back-ends folder. There can be multiple
data mappings with the back-ends folder. See Figure 5-13 on page 193 for an
example.
򐂰 In Web application projects, you will notice the following changes:
– The source folder has been replaced by the Java Source folder.
– The webApplication folder has been replaced by the Web Content folder.
26
Migrating WebLogic Applications to WebSphere V5
– The
icon is used in Web Content folders.
3.3.2 Import and export
As mentioned in 2.3.2, “WebSphere Studio Application Developer V5” on page 8,
there have been some additions to the files types for import and export.
Figure 3-3 shows the updated import selection window. Figure 3-4 on page 28
shows the updated export selection window. As you can see, these windows look
very much like their V4 counterparts, but there are more file types.
Figure 3-3 File Import types
Chapter 3. Migration tools
27
Figure 3-4 File Export types
The basic steps for import and export are unchanged. They are described in
Chapter 4 of Migrating WebLogic Applications to WebSphere Advanced Edition
V4, SG24-6179. In this paper, we describe several useful tasks that are based on
import and export.
򐂰 Project checkpoints.
Although you can do this in V4, deleting a J2EE application project in V5 can
also delete all of its dependent projects. This is a handy new feature.
28
Migrating WebLogic Applications to WebSphere V5
򐂰 Server folder checkpoints.
Although Server Configuration is one of the new Import types, we describe an
alternative approach to checkpointing server folders that we prefer.
򐂰 Import and export of an application client module.
This is not new, but we did not cover it in Migrating WebLogic Applications to
WebSphere Advanced Edition V4, SG24-6179. In this paper, we cover an
example of a lightweight application client that uses this feature.
򐂰 Javadoc export.
This is a new feature.
Missing ID in application.xml file — beta defect
We did have one problem importing EAR files that is worth mentioning. This
problem does not exists in WebSphere Studio Application Developer V4. We
assume that it is just a V5 beta system problem, so you probably will not
experience it.
As described in Chapter 7 of Migrating WebLogic Applications to WebSphere
Advanced Edition V4, SG24-6179, standard IBM deployment descriptors use
optional ID fields to support the various extended deployment descriptors. For
example, the <application> stanza of the application.xml file requires an ID field
so that ibm-application-ext.xmi and ibm-application-bnd.xmi files can reference it.
If not present, these IDs are automatically added by the WebSphere Studio
Application Developer import operation. Unfortunately, this did not happen for the
<application> stanza. If this ID is eventually needed, WebSphere Studio
Application Developer reports a validation error for the application deployment
descriptor, but provides no additional information. Although this error appeared to
cause no problems, we chose to correct it by manually adding the missing ID
field as shown in Example 3-1.
Example 3-1 Manually added ID field to <application> stanza — presumed beta defect
<application id=”Application_foobar”>
3.3.3 Project checkpoints
For the limited purpose of experimenting with WebSphere Studio Application
Developer V5 and writing this paper, we chose not to use a source management
system. Instead, we made use of the export and import services to create and
revert back to project checkpoints. You may find this handy for experimentation
and evaluation. It could also be useful in real migration projects.
An exported EAR includes the J2EE project along with all of its related projects
— EJB, Web, and application client. Importing an existing EAR will restore the
Chapter 3. Migration tools
29
original J2EE application project along with its related projects. Make sure to
include source code in EAR files so the source is available for modification after
being imported.
When you wish to revert to a previously checkpointed EAR, first make sure that
the existing application project is completely deleted from the WebSphere Studio
Application Developer workspace. This is accomplished as follows:
1. Stop the server in the server perspective — see Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179.
2. Switch to the J2EE Navigator perspective.
The J2EE Navigator ensures that the subsequent delete operation will delete
the application project along with all related projects.
3. Select the J2EE application project.
4. Right-click and select Delete.
5. Select Also delete module and utility Java projects and click OK — see
Figure 3-5.
Optionally click Details to select specific projects to delete.
6. Select Also delete contents in the file system and click Yes — see
Figure 3-6 on page 31.
The result is a clean workspace into which you can re-import an EAR of the
same or different application project, without name conflicts.
Figure 3-5 Delete J2EE application along with all related projects
30
Migrating WebLogic Applications to WebSphere V5
Figure 3-6 Delete file system source too
3.3.4 Server folder checkpoints
If you are also experimenting with different server configurations, it is handy to be
able to checkpoint server folders as well. This allows you to easily revert to a
previous server configuration without having to recreate it step by step.
There are at least two ways to create and re-import server folder checkpoints:
1. Use the new Server Configuration file type.
– Export server configuration as a file.
– Import the file as a Server Configuration file type into a newly created or
existing server project.
2. Use a Zip file to checkpoint a server folder.
– Export the contents of a server project as a Zip file.
– Import the Zip file into a newly created server project.
We prefer the Zip file method because it requires fewer steps. This is because
the Zip file preserves more information than the Server Configuration file type,
including the following:
򐂰 The server definition.
򐂰 The names of the server and the server configuration.
򐂰 The server’s configuration setting.
Limitation
When using the Zip file technique, server folder checkpoints created under one
version of WebSphere Studio Application Developer may not be able to be
imported into a later version. We recommend using these checkpoints only as a
convenience for short term archiving of server folders. Only plan to use them
within the same version of WebSphere Studio Application Developer.
Chapter 3. Migration tools
31
Create server folder checkpoint as a Zip file
1. Stop the server in the server perspective.
2. Click File -> Export.
3. Select Zip file and click Next.
4. Check the contents of the server project folder, but not the server folder itself
as shown in Figure 3-7 on page 33.
5. Check the Create only selected directories option — this prevents the
server’s folder name from being added to the checkpointed files.
6. Enter or browse to the Zip file name, and click Finish.
You may want to delete the server project at this point. Make sure you delete its
workspace contents too.
32
Migrating WebLogic Applications to WebSphere V5
Figure 3-7 Export server folder contents as a Zip file
Restore a server folder checkpoint
1. Stop the server and delete any existing server folder in the server perspective.
2. Create a server project by clicking File -> New -> Server project.
3. Name the project folder and click Finish.
4. Select the new server project folder.
5. Right-click Import, select Zip file, and click Next.
6. Enter or browse to the Zip file name and click Finish — see Figure 3-8 on
page 34.
Chapter 3. Migration tools
33
– The folder name should have been initialized to the selected project.
– You will be prompted to overwrite the .project file. Respond Yes or No; it
should not matter.
Figure 3-8 Import server folder Zip file into server project
3.3.5 Application client modules
We used J2EE application client modules in two of the examples in Chapter 5,
“Migration examples” on page 125. Alternatives for packaging and executing
application clients are discussed in 4.5.1, “Lightweight application client” on
page 117. In this section, we show how to import and export an application client
JAR in WebSphere Studio Application Developer.
34
Migrating WebLogic Applications to WebSphere V5
Import application client
The following steps import an application client JAR file into WebSphere Studio
Application Developer. The names in this example are based on 5.2, “One2many
example — CMP 2.0 with CMR” on page 126.
1. Choose File -> Import.
2. Select App Client JAR file and click Next.
3. Select New for Application Client Project.
4. Select Existing for Enterprise Application Project.
5. Complete the following fields, as shown in Figure 3-9 on page 36:
– Browse for Application Client File — in this case,
examples/one2many/Import/One2manyClient.jar.
– New project name — One2manyClient.
– Existing project name — One2manyApp.
i. Browse for existing project name.
ii. Select One2manyApp.
iii. Click OK.
6. Click Next and check the box that indicates the new project is dependent on
the One2manyEjb.jar, as shown in Figure 3-10 on page 37.
Omit this step if your application client does not have this dependency.
Message-driven beans, for example, do not have dependent EJB interfaces.
If there are dependencies and you omit this step, the dependencies can be
provided later by means of the project Properties. See Figure 3-12 on
page 39.
a. Select the One2manyClient project.
b. Right-click and select Properties at the very bottom of the pop-up menu.
c. Select the Java Build Path.
d. Select the Projects tab.
e. Check the dependency, and click OK.
7. Click Finish.
If your application has already been added to a server configuration, you may
see a warning like the one in Figure 3-11 on page 38. Although the
application client is not really needed in the test server, you can click OK to
perform this repair.
Chapter 3. Migration tools
35
Figure 3-9 Import application client into existing J2EE application project
36
Migrating WebLogic Applications to WebSphere V5
Figure 3-10 One2manyClient project depends on One2manyaEjb.jar
Chapter 3. Migration tools
37
Figure 3-11 Repair server configuration on import
The result of importing the application client is a J2EE application client project
imbedded within its J2EE application project. A new <module> deployment
descriptor element is automatically added to the application.xml deployment
descriptor. This structure can be seen in Figure 3-12 on page 39.
WebSphere Studio Application Developer insists on a valid structure for the
imported application client JAR file. Here are some common problems we
experienced:
򐂰 Missing or invalid meta-inf/application-client.xml file — see “Missing
application-client.xml file” on page 39.
򐂰 Missing main class in the meta-inf/Manifest.mf file — see “Missing main
class” on page 40.
38
Migrating WebLogic Applications to WebSphere V5
Figure 3-12 Update Java build path for new One2manyClient project
Missing application-client.xml file
WebSphere Studio Application Developer refuses to import a J2EE application
client JAR without an application-client.xml file. We experimented with several
solutions to this problem:
򐂰 Create a new J2EE application project and then import the Java source file
using File -> Import of a Zip file, extracting just the Java file. This approach
works, but it takes a lot of steps and is error prone.
򐂰 Add a meta-inf/application-client.xml file directly to the application client JAR
file. This is easily done if you are using a staging folder as recommended in
4.2.3, “Stage source code” on page 101. This approach is easier.
Example 3-2 shows the contents of a minimum acceptable application-client.xml
file. We added this file to the staging folder and recreated the application client
JAR file. The resulting JAR file imports successfully.
Example 3-2 application-client.xml file added to Staging folder
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application-client PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE
Application Client 1.3//EN"
"http://java.sun.com/dtd/application-client_1_3.dtd">
<application-client>
<display-name>One2manyClient</display-name>
</application-client>
Chapter 3. Migration tools
39
Missing main class
When the jar command is used to create a JAR, it adds a meta-inf/Manifest.mf
file if it is missing. However, this Manifest file does not include the mandatory
main class for an application client JAR. Figure 3-13 shows the error message
generated when you import such a JAR as an application client module. Fixing
this error may also correct other compiler errors. It is easily fixed.
1. Select the Manifest.mf file.
2. Right-click and select Open With -> JAR Dependency Editor. Or just
double-click the Manifest.mf file.
3. Enter the full path name of the main class as shown at the bottom of
Figure 3-14 on page 41.
4. Save modifications.
Figure 3-13 Missing main class for application client
40
Migrating WebLogic Applications to WebSphere V5
Figure 3-14 Add main class to application client module
Export application client
An application client can be exported in two forms:
1. By itself as an application client JAR, ready for execution in its own JVM.
2. As a module within the EAR of its enclosing J2EE application. Migrating
WebLogic Applications to WebSphere Advanced Edition V4, SG24-6179
shows how to export an EAR file.
Chapter 3. Migration tools
41
Exporting an application client JAR is really simple. We continue with the
one2many example, as shown in Figure 3-15.
1. Click File -> Export.
2. Select App Client JAR file and click Next.
3. Enter or browse to complete the following fields, and click Finish.
– Project resource to export — One2manyClient.
– Target file — examples\one2many\Export\One2manyClient.jar.
– Check Export source files so you can re-import the project later.
Figure 3-15 Export a J2EE application client JAR
42
Migrating WebLogic Applications to WebSphere V5
3.3.6 Javadoc export
This is a new feature in WebSphere Studio Application Developer V5. You can
generate the Javadoc files for any project containing Java code, and place them
in a folder of your choice. Javadoc warning messages are reported in a Javadoc
console for viewing.
1. Click File -> Export.
2. Select the Javadoc file type and click Next. This will show you the projects
with Java code. See Figure 3-16 on page 44 for an example.
3. Select one of the projects shown. You can only do one project at a time.
4. Select the Java classes you want included in your Javadoc. Otherwise, you
will generate Javadocs for all of the packages in the project.
a. Expand the project to expose its packages.
b. Select the package(s) you are interested in.
c. Check each Java class that you want.
If deployment code has been generated for your project (this is the normal
case), then you will want to limit Javadoc to just your original Java source.
The only way we know to accomplish this is to select those Java files
explicitly.
5. Enter the Destination folder name and click Finish.
Note that additional options are available to control references, style, and
Javadoc comments. Investigate these by clicking Next before Finish.
We used this to debug Javadoc comments. See “Debug Javadoc tags” on
page 162.
If you had to do this repeatedly, it could become a bit tedious. In a large
production project, it is recommended that Javadocs be generated by an Ant
script from the exported EAR file.
Chapter 3. Migration tools
43
Figure 3-16 Generate Javadocs for original source code
3.3.7 Create new file
You will occasionally need to add a general data file to a WebSphere Studio
Application Developer project. For example, we had to add jndi.properties and
jndiprovider.properties files in “Remove hard-coded JNDI InitialContext
properties” on page 152. In this section, we describe two different ways to do
this. These are not new to WebSphere Studio Application Developer V5, but we
44
Migrating WebLogic Applications to WebSphere V5
did not cover them in Migrating WebLogic Applications to WebSphere Advanced
Edition V4, SG24-6179. The two methods are:
򐂰 New simple file.
򐂰 Drag and drop.
New simple file
Assume you want to add a jndi.properties file to the appClientModule folder in
the One2manyClient project in Figure 3-17 on page 46.
1. Select the appClientModule folder.
2. Right-click New -> Other and select Simple File.
3. Click Next to bring up the New File window as seen in Figure 3-18 on
page 47.
4. If you did not initially select the correct folder, you can change it here.
5. Enter the name of the new file — jndi.properties in this case.
6. Click Finish.
This will leave you in the text editor so you can enter the contents of the new file.
See Figure 5-16 on page 154 for the jndi.properties example.
You can add a new folder through a similar process, by starting with New ->
Other and then selecting Simple Folder.
Chapter 3. Migration tools
45
Figure 3-17 Create new simple file
46
Migrating WebLogic Applications to WebSphere V5
Figure 3-18 Name new simple file
Drag and drop (cut and paste)
A more elegant way to add a file is to use the Windows drag-and-drop feature.
This is recommended if:
򐂰 The file already exists somewhere in your file system.
򐂰 You also want to create enclosing folders at the same time.
This technique is depicted in Figure 3-19 on page 48. This example shows how
to add the jndiprovider.properties file, along with its enclosing folder structure of
com/ibm/websphere/naming, to the appClientModule in the One2manyClient
project.
1. Arrange the windows of WebSphere Studio Application Developer and
Windows Explorer so that both are visible.
2. Select the com folder in Windows Explorer.
Chapter 3. Migration tools
47
3. Drag and drop the com folder to the appClientModule folder in WebSphere
Studio Application Developer.
Another alternative, at this point, is to use cut and paste operations. This is
convenient if the windows are not both visible.
This will create the entire folder structure along with copies of all enclosed files in
the WebSphere Studio Application Developer folder.
Figure 3-19 Drag and drop to create new file along with its enclosing folders
3.3.8 Using type hierarchy browser
WebSphere Studio Application Developer provides a powerful type hierarchy
browser. This feature is an effective way to analyze and understand class
relationships. WebSphere Studio Application Developer V4 supports type
hierarchies through the Java Type Hierarchy perspective. V5 has improved this
feature and now makes it available from within other perspectives through the
Open Type Hierarchy pop-up menu selection.
In the process of fixing an initial context lookup problem in “Use
PortableRemoteObject narrow” on page 156, we used the type hierarchy
browser to analyze the relationship between two known types:
򐂰 _ObjectStub, the object returned by the InitialContext lookup.
򐂰 BankHome, the interface expected by this lookup.
48
Migrating WebLogic Applications to WebSphere V5
This is how we browsed the associated type hierarchies:
1. Use Java Search to find the declaration of the type _ObjectStub — the search
pane should appear with a single hit as shown in Figure 3-20 on page 50.
2. Select the search result.
3. Right-click Open Type Hierarchy — the Hierarchy for _ObjectStub will
appear as in Figure 3-21 on page 51.
4. Select the abstract class ObjectImpl to investigate the parent of _ObjectStub.
5. Right-click Focus On ‘ObjectImpl’ — this with show the Hierarchy for
ObjectImpl.
6. To see the Hierarchy (Subtypes) of ObjectImpl, click the Subtypes icon as
shown in Figure 3-21 on page 51 — at this point, the _BankHome_Stub
subtype should look familiar.
7. Repeat steps (4) and (5) for _BankHome_Stub to see its type hierarchy,
shown in Figure 3-22 on page 51.
8. Click the Supertypes icon to see the Hierarchy (Supertypes) of
_BankHome_Stub. This view includes the BankHome interface we are
interested in.
9. At any time, you can return to a previous hierarchy by clicking the Previous
Hierarchy icon as shown in Figure 3-22 on page 51. This also shows the
package for each type.
From this analysis, we quickly learned the following:
򐂰 BankHome is implemented by _BankHome_Stub.
򐂰 _BankHome_Stub and _ObjectStub both extend the abstract class
ObjectImpl, which is located in the org.omg.CORBA_2_3.portable package.
These types are all visible in the subtypes hierarchy in Figure 3-21 on
page 51.
Chapter 3. Migration tools
49
Figure 3-20 Java Search for _ObjectStub type declaration
50
Migrating WebLogic Applications to WebSphere V5
Figure 3-21 Hierarchy for _ObjectStub, and Hierarchy (Subtypes) for ObjectImpl
Figure 3-22 _BankHome_Stub supertypes, and Previous Hierarchy Inputs with package names
Chapter 3. Migration tools
51
3.3.9 Finding Find/Replace
One thing that takes some getting used to in WebSphere Studio Application
Developer is where to find what. To make this more challenging, some common
V4 functions have moved in V5. For example, we discovered the following:
򐂰 The V5 Search function has its own entry on the menu bar. It is no longer
found in the Edit menu.
򐂰 When editing in the Java editor, Search is available on the pop-up menu, but
Find/Replace is not. You must used the Edit menu bar entry for Find/Replace.
These functions are both available on the pop-up menu in V4.
򐂰 In the Deployment Descriptor Source editor, neither Search nor Find/Replace
are available on the pop-up menu. They must be invoked from the Search
and Edit menu bar entries, respectively. In V4, Find/Replace was available on
the pop-up menu, but Search was not.
We present an example of replacing text in the ejb-jar.xml file. We found that
getting Find/Replace to work properly requires selecting things in the correct
order. We start with the ejb-jar.xml file already in the Source tab of the
Deployment Descriptor Editor, as shown in Figure 3-23 on page 53.
1. First select the ejb-jar.xml file.
This can be in the J2EE Navigator or Navigator perspective. We found that
omitting this select sometimes causes Find/Replace to be unavailable.
2. Select the text for finding by highlighting it in the XML text.
3. Select Edit -> Find/Replace — this will initialize the Find text in the
Find/Replace window.
4. Enter the Replace With text.
5. Use Replace/Find or Replace All to make the changes.
6. Click Close.
7. Save your changes.
52
Migrating WebLogic Applications to WebSphere V5
Figure 3-23 Modify deployment descriptor XML source with Find/Replace
3.3.10 Java Browsing perspective
The Java Browsing perspective has a look and feel reminiscent of VisualAge for
Java. It is bound to be appealing to VisualAge for Java users. However, the
method-level features of this tool are not supported in the Java Browsing
perspective.
Chapter 3. Migration tools
53
Activate this perspective as follows:
1. Select Window -> Open Perspective -> Java Browsing, as shown in
Figure 3-24.
Alternatively, you can click the
and select Java Browsing.
Open a Perspective icon in the left tool bar
2. Populate Figure 3-25 on page 55 as follows:
a. Click a project.
b. Click a package.
c. Click a type.
d. Double-click a member.
Figure 3-24 Activate the Java Browsing perspective
54
Migrating WebLogic Applications to WebSphere V5
Figure 3-25 Java Browsing perspective of AccountBean abstract getter getAccountId
3.4 Deployment Descriptor editors
The different deployment descriptor editors of WebSphere Studio Application
Developer V4 — such as EJB Editor, Application Editor, and Web.xml editor —
are unified under the name of Deployment Descriptor editor in V5. Both its look
and feel, and the organization of these editors have changed significantly. In
addition, they support the new functions of J2EE 1.3, EJB 2.0, and Servlets 2.3.
We summarize some of these changes in this section.
Look and feel
You activate the new Deployment Descriptor editors pretty much the same way:
1. Select a deployment descriptor file, such as ejb-jar.xml file.
2. Right-click Open With -> Deployment Descriptor.
This takes you to an overview window. For EJBs, this looks like Figure 3-26 on
page 57. Note two interesting features of the overview window:
1. It acts a bit like a mini-browser.
Some of the entries on this window will take you to pages corresponding to
the tabs across the bottom — Beans, Assembly Descriptor, References, and
Access. Each of these has a little home icon in the upper-right corner to take
Chapter 3. Migration tools
55
you back to the overview window. See Figure 3-28 on page 60 for an
example.
2. Its major sections can expand or collapse, similar to folders and their
contents.
You may have to scroll down to find what you are looking for. Alternatively,
you can collapse subsections you are not interested in. Compare Figure 3-26
on page 57 with Figure 3-27 on page 59 to see what this looks like. These are
both views of the overview window, but the second one has most of its
subsections collapsed to their header lines.
Organization
The major tabs of the new EJB Deployment Descriptor editor are denser than the
V4 EJB Editor. Moreover, there is no longer a separate EJB Extension Editor.
WebSphere-specific and standard deployment descriptors have been integrated.
WebSphere specific descriptors are indicated by their header names. For
example, Figure 3-27 on page 59 shows the following two headings for
extensions:
򐂰 WebSphere Extensions
򐂰 WebSphere Bindings
The following is a rough mapping of the contents of the old EJB and EJB
Extension tabs to the new Deployment Descriptor tabs:
򐂰 The new References and Source tabs are similar to the old ones.
򐂰 The new Beans tab includes the old Bindings, Environment, Inheritance,
Relationships, Finders, Container, and some of the Methods tabs.
򐂰 The new Access tab covers the remainder of the old Methods tab.
򐂰 The new Assembly Descriptor tab includes the old Transactions and Security
tabs.
56
Migrating WebLogic Applications to WebSphere V5
Figure 3-26 Overview of Deployment Descriptor editor
3.4.1 CMP 2.0 deployment
Before you can start an application with CMP 2.0 entity beans, you must bind
each bean to a CMP-ready connection factory. This is done by deploying each
bean with a JNDI name of the form eis/{DSname}_CMP, where {DSname} is the
DataSource name for the underlying database. There are two steps to this
process, which can be done in either order:
1. Define the CMP-ready DataSource.
Chapter 3. Migration tools
57
2. Bind the associated JNDI name of the CMP 2.0 connection factory to the
CMP 2.0 entity beans.
Define a CMP-ready DataSource
DataSources are defined within server configurations:
1. If you do not already have a server configuration, you must set up a
WebSphere Studio Application Developer test server as described in 3.5.1,
“Test server setup” on page 71.
2. Define a DataSource for use with CMP 2.0 according to 3.5.2, “Create
[CMP-ready] DataSource” on page 74. Make sure you check the box labeled
Use this data source in CMP.
Bind CMP connection factory
Assume that the database DataSource has the JNDI name jdbc/Sample. Then
the JNDI name for the CMP 2.0 connection factory is eis/jdbc/Sample_CMP. It
can be specified at either of two levels:
򐂰 A CMP connection factory for the JAR becomes the default for all CMP
beans.
򐂰 A CMP connection factory can be specified for each individual CMP bean.
Figure 3-27 on page 59 shows binding the CMP connection factory at the JAR
level in the EJB Deployment Descriptor editor. You can get there through the
J2EE perspective:
1. Select the ejb-jar.xml.
2. Right-click and select Open With -> Deployment Descriptor.
3. Scroll to the bottom to find the WebSphere Bindings section. For visual
clarity, we collapsed all unneeded sections in this figure.
4. Enter the connection factory JNDI name.
5. Save your changes.
Follow a similar procedure if you choose to configure each bean individually. In
that case, enter the CMP JNDI name in a corresponding place on the Beans tab
of the Deployment Descriptor editor.
58
Migrating WebLogic Applications to WebSphere V5
Figure 3-27 Bind CMP 2.0 connection factory using special JNDI name
3.4.2 Bind global JNDI name to EJB home
The following is WebSphere specific. Other vendors have different rules. In
particular, see 4.4.5, “ejb-link” on page 115, for a discussion of WebLogic
differences.
The home interface of each EJB must be deployed with a global JNDI name. This
is true for both remote and local interfaces. If an EJB is not deployed with a global
JNDI name, it is not possible to look up its home at runtime. See the JNDI
chapter of Migrating WebLogic Applications to WebSphere Advanced Edition V4,
SG24-6179 for more information on global JNDI names and EJB references.
Although binding a JNDI name involves basically the same process as for
WebSphere Studio Application Developer V4, since the Deployment Descriptor
editor has a different look and feel, we present the updated details here.
Chapter 3. Migration tools
59
An EJB home interface is assigned its global JNDI name in the Beans tab of the
Deployment Descriptor editor. There are several ways to get to this window; we
only describe the most common one here.
1. Select the bean’s ejb-jar.xml file in the J2EE Navigator perspective.
2. Right-click Open With -> Deployment Descriptor.
3. Click the Beans tab.
4. Select the bean by its name — see Figure 3-28.
5. Enter the correct global JNDI name.
6. Save the results.
Figure 3-28 Bind global JNDI name to EJB
3.4.3 Bind local JNDI name to EJB reference
Whenever one EJB references another EJB, the following deployment descriptor
is required by the J2EE 1.3 specification:
1. Declare an EJB reference deployment descriptor, one for each EJB that is
referenced.
60
Migrating WebLogic Applications to WebSphere V5
2. Use a JNDI name in the java:comp/env local environment context to indirectly
look up the referenced EJB.
– The local JNDI name, without its java:comp/env context, is the name of the
EJB reference deployment descriptor.
– The global JNDI name for the referenced EJB also appears in the
deployment descriptor for the EJB reference. The use of a global JNDI
name is vendor specific. It is always required in WebSphere. See 4.4.5,
“ejb-link” on page 115, for the WebLogic rules.
These rules apply regardless of whether the reference is to a remote interface or
a local interface. Reference for remote and local interfaces use distinct
deployment descriptors. The JNDI chapter of Migrating WebLogic Applications to
WebSphere Advanced Edition V4, SG24-6179 contains more details on global
JNDI names and EJB references.
Defining an EJB reference is basically the same as in WebSphere Studio
Application Developer V4. Since the Deployment Descriptor editor has a different
look and feel, we present the updated details here.
An EJB reference is defined in the References tab of the Deployment Descriptor
editor. Here is a sample scenario:
1. Select the bean’s ejb-jar.xml file in the J2EE Navigator perspective.
2. Right-click Open With -> Deployment Descriptor.
3. Click the References tab.
4. Select the bean that does the EJB lookup and click Add — see Figure 3-29
on page 62.
5. Select the type of reference in the Add Reference window and click Next.
– In this example, we chose EJB local reference.
– Notice that non-EJB references are also supported by this wizard.
The EJB resource reference and the Resource environment reference
options also appear in the Client Deployment Descriptor editor. These
options were needed to deploy the message client in 5.3.8, “Standard
J2EE application client” on page 194.
6. Click Browse on the Link field to bring up the Link Selection window — see
Figure 3-30 on page 63.
– Deployment descriptor fields can be completed manually, but it is easier to
use this newly enhanced ejb-link processing.
7. Select Enterprise bean in current EJB project and pick the referenced
bean out of the selector list.
Chapter 3. Migration tools
61
8. Click OK and Finish — see Figure 3-31 on page 64.
– Expand BankEJB to view all references — we just added the second one.
– All required deployment descriptor fields are completed for you, including
the crucial global JNDI name of the referenced EJB.
9. Make sure that the Name field corresponds to what is used in the code —
modify it if it is incorrect.
– In this case the Name is ejb/customerEjb, so the code should be using the
Java String “java:comp/env/ejb/customerEjb” in the initial context lookup.
10.Save the results.
Figure 3-29 Adding an EJB reference to BankEJB
62
Migrating WebLogic Applications to WebSphere V5
Figure 3-30 Use wizard to complete EJB reference
Chapter 3. Migration tools
63
Figure 3-31 Bind local and global JNDI names in EJB reference
3.4.4 EJB QL finders
The EJB query language is a new feature of EJB 2.0. Although our examples do
not use EJB QL, this section gives a preview of the EJB QL wizard. It is part of
the EJB Deployment Descriptor editor.
We start with the completed migration results of 5.2, “One2many example —
CMP 2.0 with CMR” on page 126. We add a finder to this application. The finder
is designed to select AccountBean objects with balances less than or equal to
2000. Here is how we implemented the finder:
1. Select the ejb-jar.xml file.
2. Right-click and select Open Deployment Descriptor.
3. Select the Bean tab.
4. Select the Account bean.
5. Scroll down to the section entitled Queries.
64
Migrating WebLogic Applications to WebSphere V5
6. Click Add.
This starts the Add Finder Descriptor wizard as shown in Figure 3-32 on
page 66. It steps you through two windows:
a. Add the finder method — this modifies the home interface.
b. Define the EJB QL — this modifies the deployment descriptor file.
7. Add the finder method:
a. Select New method.
b. Make sure find method is selected.
c. Fill in the following fields as shown in Figure 3-32 on page 66:
•
Name: findSmallAccounts.
•
Use the selector for Return type: java.util.Collection.
d. Click Next to proceed to the EJBQL window.
8. Define the EJB QL — see Figure 3-33 on page 67.
a. Use the selector to choose a query sample — we chose the Single Where
Predicate style of query.
b. Modify the sample query as shown in the figure.
From: select object(o) from AccountBean o where o.accountId is null
To: select object(o) from AccountBean o where o.balance <= 2000
c. Click Finish — the EJB QL query is validated at this point.
9. Save the modified deployment descriptor.
This procedure adds a findSmallAccounts finder to the AccountHome interface.
You must regenerate the deployment code to create the implementation for this
new method.
Chapter 3. Migration tools
65
Figure 3-32 Add a new EJB QL finder method
66
Migrating WebLogic Applications to WebSphere V5
Figure 3-33 Deploy with EJB QL query
3.4.5 Other deployment descriptor editors
So far in the chapter, all of the deployment descriptor editors have been for EJBs.
There are several other important deployment descriptor editors. Instead of
describing them here, we refer you to examples elsewhere in this paper.
򐂰 Web Deployment Descriptor editor.
The filters migration exercise has examples of the Filter, Pages, and Security
tabs of the Web Deployment Descriptor editor. See 5.4, “Filters example —
servlet filters and authentication” on page 203.
Chapter 3. Migration tools
67
In particular, the Security tab shows a variation on the page layout that can
cause some confusion. Examine the different figures of the Security tab in
5.4.3, “Deploy and test filters” on page 215. You will notice two very different
page layouts. These are controlled by a secondary tab selection at the top of
the page. We call these subtabs because they are within the Security tab.
– The Security Roles subtab.
– The Security Constraints subtab.
It is easy to overlook these variations and not be able to find their associated
deployment descriptors. This same technique is used for the References tab.
򐂰 Application Deployment Descriptor editor.
See “Map login security role” on page 230 for an example of this editor.
򐂰 Client Deployment Descriptor editor.
This is used for client-application.xml deployment descriptor files. We did not
actually use this editor. Instead, we use the equivalent features of AAT in
5.3.8, “Standard J2EE application client” on page 194.
3.4.6 RDB mapping with CMR
Also see 5.2.7, “Meet-in-the-middle RDB mapping” on page 163.
Top-down and meet-in-the-middle EJB/RDB mappings are covered in Migrating
WebLogic Applications to WebSphere Advanced Edition V4, SG24-6179. The
steps for the top-down mapping are the same in WebSphere Studio Application
Developer V5, but the final results have some differences.
򐂰 EJB 2.0 CMR introduces new mapping entities.
򐂰 The results are placed in a back-end folder.
For a top-down mapping, here are the steps:
1. Select the project containing CMP beans.
2. Right-click Generate -> EJB to RDB Mapping to start the mapping wizard.
3. Select Create a new backend folder and click Next.
– This window is new with WebSphere Studio Application Developer V5.
– It is the only option available if there is no existing back-end folder.
– See Figure 5-12 on page 145 for the contents of the back-end folder.
4. Select the Top Down option and click Next.
5. Enter the database and schema names, as shown in Figure 3-34 on page 69.
– The database need not exist yet for top-down mapping.
6. Check Generate DLL and click Finish.
68
Migrating WebLogic Applications to WebSphere V5
7. This should put you into the mapping editor. Notice the following features in
Figure 3-35 on page 70:
– The Map.mapxmi mapping is for the DB2UDBNT_V72_1 back end.
– Foreign keys are used to implement the CMP 2.0 relationships.
– Since this example has a bi-directional relationship, each table uses a
foreign key field.
Figure 3-34 Database and schema names needed for EJB/RDB mapping
Chapter 3. Migration tools
69
Figure 3-35 Top-down mapping of bi-directional Container Managed Relationship
3.5 Test server
Most of the features of a WebSphere application can be tested on the test server
embedded within WebSphere Studio Application Developer. The most common
server configuration steps are supported directly by the WebSphere Studio
Application Developer server configuration editor. Others are available by
launching the WebSphere Administrative Console from within the test server.
This topic is discussed in 3.6, “WebSphere Administrative Console” on page 81.
In this section, we present some of the most common testing tasks that we used
in the WebSphere Studio Application Developer test server.
70
Migrating WebLogic Applications to WebSphere V5
3.5.1 Test server setup
Starting the test server in V5 is very close to the V4 instructions. However, since
both V4 and V5 servers are supported, there are a few more options to resolve.
Another minor difference is that we had to explicitly create a server project before
creating and configuring a server. This may just be a beta defect, but the
automatic creation of a server project failed for us.
Here is what we had to do a little differently:
1. If you do not already have a server project, create one as follows:
a. Click File -> New -> Server Project.
You may have to use the following alternative.
i. Click File -> New -> Other.
ii. Select Server and Server Project.
iii. Click Next.
b. Enter the project name — we use Servers.
c. Click Finish.
2. Open the server perspective and follow the instructions in Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179, with the
following differences:
a. In the Create a New Server Configuration step, you will have additional
server configurations to choose from. See Figure 3-36 on page 72. We
chose the WebSphere Version 5.0 Server Configuration.
b. In the Create New Server Instance step, you will also have additional
servers to choose from. See Figure 3-37 on page 73. We chose the
WebSphere Version 5.0 Test Environment.
c. In the last step, where you assign the configuration to the server, the Set
Configuration has been changed to Switch Configuration. See
Figure 3-38 on page 74.
Chapter 3. Migration tools
71
Figure 3-36 Choose WebSphere V5.0 Server Configuration
72
Migrating WebLogic Applications to WebSphere V5
Figure 3-37 Choose WebSphere V5.0 Test Environment
Chapter 3. Migration tools
73
Figure 3-38 Switch server to new server configuration
3.5.2 Create [CMP-ready] DataSource
By comparison with WebSphere Studio Application Developer V4, we found that
creating a DataSource has the following differences in V5:
1. The look and feel of the DataSource editor has changed to be more like the
look and feel of the new Deployment Descriptor editors.
2. We had to define the JDBC driver for DB2 for our one2many example.
3. With the introduction of CMP 2.0, there is the important added option to use
the DataSource for CMP.
Here are the steps we followed:
1. Set up the server if that has not already been done — see 3.5.1, “Test server
setup” on page 71.
2. Select the server perspective if not already selected.
3. Select the Server Configuration instance — we used our One2many Server
Configuration in this example.
4. Right-click and select Open to bring up the Configuration editor.
5. Click the DataSource tab — see Figure 3-39 on page 76.
6. Scroll down, or close Node Settings, to locate the Server Settings.
7. We did not find the DB2 JDBC provider, so we followed the instructions in
3.5.3, “Configure a JDBC provider” on page 79, to configure it.
8. Select the DB2 JDBC JDBC provider.
9. Click Add for the DataSource list (second list in the Server Settings).
74
Migrating WebLogic Applications to WebSphere V5
10.Make sure WebSphere V5.0 DataSource is selected, and click Next to bring
up the Modify DataSource window shown in Figure 3-40 on page 77.
11.Complete the following DataSource fields:
– Name — we used the display name of Sample DataSource.
– JNDI name — this is the global JNDI name for the database.
– Check Use the DataSource in CMP if you need CMP 2.0 code
generation.
12.Click Next to bring up the database options window shown in Figure 3-41 on
page 78.
13.Complete the following database field:
– databaseName — we used Sample.
– user — db2admin.
– password — db2admin.
14.Click Finish.
15.Verify the completed properties under Server Settings — see Figure 3-42 on
page 79.
16.Save your new DataSource configuration.
Chapter 3. Migration tools
75
Figure 3-39 Server Configuration DataSource editor
76
Migrating WebLogic Applications to WebSphere V5
Figure 3-40 Complete DataSource JNDI name and CMP option
Chapter 3. Migration tools
77
Figure 3-41 Complete database properties
78
Migrating WebLogic Applications to WebSphere V5
Figure 3-42 Verify completed properties before saving
3.5.3 Configure a JDBC provider
A JDBC provider must be configured in order to locate the class for the
DataSource connection factory. This class is typically located in a Java Zip file
provided with your database. You may need to configure DB2 or some other
database system. Here are the steps:
1. Get to the Server Settings of the DataSource editor by following the
instructions in 3.5.2, “Create [CMP-ready] DataSource” on page 74. This
should look like Figure 3-39 on page 76, but without the DB2 JDBC provider
entry.
2. Click Add for the JDBC provider list to bring up the Create a JDBC Provider
window — see Figure 3-43 on page 80.
3. Select IBM DB2 as the Database type.
4. Select DB2 JDBC Provider as the JDBC Provider type — we probably
should have picked the XA type, but were being conservative.
Chapter 3. Migration tools
79
5. Click Next — see Figure 3-44 on page 81.
6. Enter Name and Class path of the DataSource implementation class, as
shown.
7. Click Finish.
8. Save modifications.
The DB2 JDBC provider should now be available for use, as shown in
Figure 3-39 on page 76. We did have a problem trying to use the Edit tab in this
window. It let us modify the provider properties, but a save had no effect, not
even an error message. Errors had to be corrected by a remove and add
sequence.
Figure 3-43 Create a JDBC Provider for DB2
80
Migrating WebLogic Applications to WebSphere V5
Figure 3-44 Complete name and path of new JDBC Provider
3.6 WebSphere Administrative Console
Figure 3-45 on page 82 shows the welcome page for the new browser-based
Administrative Console of WebSphere Application Server V5. You navigate to the
various configuration options be expanding the appropriate folders on the left
side of this page. See 5.3.4, “Configure JMS service” on page 176, for examples
that exercise aspects of the Services and Resources folders. Also see 3.6.4,
“Install EAR into WebSphere” on page 86.
Chapter 3. Migration tools
81
Figure 3-45 WebSphere Administrative Console starting page
3.6.1 Launching the Administrative Console
The WebSphere Administrative Console can be launched from two different
environments:
򐂰 Full support from Windows 2000.
Click Start -> Programs -> IBM WebSphere -> Application Server v5.0 ->
Administrative Console.
򐂰 Single server support from WebSphere Studio Application Developer test
server.
Follow the instructions in 3.6.3, “Run the Administrative Console in test
server” on page 84.
In our beta system, some of the test server features could only be configured
through the WebSphere Administrative Console — for example, the JMS
configuration. A new JMS tab will be present in the server configuration editor
of the released WebSphere Studio Application Developer.
82
Migrating WebLogic Applications to WebSphere V5
3.6.2 Administrative Console login
The login authorization for the WebSphere Administrative Console has two
variants:
򐂰 Security disabled.
As shown in Figure 3-46, you can provide an arbitrary user ID. It is used just
for tracking purposes.
򐂰 Security enabled.
You must provide the valid user ID/password for the configured security
account. See Figure 3-47 for this login prompt. For testing purposes, security
can be enabled from the WebSphere Studio Application Developer test server
— see “Enable WebSphere security” on page 228 for an example. The
console depicted in Figure 3-45 on page 82 was launched from within the
WebSphere Studio Application Developer test server with security enabled.
Figure 3-46 WebSphere console login — security disabled
Figure 3-47 WebSphere console login — security enabled
Chapter 3. Migration tools
83
3.6.3 Run the Administrative Console in test server
The configuration editor for the WebSphere Studio Application Developer test
server is sufficient for most testing requirements. However, there are testing
situations where you need options that are only available through the
WebSphere Administrative Console. These are available by running the
administrative client after starting the test server.
1. Select the server perspective.
2. Select the server configuration.
3. Right-click and select Open.
4. Check the Enable administration client box on the WebSphere Server
Configuration page — see Figure 3-48 on page 85.
5. Save your modifications.
6. Start the test server, or restart it if it is already running, and wait for it to start.
7. Select the Servers tab.
8. Right-click and select Run administrative client.
9. Provide the required authorization information as described in 3.6.2,
“Administrative Console login” on page 83.
Configuration changes made in the WebSphere Administrative Console modify
the current test server configuration object in the WebSphere Studio Application
Developer workspace.
Caveats
򐂰 Avoid using the WebSphere console and the server configuration editor at the
same time.
򐂰 You can only start the WebSphere console after starting the test server. This
may limit its usefulness for some tasks.
򐂰 If the console breaks or becomes inaccessible, you can just delete the test
configuration from within WebSphere Studio Application Developer and start
over.
84
Migrating WebLogic Applications to WebSphere V5
Figure 3-48 Enable the administration client in the test server
Configure the Web browser
You can configure the browser that WebSphere Studio Application Developer
uses for the WebSphere Administrative Console. We configured Internet
Explorer as follows:
1. In WebSphere Studio Application Developer, select Window -> Preferences.
2. Select Web Browser — see Figure 3-49 on page 86.
3. Select Use external Web Browser.
4. Enter or Browse to put the path of your Web browser into the Location field.
5. Click OK.
Chapter 3. Migration tools
85
Figure 3-49 WebSphere Studio Application Developer browser configuration
3.6.4 Install EAR into WebSphere
We used WebSphere Studio Application Developer for most migration and
testing tasks. The resulting EAR files can be installed into WebSphere with no
changes. These are the steps used to install the message example. The actual
steps will vary, depending on the application’s components.
1. Expand the Applications folder.
2. Click Install New Application — see Figure 3-50 on page 88.
3. Enter or browse to the EAR file path name.
86
Migrating WebLogic Applications to WebSphere V5
4. Click Next for each of several numbered steps, as long as no errors are
indicated.
Each step clearly describes what deployment options are available. Since we
used other tools to fully deploy our examples, we made no additional changes
during the install process. If an error occurs:
a. Click Cancel.
b. Correct the error.
c. Construct a new EAR file.
d. Start the install anew.
5. Click Finish after completing all numbered steps.
6. Click Save Configuration.
7. Confirm by clicking Save — the application should be installed at this point,
but not yet started.
8. Click Managed Applications.
9. Check the box to the left of the newly installed application — see Figure 3-51
on page 88.
10.Click Start.
The messages window indicates if the application has started successfully.
Although the application appears to have started properly, there may have been
related errors in other servers, such as the JMS listener server for an MDB.
Check for these errors in the AppServer/logs/server1/SystemOut.log file. If you
have recently made WebSphere configuration changes, you may have to restart
the server before they take effect.
Chapter 3. Migration tools
87
Figure 3-50 Install EAR into WebSphere
Figure 3-51 Start newly installed application
88
Migrating WebLogic Applications to WebSphere V5
3.7 AAT
AAT supports the creation and modification of all of the deployment descriptors
discussed elsewhere in this paper. We chose to use WebSphere Studio
Application Developer because we also needed its source code editing features
for most migration tasks. In a migration effort, AAT may be more convenient for
making final adjustments to deployment descriptors. In this section, we show
how a few of the deployment descriptors of our one2many example look in AAT.
Also see 5.3.8, “Standard J2EE application client” on page 194, where we used
AAT to deploy a J2EE application client.
Launch AAT by clicking Start -> Programs -> IBM WebSphere -> Application
Server v5.0 -> Application Assembly Tool. Figure 3-52 on page 90 shows the
V5 launch page. Figure 3-53 on page 91 shows the EAR from the migrated
one2many example as it looks in AAT. We expanded the EJB Beans to show their
deployment details. You can access and modify all deployment descriptors from
this view.
򐂰 Select BankEJB -> EJB Local References to see the local references in
Figure 3-54 on page 92. We had to add these references as described in
“Upgrade to use standard EJB references” on page 158.
򐂰 Select EJB Relations -> Relationship Role 2 to see the cascade delete
relationship as shown in Figure 3-55 on page 93. This was imported
unchanged, as part of the original one2many example.
Chapter 3. Migration tools
89
Figure 3-52 Launching AAT
90
Migrating WebLogic Applications to WebSphere V5
Figure 3-53 A one2many EAR checkpoint in AAT
Chapter 3. Migration tools
91
Figure 3-54 EJB references for one2many BankEJB in AAT
92
Migrating WebLogic Applications to WebSphere V5
Figure 3-55 One-many cascade delete relationship in AAT
3.8 Automation tools
There are obvious opportunities for the introduction of automation into the
migration process. Chapter 4, “Migration issues” on page 97, offers a sampling of
the issues that automation could address. Here are some examples:
򐂰 Analyze project structure for application repackaging into standard EAR files.
򐂰 Enforce standard usage — for example, PortableRemoteObject narrow.
򐂰 Convert non-portable code — for example, InitialContext properties.
򐂰 Convert vendor-specific deployment descriptors — JNDI names and EJB
references.
򐂰 Help configure server for application installation — JMS connection factories
and destinations.
Chapter 3. Migration tools
93
Assistance can range for direct conversion to warnings and advice. Artifacts can
range from deployment descriptors to source code. To be useful, such tools must
know the details of specific J2EE versions and specific vendor products.
We specifically looked for tools to help migrate J2EE 1.3 applications from
WebLogic V7 to WebSphere V5. We found none. We did, however, find some
promising technologies that offer possibilities for the future. Struck by the variety
of approaches taken, we present a brief summary of our findings here.
Disclaimer
򐂰 We did not test or evaluate any of these tools while writing this paper.
򐂰 Information is based on our interpretation of publicly available documentation
and marketing information.
򐂰 We offer no recommendations on these technologies, or on the efficacy of
these tools.
򐂰 This is just a sampling of the tools we found. It is not intended to be a
complete list of what is available.
was40utils
We used was40utils in Migrating WebLogic Applications to WebSphere
Advanced Edition V4, SG24-6179. It converts the global JNDI names found in
vendor-specific extended deployment descriptors between the WebLogic,
WebSphere, and Sun formats. We were unable to find an updated version for
J2EE 1.3. In particular, we required support for the new ejb-local-ref descriptor.
There is no sign of future releases of this tool.
This is a useful, but limited automation tool. It handles global JNDI names for
EJBs and EJB references. It does not support other extended deployment
descriptors. In particular, it does not support data mapping descriptors. What is
interesting about this tool is that it is available as Java source code. It should be
possible to upgrade it to support new descriptors. It is available for downloading
at http://www.ejbinfo.com/FTP/was40utils.zip.
WL2WAS
WL2WAS addresses the conversion of all WebLogic extended descriptors to
WebSphere. It understands the contents of the following deployment descriptor
files:
򐂰 weblogic-ejb-jar.xml
򐂰 weblogic.xml
򐂰 weblogic-cmp-rdbms-jar.xml, including support for a long list of database
vendors
94
Migrating WebLogic Applications to WebSphere V5
It is designed to convert these descriptors into WebSphere extended deployment
descriptors. Note that there are some vendor-specific WebLogic options that do
not convert exactly, or at all, to WebSphere equivalents. In these cases, the tool
provides warnings and references to IBM documentation, so that you can
perform appropriate manual conversions.
This tool currently supports the conversion of WebLogic 5.0/6.0/6.1 deployment
descriptors into WebSphere 4.0 descriptors. WL2WAS is freely downloadable
from IBM, but it is not supported. For additional information, visit
http://www7b.software.ibm.com/wsdd/zones/studio/wl2was.html.
Cacheon Migrator
This tool goes beyond the conversion of extended deployment descriptors. It can
identify and convert source code as well. Its technology has the flavor of an
expert system. It uses a rule base to recognize source code patterns that it can
then rewrite into replacement code. If no replacement is possible, then the
source is flagged for manual conversion, which is also assisted by the tool. A
classic example is the conversion of the InitialContext PROVIDER_URL from
one vendor to another. The rewrite rules are designed to capture detailed
experience from real migration efforts. Users can also augment the rule base.
The company claims that this tool can automate up to 50% of an application
conversion.
This tool currently supports conversions between WebLogic, WebSphere, and
Oracle9i. For our purposes, conversion is supported only from WebLogic 5.1/6.1
to WebSphere 4.0. This tools can also be used to convert between different
versions of J2EE. Cacheon Migrator is a commercial product. It is not freely
available. See http://www.cacheon.com for more information.
XDoclet
This tool encourages a different approach to the development of J2EE
applications. Its promoters claim that it supports general attribute-oriented
programming in Java. The basic idea is to code all information into the bean
itself. An extension to Javadoc @tags is used to capture additional details for the
interfaces, deployment descriptors, and other files. These files are then
generated automatically by the tool in conjunction with Ant scripts. Templates
describe the form of the generated files. XDoclet tags assign values to attributes
that are used in the templates. Tag names are grouped by namespaces,
including @ejb, @web, @weblogic, and @webSphere. EJB interfaces are
generated from the @ejb namespace. WebSphere specific deployment
descriptors are generated from the @webSphere namespace.
For migration purposes, the XDoclet technology becomes interesting with the
recent introduction of the round-trip generation of tags from existing artifacts. You
Chapter 3. Migration tools
95
would first convert an ordinary J2EE application into an XDoclet-base
application, and then migrate it by adding appropriate XDoclet tags. One
advantage to this approach is that the original deployment information is
retained. The same artifacts could be used for deployment on different servers.
XDoclet currently supports an extensive set of tags. The last time we checked,
however, support for WebSphere V5 was still under construction. We did not
investigate precisely what is and is not supported. XDoclet is an open source
product. See http://xdoclet.sourceforge.net for more information.
96
Migrating WebLogic Applications to WebSphere V5
4
Chapter 4.
Migration issues
This chapter presents the migration issues identified by our migration examples.
Some of them are common migration issues. Others deal specifically with J2EE
and WebSphere features.
© Copyright IBM Corp. 2003. All rights reserved.
97
4.1 Introduction
This chapter is an issues-oriented summary of the problems we identified during
our migration exercises. You are encouraged to read the full details of this
discovery process in Chapter 5, “Migration examples” on page 125. We also
include a few issues based on our past migration experiences, and Migrating
WebLogic Applications to WebSphere Advanced Edition V4, SG24-6179.
Each issue is organized as follows:
1. Background discussion of J2EE specifications and migration practices.
2. One or more specific problems that we experienced in migration examples.
These are clearly labeled in the text for easy identification. A few of the issues
are of a general nature and do not include specific problems.
3. Recommendations for resolving the identified problems.
The issues are categorized as follows:
1. Migration process
During the writing of this paper, we refined the migration process used in
Migrating WebLogic Applications to WebSphere Advanced Edition V4,
SG24-6179. We describe the issues that led to these refinements:
–
–
–
–
–
Learn the new tools
Verify baseline
Stage source code
Portable shared JAR files
Project and server folder checkpoints
2. Follow the standards
All of the original examples ran on WebLogic 7.0. None of the examples ran
on WebSphere 5.0 without modifications. One reason for this is that none of
the examples precisely follow the J2EE standards. This is a common source
of migration problems.
–
–
–
–
–
PortableRemoteObject narrow
EJB references
EJB references for local EJBs
Syntax and completeness errors
Invalid exceptions
3. J2EE 1.3 features
In general, the J2EE features that we tested worked as advertised. In this
group, we highlight deployment problems and opportunities to use new or
improved features.
– Deployment of CMP 2.0 connection factory
98
Migrating WebLogic Applications to WebSphere V5
–
–
–
–
Deployment of MDB/JMS listener port
Use of local interfaces
J2EE form-based authentication
ejb-link
4. Client portability issues
This group deals with portability issues, mainly of lightweight application
clients. Lightweight application clients are not covered by the J2EE
specifications. Here we summarize changes we had to make to remove
proprietary and non-portable code from client code.
–
–
–
–
–
Lightweight application client
The t3 protocol
Portable JNDI InitialContext
EJB interfaces and stubs for lightweight clients
Portable JNDI names in clients
5. Data mapping
Aside from CMP 2.0 deployment, we did little with data mapping in this paper,
so this is a short section.
– Impact of CMP 2.0 features
– Decoupling database conversion
4.2 Migration process
Taken together, these issues capture improvements to our recommended
migration process.
1. Learn how to use the tools.
2. Verify baseline.
3. Stage source code, and examine it for known migration problems.
4. Import source code.
5. Correct compilation errors.
6. Update and complete deployment descriptors.
7. Test and debug cycle.
8. Export final EAR for deployment on server.
Most of the issues in this section encourage spending a little more time early in a
migration effort, so as to improve quality and reduce rework. The last issue
introduces a style of source control that we used in cases where rework was
unavoidable.
Chapter 4. Migration issues
99
4.2.1 Learn the new tools
This is not a new idea. We mention it in both of our earlier migration books, but it
deserves mentioning again. Much of the time spent writing this paper was
invested in learning how to use the latest version of the tools. In particular,
WebSphere Studio Application Developer is a complex and rich set of tools.
Although learning to use these tools is slow at first, the benefits are well worth
the effort.
򐂰 Study Chapter 3, “Migration tools” on page 19, and Chapter 4 of Migrating
WebLogic Applications to WebSphere Advanced Edition V4, SG24-6179.
We have tried to highlight the tools that were most useful during our migration
examples. We provide explicit instructions to help you find things within
WebSphere Studio Application Developer.
򐂰 Use the built-in WebSphere Studio Application Developer help facility.
This is an excellent source of information on both the WebSphere Studio
Application Developer and WebSphere. It has an excellent search capability.
Learn to use it. Hold the control key as you click Help -> Help Contents. This
puts the help function into a separate and independent window for easy
context switching between help information and your work.
4.2.2 Verify baseline
It is important to know that your application actually works on the original system.
This helps ensure the following:
򐂰 You have collected all of the necessary artifacts.
򐂰 All the pieces actually work together.
Problem: Missing or incorrect artifacts
We did not always follow this strategy in writing Migrating WebLogic Applications
to WebSphere Advanced Edition V4, SG24-6179, and this got us into trouble.
One of those examples had errors in its deployment descriptors. Using the
incorrect artifacts wasted time and resources.
Recommendation
Although it should be obvious, we recommend that you first verify that the
application works as expected on the source system — WebLogic in this case.
We applied this strategy to the examples in this paper.
Following this advice sometimes requires a little innovation. For example, see
5.2.1, “Verify baseline” on page 128, for the one2many example. Since we did
not have the required Oracle database system available, we first re-deployed to a
different database system as part of the baseline verification step.
100
Migrating WebLogic Applications to WebSphere V5
4.2.3 Stage source code
One of the first migration steps is to package the application’s source code for
importation into WebSphere Studio Application Developer. A good way to do this
is to construct an appropriately structured EAR file. It should contain the
following:
򐂰 Source code (no class files).
򐂰 Standard deployment descriptor files.
You must generate a legal EAR with legal JAR files, specifically ones that are
acceptable to WebSphere Studio Application Developer.
In WebSphere Studio Application Developer, application artifacts are organized
according to modules and projects. If your source code is organized into a simple
folder structure, it may need to be reorganized to accommodate J2EE modules
and WebSphere Studio Application Developer projects. This was the case with
our three examples. Although the WebLogic build process does create separate
EAR and client JAR files, they are embedded within the WebLogic server file
structure and they do not contain the source code needed for migration.
Problem: Construct valid EAR for import
Here are some of the specific problems we experienced in attempting to
construct valid EAR files for import:
򐂰 We put pieces into the wrong folders, in particular the Java, JSP, HTML, and
web.xml files for the filters example.
򐂰 We used incorrect JAR file names in the application.xml <module> stanzas
for the one2many and message examples.
򐂰 We had to construct an application.xml file for the filters example.
򐂰 The application-client.xml files were missing in the one2many and message
examples.
Recommendation
In the deployment chapter of Migrating WebLogic Applications to WebSphere
Advanced Edition V4, SG24-6179, we recommend the following:
򐂰 Use a staging folder to assist in restructuring source code.
򐂰 Construct an EAR file from the staging folder with the help of a simple Ant of
command script.
The staging folder allows you to reconstruct the EAR several times until you get it
right. You can easily move things around and adjust the deployment descriptors.
The staging folder is a bootstrapping technique. Once you start making source
code changes in the WebSphere Studio Application Developer workspace, you
Chapter 4. Migration issues
101
cannot easily go back to modifying the staging folder. You in effect cut the
umbilical cord to the staging folder. Our advice is to make this transition when
you are happy with the WebSphere Studio Application Developer module and
project structure. However, in at least one case, we had to return to the staging
folder to make a structural correction and then repeat modifications that had
been made in the meantime.
We used a staging folder for each of our examples:
򐂰 See 5.2.2, “Stage source code” on page 129, for additional details on how this
was done for the One2many example — CMP 2.0 with CMR.
򐂰 See “Staging Web source” on page 206 for an example of a Web application.
We had to add an application.xml file because this was just a Web application
and we wanted an EAR file for import.
Understand an application’s structure
One of the side benefits of this technique is that it forces you to learn more about
the structure of your application early in the migration process. This knowledge
helps in later migration steps. The original source for each of our examples had
an Ant build script. Build scripts can help you identify the modules and packages
in an application.
4.2.4 Portable shared JAR files
This issue is closely related to the construction of properly formed EAR archives.
We did not have to deal with this issue with our simple examples. It is included
here for completeness.
Complex applications often have JARs that are shared across different projects.
They may be third-party JARs, and may be shared across Web or EJB projects.
The issue here is how best to package shared JARs in EAR files.
Problem: Portable way to share JARs
The challenge is to satisfy the following two criteria:
򐂰 Share JARs across multiple modules without replication, because copies
cause maintenance problems.
򐂰 Provide a portable solution, one that will not require changes when deploying
to another server.
102
Migrating WebLogic Applications to WebSphere V5
Recommendation
As documented in WebSphere Studio Application Developer help, this is the only
J2EE-defined, portable way to use a JAR file.
򐂰 For a third-party JAR within a Web project:
a. Import Zip file as file system to avoid expansion.
b. Import into WebProject/webApplication/web-inf/lib folder.
c. JAR file is automatically added to Java build path — no changes are
required for runtime.
򐂰 For third-party JAR for multiple EJB or Web projects:
a. Import Zip file as file system to avoid its expansion.
b. Import into Enterprise Application project that contains the EJB or Web
projects.
c. The JAR is automatically added to Java build path — no runtime changes
needed.
d. Add dependencies between projects with Edit Module Dependencies
pop-up — this modifies the Manifest files.
Note that the alternative of using a global build and server classpath is not
recommended because the application will not be easily portable.
Problem: Improper override of system library
Another kind of invalid EAR is constructed when it contains different versions of
JARs that are already in the server or development system — for example,
javax.xml packages. We have not experienced this particular problem directly,
but it has been reported by other migration efforts.
Recommendation
Identify any overriding JARs during baseline verification and source staging.
Avoid their use unless absolutely necessary. If it is absolutely necessary, make
sure it is compatible with the target server. If something weird happens, such as
a server runtime crash, check for this kind of conflict. WebSphere Studio
Application Developer helps identify these kinds of problems.
4.2.5 Project and server folder checkpoints
Experimentation is a natural part of the migration process. This is especially true
when you are also learning how to use a new set of tools. It is useful to
periodically checkpoint your current work in a form that is easily restored when
you want to try another alternative. The source control system typically supports
this function.
Chapter 4. Migration issues
103
Problem: Revert to previous state of migration
For a J2EE application, the EAR file in a natural unit for major checkpoints and
baselines. Although much smaller, server configurations are also repositories of
application configuration information that you may wish to checkpoint.
Sometimes you want to temporarily checkpoint the state of your migration as
represented by the WebSphere Studio Application Developer workspace and its
current server configuration. This was particularly true for our small migration
examples.
Recommendation
For our examples, we used checkpoints described in 3.3.3, “Project checkpoints”
on page 29, and 3.3.4, “Server folder checkpoints” on page 31. These
checkpoints are available in the additional materials accompanying this paper.
4.3 Follow the standards
This section reports standards violations experienced during migration of the
examples in Chapter 5, “Migration examples” on page 125. If these errors are
typical, you can expect similar problems with other WebLogic migrations.
Most of these errors must be corrected for successful compilation and execution.
We discovered and corrected these errors in our simple examples using
WebSphere Studio Application Developer and its test server. A few of these
errors were only discovered by testing. A large migration effort would benefit
from code inspections to find some of these errors.
4.3.1 PortableRemoteObject narrow
The use of the IIOP protocol mandates that returned stub objects must use the
PortableRemoteObject narrow method to help cast them to the correct interface
types. WebLogic applications using the proprietary t3 protocol do not require this
treatment. This practice has produced examples that give the mistaken
impression that PortableRemoteObject narrow is optional. It may work on your
system now, but it is sure to cause failures in the future.
Some developers are unsure of when to use PortableRemoteObject narrow.
Indeed, in our migration examples, we observed two kinds of improper use of
PortableRemoteObject narrow.
򐂰 Not used when it is required.
򐂰 Used when it is not required.
The first is clearly the most serious, but the second is also a concern.
Unfortunately, there is no reliable static or runtime check to determine when
104
Migrating WebLogic Applications to WebSphere V5
PortableRemoteObject narrow is required. Developers must learn when it is
required. Vendors may optimize away its use for certain cases. We observed this
in our migration examples, where one version of the ORB required it, while
another did not.
To help clarify this requirement, all of the following must be true for the
PortableRemoteObject narrow requirement to apply:
1. Using IIOP.
The t3 protocol, for example, does not require PortableRemoteObject narrow.
Of course, when you eventually migrate to IIOP, it will be required.
2. The stub being returned is for a remote object.
Stubs for local EJB objects do not require PortableRemoteObject narrow.
3. The stub object requires an explicit Java cast.
This requirement comes from the CORBA world where stubs need not
implement the remote interface of the referenced object. For J2EE, this limits
its use to a small number of methods. InitialContext lookup is the most
commonly used one, and Handle getEJBObject is another. These methods
return the type Object, which must be cast before use.
As a special note, PortableRemoteObject narrow is not needed for EJB
remote method calls. If the type of the returned object does not require a cast,
then PortableRemoteObject narrow is not required either. Please note that the
example in Chapter 9 of Migrating WebLogic Applications to WebSphere
Advanced Edition V4, SG24-6179 makes this error, as does the BankBean in
the one2many migration example. These errors result from an overly
aggressive interpretation of the J2EE specifications.
If you happen to use PortableRemoteObject narrow where it is not needed or
required, it just returns the original object. If you fail to use it where it is needed,
you get a ClassCastException. In the general case, PortableRemoteObject
narrow may invoke the class loader, and download additional classes.
Problem: PortableRemoteObject narrow is not optional
In the process of migrating examples from the t3 protocol to the IIOP protocol, we
had to convert to PortableRemoteObject narrow for each use of InitialContext
lookup.
Recommendation
Check all InitialContext lookup statements during migration. It is easier to find
these modifications by inspecting the source code directly.
Chapter 4. Migration issues
105
Lookup of local EJBs
The one2many example has two local EJBs. Although PortableRemoteObject
narrow is not required to look up the homes of these objects, it is in general not
obvious from the code that a lookup is for a local interface. Indeed, the same
lookup statement can be used for local or remote lookups. Use the
PortableRemoteObject narrow for the following case:
򐂰 You are not certain that the lookup is for a local EJB.
򐂰 The lookup is used for both local and remote EJBs.
򐂰 You want to be able to switch from local to remote without having to change
the code.
Type hierarchy analysis
In the one2many example, we used WebSphere Studio Application Developer
tools to help us understand the type hierarchy used by PortableRemoteObject
narrow. We analyzed the relationship between the stub _ObjectStub and the
home interface BankHome. For details, see 3.3.8, “Using type hierarchy browser”
on page 48. From this analysis, it was clear that PortableRemoteObject narrow is
required, and that its processing is non-trivial.
Problem: Unnecessary use of PortableRemoteObject narrow
Figure 4-1 on page 107 shows an example of before and after code from the
one2many BankBean. Since the AccountHome create method returns type
Account, no Java cast is needed, so the PortableRemoteObject narrow is not
needed. This is one of three similar errors in the one2many example — two in
BankBean and one in Client.java.
Recommendation
Manually review all uses of PortableRemoteObject for this kind of error. If it is
used with other than the InitialContext lookup or Handle getEJBObject methods,
it is probable an error. If the code compiles without a Java cast, the
PortableRemoteObject narrow is not needed.
106
Migrating WebLogic Applications to WebSphere V5
Figure 4-1 Remove unnecessary use of PortableRemoteObject narrow [before and after]
4.3.2 EJB references
EJB JNDI names are covered in detail in the JNDI chapter of Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179. Since this is an
area that is not well understood, here is a review of the requirements:
1. The lookup code for each EJB reference must use the local JNDI context.
An EJB reference is where one EJB references another EJB. This is typically
implemented in the EJB code by an InitialContext JNDI lookup. This lookup
must use a local JNDI name — that is, a JNDI name defined in the local EJB
context java:comp/env. According to the EJB 2.0 specification, use of the local
Chapter 4. Migration issues
107
context is not optional. The only thing that is optional is the subcontext name
— it is recommended that you use java:comp/env/ejb/something, but you are
allowed to use java:comp/env/somethingelse.
A similar deployment descriptor is required by the J2EE 1.3 specification for
standard J2EE application clients:
– They must also use the local JNDI java:comp/env context.
– They must also be deployed with ejb-ref deployment descriptors.
In 4.5.1, “Lightweight application client” on page 117, we consciously violate
this standard. Use of such a lightweight client is non-standard and
non-portable.
2. Each EJB reference requires a standard ejb-ref deployment descriptor.
The EJB 2.0 specification requires the use of ejb-ref deployment descriptors.
Each EJB reference must have one. The name of an ejb-ref deployment
element is the local JNDI name used for its lookup, minus the java:comp/env
context.
Unfortunately, no one complains if the ejb-ref deployment descriptor is
missing. Your application may or may not execute correctly, depending on
what JNDI name is used in the JNDI lookup.
– If you follow the specification and use a local context name of
java:comp/env, but your ejb-ref deployment descriptor is missing or
incorrect, you get a JNDI naming exception at runtime.
– If you ignore the specification altogether and use a name in some other
global JNDI context, your application will execute properly if that name
happens to resolve to the expected EJB home. This is true regardless of
the presence of an ejb-ref deployment descriptor, because this descriptor
will not be exercised without a local JNDI name lookup. In this case,
modification of an ejb-ref deployment descriptor will have no effect — this
should be a clue that something is wrong.
3. In WebSphere, each EJB home must be bound to a global JNDI name.
This is so that it can be found by clients and other EJBs. This JNDI name is
specified in a vendor-specific deployment descriptor. In WebSphere, this is in
the ibm-ejb-jar-bnd.xmi file.
If this binding is missing, the WebSphere server will complain when you start
the application.
4. In WebSphere, each ejb-ref must be bound to a global JNDI name.
The local JNDI name of the ejb-ref must be bound to a global JNDI name that
satisfies the required home interface. As with the JNDI names for EJB homes,
this binding is recorded in a vendor-specific deployment descriptor. The
108
Migrating WebLogic Applications to WebSphere V5
optional ejb-link deployment descriptor may be used to assist in this
resolution. See 4.4.5, “ejb-link” on page 115.
An incorrectly bound ejb-ref will result in a JNDI naming exception at runtime,
provided that the Java code actually references it by its local JNDI name.
5. In WebLogic, global JNDI names are not always required.
It is customary in WebLogic to use global JNDI names for EJBs and EJB
references. However, this is not always required. See 4.4.5, “ejb-link” on
page 115, for cases where global JNDI names are not required.
Problem: EJB reference deployment is not optional
In our examples, only the one2many example uses EJB references. None of
these references followed the J2EE standard.
򐂰 The InitialContext lookup code used global JNDI names.
򐂰 There were no EJB reference deployment descriptors.
Because these references are to local EJB interfaces, their lookups fail at runtime
in WebSphere — for details, see 4.3.3, “EJB references to local interfaces” on
page 110.
If they were references to remote EJB interfaces, the runtime lookups would
have actually worked in WebSphere. Even though the code violates the
standard, it can still work because the global JNDI names resolve to the desired
EJB homes. No doubt, correct execution of non-compliant code encourages
future non-compliance. With WebSphere, however, this is only true for remote
EJBs. Non-compliant local EJB references fail to execute in WebSphere.
Recommendation
Even though non-compliant remote EJB references may work, we recommend
that you correct them. The corrected EJB references:
򐂰 Provide assemblers with important structural information needed for
deployment.
򐂰 Make code more adaptable to future changes.
As described in “Upgrade to use standard EJB references” on page 158, this
correction has two parts:
򐂰 Modify Java code to use the java:comp/env local JNDI context.
򐂰 Provide a deployment descriptor for each EJB reference as described in
3.4.3, “Bind local JNDI name to EJB reference” on page 60.
Chapter 4. Migration issues
109
Since these errors are hard to detect, we recommend reviewing the code to find
them. Examine all InitialContext lookups, along with their corresponding
deployment descriptors for EJB references.
4.3.3 EJB references to local interfaces
The introduction of local interfaces in EJB 2.0 is accompanied by a
corresponding new ejb-local-ref standard deployment descriptor. However, local
beans must still follow the same EJB reference rules described in 4.3.2, “EJB
references” on page 107.
򐂰 They must be looked up by a local JNDI name.
򐂰 They must have an ejb-ref deployment descriptor.
Problem: Lookup of local EJB fails without local JNDI
The EJB references in the one2many example are local EJB references. As
described in “Problem: EJB reference deployment is not optional” on page 109,
they do not follow the J2EE standards. In WebSphere, this causes a runtime
JNDI naming exception. The practice of using global JNDI names in
InitialContext lookup statements — ignoring the EJB 2.0 standard for EJB
references — causes application failure for local EJB lookups.
Recommendation
Since this code fails, it must be corrected. Convert to the J2EE standard as
described in “Recommendation” on page 109.
To review, InitialContext lookups for local EJB interfaces:
򐂰 Do not require PortableRemoteObject narrow — see “PortableRemoteObject
narrow” on page 104.
򐂰 Must use the local JNDI naming context.
򐂰 Must have EJB reference deployment descriptors.
4.3.4 Syntax and completeness errors
During the course of our migration examples, we had to correct several serious
syntax errors. Apparently WebLogic tolerates these errors, but portability
demands that you follow standard syntax.
Errors in deployment descriptors are likely to cause related parsing and compile
errors in other files. For this reason, we recommend that errors in deployment
descriptors be corrected before examining other errors.
110
Migrating WebLogic Applications to WebSphere V5
Problem: An ejb-name must be a proper Java identifier
The ejb-jar.xml file for the one2many example uses syntactically incorrect names
for EJBs. Although WebSphere Studio Application Developer only flagged these
as warnings, ignoring the warnings eventually caused serious errors. We had to
fix these errors.
Recommendation
Use WebSphere Studio Application Developer. It is very good at catching such
errors. Also, when you change a name, it is important to make sure you find all
occurrences of the name. In this case, the names were used in several places
that did not get flagged. For details, see “Fix invalid names in <ejb-name>
descriptor” on page 133.
Problem: Incorrect version in DOCTYPE is a serious error
In the filters example, the web.xml DOCTYPE had inconsistent and incorrect
version information. Filters require the web-app_2_3 DTD, but the web-app_2_2
DTD was declared. Not only did this cause the <filter> descriptors to be
unrecognized, it caused WebSphere Studio Application Developer to compile the
Java code with the incorrect J2EE 1.2 libraries.
Recommendation
After importing from the staging folder, verify that your imported code is using
correct versions of the J2EE specifications. Carefully examine the DOCTYPE
headers in deployment descriptor files. We corrected invalid version information
in WebSphere Studio Application Developer. However, given that incorrect
version information can have a cascade effect, if is probably best to make these
modifications in the staging folder and re-import into WebSphere Studio
Application Developer. For details, see “Correct web.xml file” on page 210.
Problem: Erroneous deployment descriptor for servlet filter
In the filters example, the <filter> deployment descriptors provided in web.xml file
were syntactically incorrect. They were in the wrong position according to the
web-app_2_3 DTD. Consequently, the entire web.xml deployment descriptor
could not be parsed.
Recommendation
WebSphere Studio Application Developer is good at detecting such errors. It is
also very easy to correct them with the WebSphere Studio Application Developer
XML editor. For details, see “Correct web.xml file” on page 210.
Problem: Incorrect use of the HTML <font> tag
Two of the JSP files in the filters example use the <font> tag incorrectly.
Chapter 4. Migration issues
111
Recommendation
This is a relatively minor error, but with the help of the WebSphere Studio
Application Developer Context Assist tool, it is easy to fix and easy to avoid in the
first place. For details, see“Fix minor HTML errors” on page 214.
4.3.5 Invalid exceptions
The J2EE rules for exceptions are complex, especially with the introduction of
such new features as MDB and local EJBs. Developers naturally make errors —
cut-and-paste errors are common — so developers need good tools to help
improve quality.
Problem: Incorrect exception declarations — minor
During the course of our migration examples, we discovered the following errors
in exception declarations. These errors include both coding and Javadoc
documentation errors. All were detected by WebSphere Studio Application
Developer tools.
򐂰 Local home methods in the one2many example were documented as
throwing a RemoteException. Local methods are not allowed to throw
RemoteExceptions.
򐂰 Bean methods in the one2many example throw RemoteException. Beans are
not allowed to throw RemoteExceptions.
򐂰 A method in the MDB class throws an application exception. MDB classes are
not allowed to throw application exceptions because applications cannot call
them.
Recommendation
Use WebSphere Studio Application Developer and its Javadoc export tool to
locate and correct such errors. Even though these errors could be ignored, we
recommend fixing them. Documentation errors may actually be more serious
than the coding errors. Clients following incorrect Javadocs will create additional
errors in their code. For details, see Figure 5-7 on page 137, “Debug Javadoc
tags” on page 162, and 5.3.2, “Import source code” on page 172.
4.4 J2EE 1.3 features
We looked at a selection of the new J2EE 1.3 features. They all worked as
advertised, so we have no compliance or compatibility issues to report. However,
we expect that differences in deployment, and restrictions on the use of the new
features will require additional training.
112
Migrating WebLogic Applications to WebSphere V5
Here is a summary of the issues in this section:
򐂰 An experienced developer can usually determine deployment needs by
studying the options available in the WebSphere Studio Application
Developer Deployment Descriptor editors. However, differences between
WebLogic and WebSphere deployment models for the following two features
are less obvious and may required additional training:
– CMP 2.0 connection factory.
– MDB/JMS listener port.
򐂰 A warning from the J2EE specifications on the use of local interfaces.
򐂰 J2EE form-based authentication solves a proprietary WebLogic migration
issue.
򐂰 An update on the ejb-link issue.
4.4.1 Deployment of CMP 2.0 connection factory
The WebSphere deployment of CMP 2.0 beans requires the use of an unusual
JNDI name. This name is for the CMP connection factory. It is based on the JNDI
name used for the associated DataSource.
1. Establish the DataSource JNDI name, jdbc/Sample for example.
2. Use it to build the connection factory name, in this case
eis/jdbc/Sample_CMP.
Problem: Unusual JNDI name for connection factory
This approach is different from the WebLogic model, and it is not altogether
obvious from the Deployment Descriptor editor. As noted in the WebSphere
Studio Application Developer documentation, failure to follow this procedure
results in runtime startup failure with few clues on how to resolve the problem.
Recommendation
This comes under the heading 4.2.1, “Learn the new tools” on page 100. In
particular, use the WebSphere Studio Application Developer help facility. See
3.4.1, “CMP 2.0 deployment” on page 57, for detailed instructions in this paper.
4.4.2 Deployment of MDB/JMS listener port
This is another situation where WebSphere deployment uses an unfamiliar
model.
򐂰 To deploy an MDB, WebLogic uses a pair of JMS JNDI names, one of which
is usually defaulted.
Chapter 4. Migration issues
113
򐂰 WebSphere deploys with a construct called a listener port. The listener port is
defined as part of the JMS configuration, and it knows about the required pair
of JMS JNDI names.
Problem: Listener port new to WebLogic developers
Discovering the details of this deployment, without training, can be frustrating
and time consuming.
Recommendation
This also comes under the heading 4.2.1, “Learn the new tools” on page 100. In
addition, the JMS configuration steps are somewhat complex. For detailed
instructions, see 5.3.3, “Deploy MDB” on page 174, and 5.3.4, “Configure JMS
service” on page 176.
4.4.3 Use of local interfaces
The J2EE specifications contain strong warnings about the use of the local
programming model introduced by local EJB interfaces. This is because the
arguments passed to local EJBs are passed by reference and are shared
between the caller and the callee.
򐂰 Do not assign the state of one EJB to the state of another EJB.
򐂰 Do not use references passed across the local interface outside of the
immediate call chain.
򐂰 Never store passed-in references as part of the state of another EJB.
򐂰 These warnings are particularly critical where there may be a change in
transaction or security context.
Problem: Misuse of local EJB sharing
We did not notice any of these violations in the simple local EJBs that we tested.
We are, however, concerned about potential improper use. This concern is
prompted by the following:
򐂰 Misuse has undefined behavior.
򐂰 Similar usage violations have been observed in previous migration projects,
for example, invocation of EJB methods outside the EJB container.
򐂰 These restrictions are not easily checked, mechanically or manually.
򐂰 In 4.3.3, “EJB references to local interfaces” on page 110, we did observe
invalid deployment of local EJB interfaces.
114
Migrating WebLogic Applications to WebSphere V5
Recommendation
Do not violate these restrictions. This is easy to say and hard to check. Things
that can be done during a migration effort include the following:
򐂰 Carefully examine deployment and invocation of local interfaces.
򐂰 Review the state variables of local EJBs for clues to misuse.
򐂰 If you are concerned about a particular local EJB, try to temporarily convert it
to a remote EJB to see if it behaves differently. Depending on its coupling,
this may not be easy to do. In particular, this is not possible for CMP beans
with CMRs.
4.4.4 J2EE form-based authentication
J2EE 1.3 mandates that servers support a standard Web-based mechanism for
performing form-based authentication. Every compliant server must support the
following:
򐂰 The new <login-config> deployment descriptor for the web.xml file.
򐂰 An HTTP action, called j_security_check, that authenticates a user session by
a vendor-provided mechanism.
򐂰 Two variables, j_username and j_password, for use in the login form.
Problem: Convert proprietary WebLogic authentication
WebLogic applications may use the proprietary ServletAuthentication class in the
weblogic.servlet.security package to implement custom form-based
authentication. This must be replaced as part of migrating to WebSphere. We
had to do this as part of the filters migration example.
Recommendation
Use the new standard J2EE form-based authentication to replace proprietary
WebLogic authentication, and to promote future portability. For details, see 5.4.4,
“Convert to portable form-based J2EE authentication” on page 220. For a secure
version, see 5.4.5, “Secure session tracking” on page 231.
4.4.5 ejb-link
An ejb-link is an optional descriptor for EJB references. It is used for references
to EJBs contained in the same application. While the ejb-link deployment
descriptor is not new to J2EE 1.3, it is included here because of the following:
򐂰 The ejb-link deployment descriptor was mentioned as an issue in Migrating
WebLogic Applications to WebSphere Advanced Edition V4, SG24-6179. Full
Chapter 4. Migration issues
115
support for ejb-link could reduce the tedium involved in deploying EJB
references.
򐂰 Support for ejb-link has improved in the latest versions of both WebLogic and
WebSphere. This was apparently motivated by the introduction of references
to local EJBs, and CMRs in particular, which must use local EJBs.
Depending on interpretation, implementation of the ejb-link specification can be
used to do either one or both of the following:
򐂰 Semi-automate deployment by assisting the application assembler, through
tools support, in deploying EJB references to EJBs contained within the same
application.
򐂰 Fully automate deploying EJB references to EJBs contained within the same
application.
Either of these alternatives represents an improvement over fully manual
deployment, and can save effort in the deployment of EJB references. Each of
these approaches has a variation regarding how it deals with the vendor-specific
global JNDI name of an EJB reference:
򐂰 Automate its insertion into the vendor’s extended descriptor.
򐂰 Eliminate it altogether, and simply use the ejb-link to find the EJB.
Implementation differences
Although we did not thoroughly investigate this issue, it is not surprising to find
that the two servers have implemented different strategies:
򐂰 WebSphere appears to have taken the semi-automated approach. The global
JNDI name is still required, but it is inserted automatically by the WebSphere
Studio Application Developer Deployment Descriptor editor. The editor is
described in 3.4.3, “Bind local JNDI name to EJB reference” on page 60.
Although local EJBs continue to require global JNDI names, these names are
not visible from outside of the server. In the JNDI explorer in Figure 5-18 on
page 160, notice that the local JNDI names are listed in their own local
context.
򐂰 WebLogic appears to have taken the fully automated approach, and has
eliminated the need for the global JNDI name altogether. We got this
information from the documentation and did not test it directly.
If a local EJB is only referenced by ejb-link, this means that the EJB requires
no global JNDI name at all! Neither the EJB home nor its EJB references
require a global EJB name.
116
Migrating WebLogic Applications to WebSphere V5
4.5 Client portability issues
The issues in this section deal with client code that is not covered directly by the
J2EE specifications. We had to make source code changes to deal with each of
these issues during the course of our migration examples. In each case, we had
to make trade-offs between more portable and less portable solutions. In
particular, with respect to the J2EE standards, lightweight application clients are,
in general, non-standard and non-portable.
򐂰
򐂰
򐂰
򐂰
򐂰
Lightweight application client.
Converting from the t3 protocol to IIOP.
Portable JNDI InitialContext.
EJB interfaces and stubs in lightweight clients.
Portable JNDI names in clients.
4.5.1 Lightweight application client
The J2EE specifications define three types of containers, only one of which is for
application clients:
򐂰 EJB container.
򐂰 Web container.
򐂰 Application client container.
In practice, however, there are at least three different application client models.
These are described in the Java clients paper, was/pdf/nav_clients.pdf, at
http://www-3.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter.
򐂰 Applet client embedded within an HTML document and invoked by a browser.
򐂰 Application client container specified in the J2EE specifications.
򐂰 A Java thin application client, also called a lightweight application client.
The standard application client is relatively heavyweight. It supports the
following:
򐂰 A local environment, similar to the EJB local environment, with:
– Deployment descriptors.
– The java:comp/env context.
򐂰 Support for the portable, zero-argument new InitialContext.
򐂰 A launchClient.bat that:
– Sets up the J2EE libraries.
– Provides all needed EJB interfaces and stubs.
– Takes an EAR file as an input parameter.
Chapter 4. Migration issues
117
In 5.3.8, “Standard J2EE application client” on page 194, we deployed the
message example as a standard J2EE application client.
The lightweight application client model follows none of the above rules. As such,
it is non-standard and non-portable.
Problem: Application client model trade-offs
Two of the WebLogic examples that we migrated use a variation on the
lightweight application client model. They also included WebLogic dependencies,
so code modifications were required to make them run on WebSphere.
Our dilemma was how to balance the following:
򐂰 Use as much as possible of the WebSphere Studio Application Developer
support for standard J2EE application clients.
򐂰 Make the deployed client as lightweight as possible — this keeps it close to
the familiar WebLogic model.
򐂰 Make the deployed client code as portable as possible.
Recommendation
We struck the following compromise for migrating lightweight WebLogic
application clients to WebSphere:
򐂰 Include the client code as a standard J2EE application client within
WebSphere Studio Application Developer. This way, the application client is
embedded within the J2EE application project and its EAR file.
See 3.3.5, “Application client modules” on page 34, for instructions on how to
import and export this style of application client JAR file.
򐂰 Restrict use of standard J2EE application client features as follows:
– Do not rely on client deployment descriptors.
– Do not use local environment features — this means you must use global
JNDI names for InitialContext lookups.
򐂰 Implement the InitialContext as described in 4.5.3, “Portable JNDI
InitialContext” on page 120.
򐂰 Provide EJB interfaces and stubs as described in 4.5.4, “EJB interfaces and
stubs for lightweight clients” on page 121.
򐂰 Provide local environment information by command parameters or system
environment arguments. One example of this is described in 4.5.5, “Portable
environment variables in lightweight clients” on page 122.
118
Migrating WebLogic Applications to WebSphere V5
򐂰 In place of the full J2EE environment, add the WebSphere client.jar file to the
client’s classpath. We discovered that this small JAR file provides the
minimum additional classes needed for an application client.
򐂰 Invoke this lightweight application client with a simple command script like the
one in Example 5-1 on page 151.
Problem: Lightweight model depends on vendor JARs
The lightweight model described above did not work for the message example
without modifications. The problem was that the global JNDI lookup for the JMS
connection factory failed to return an object of type QueueConnectionFactory.
For details, see 5.3.6, “Test cycle” on page 185. We eventually resolved this
problem by adding several vendor JARs to the classpath, but this process
disrupted the normal migration process. You can expect this kind of problem
when a lightweight application client uses a resource that requires a connection
factory.
Recommendation
First, migrate to the standard J2EE application client model. If you encounter
problems using the lightweight model, convert to the lightweight model as an
optimization step, after the migrated application is running correctly. We followed
this strategy for the message example, and also managed to retain J2EE
portability. For details, see 5.3.9, “Lightweight JMS client” on page 201. Testing
with the standard client model can have the added advantage of helping to
discover non-portable code. For an example of this, see “Non-portable JMS
code” on page 189.
4.5.2 The t3 protocol
The t3 protocol is often a migration issue for WebLogic application clients. While
there may be some advantages to this proprietary protocol, IIOP provides a more
portable solution.
Problem: Convert to IIOP protocol
The application clients of our migration examples required migration from the t3
protocol to IIOP, in order to run on the WebSphere server.
Recommendation
Convert to IIOP with the following steps:
򐂰 Convert to the use of PortableRemoteObject narrow as described in 4.3.1,
“PortableRemoteObject narrow” on page 104.
Chapter 4. Migration issues
119
򐂰 Convert to the zero-argument InitialContext as described in 4.5.3, “Portable
JNDI InitialContext” on page 120. In part, this replaces the t3 protocol with the
IIOP protocol, in the URL for the JNDI server.
4.5.3 Portable JNDI InitialContext
The creation of a new InitialContext object takes a Properties object with the
following minimal information:
򐂰 The JNDI name of the initial context factory for your server.
򐂰 The URL for the JNDI server — for WebLogic, this URL may specify the t3
protocol.
These parameters can also be provided by other means. For example, you can
use a jndi.properties file in the client’s classpath. In this case, the zero-argument
form of the new InitialContext method can be used, and no properties object is
required in the Java code.
Problem: Remove hard coded InitialContext properties
The application clients of our migration examples contained hard-coded,
WebLogic-specific properties for the InitialContext object. These properties had
to be changed to WebSphere specific values.
Recommendation
There are two portable ways of specify JNDI initial context properties. Using
either of these techniques allows the properties to be changed without changing
the Java code. The client code becomes portable between WebLogic,
WebSphere, and other J2EE servers.
򐂰 Use -D parameters on the Java command for these properties.
򐂰 Provide a jndi.properties file in the classpath of the application client.
We recommend the jndi.properties alternative. Replace hard-coded WebLogic
InitialContext code with portable code as follows:
򐂰 Use the zero-argument new InitialContext method.
򐂰 Add a jndi.properties files to the classpath of the client.
򐂰 For WebSphere, it is also necessary to add another file to the classpath —
the optional jndiprovider.properties file.
For details, see “Remove hard-coded JNDI InitialContext properties” on
page 152.
120
Migrating WebLogic Applications to WebSphere V5
4.5.4 EJB interfaces and stubs for lightweight clients
Application clients must include all necessary EJB interfaces and stubs. In a
lightweight client, these must be part of the client JAR or another JAR in the
classpath. WebLogic provides tools, the ejbc command for example, that
automatically create a JAR with the EJB interfaces. Moreover, the WebLogic t3
protocol dynamically provides stubs as needed at runtime. We know of no
equivalent features for use with WebSphere.
Problem: Provide interfaces and stubs to lightweight clients
When migrating a lightweight application client from WebLogic to WebSphere,
some extra work is required to make EJB interfaces and stubs available to the
WebSphere application client. We had to do this for the one2many example.
Recommendation
The EJB interface and stub classes can be provided to the application client in
either of two ways:
򐂰 Add them to the client’s JAR file.
򐂰 Put them in a new JAR and add that JAR to the classpath.
We recommend the second approach because it is more flexible. It is also similar
to what is typically done in WebLogic, because the WebLogic ejbc command
automatically produces this JAR with the interface classes. Unfortunately,
WebSphere Studio Application Developer does not yet provide a similar function.
Instead, you can use the JAR export feature to selectively add files to a JAR. See
“Add interfaces to application client classpath” on page 155 and “Add interface
stubs to application client classpath” on page 158 to see how we constructed this
JAR for the one2many example.
Dynamic download of remote interface stubs
The RMI protocol supports dynamic downloading of interface and stub classes.
Stand-alone RMI applications typically used this feature. We experimented with
using this in the context of J2EE IIOP, but had only limited success.
򐂰
򐂰
򐂰
򐂰
We added an IIOP path to the classpath.
A request was made to download an EJB interface class.
A security problem disallowed the request — we did not pursue further.
The next step would be to install an appropriate security policy file.
This RMI feature was complicated, possibly irrevocably, with the introduction of
RMI-IIOP and the deprecation of RMI security. We will probably see future
improvements in this area.
Chapter 4. Migration issues
121
4.5.5 Portable environment variables in lightweight clients
To avoid hard-coding parametric information, EJBs and standard J2EE
application clients are deployed with local JNDI environment variables. Since the
local environment is not available in lightweight clients, they must use a
non-J2EE mechanism like the following:
򐂰 Use -D parameters on the Java command.
򐂰 Extract properties from operating system environment variables.
򐂰 Store properties in one or more application-specific configuration files.
Problem: Remove hard-coded JNDI names
The message example contains two hard-coded JMS-related JNDI names. Our
alternatives were:
򐂰 Keep the code unchanged and configure JMS with the original JNDI names.
At best, this would be highly misleading in WebSphere because one of the
JNDI names was weblogic.jms.ConnectionFactory.
򐂰 Change the code to be more portable, using one of the methods mentioned
above.
Recommendation
If there are only a few such environment variables, we recommend the use of
command parameters. For larger collections of variables, configuration files are
probably best. In either case, the resulting lightweight client code is more
portable. For details on what we did for the message example, see 5.3.5,
“Migrate client code” on page 183.
4.6 Data mapping issues
Data mapping is a large and complex area. We only address a small part of the
picture in this paper.
򐂰 We exercised a few of the new CMP 2.0 features.
򐂰 We refined techniques for decoupling database migrations from application
migrations.
4.6.1 Impact of CMP 2.0 features
The one2many example exercises the migration and deployment of a few of the
new CMP 2.0 features. No specific problems were encountered with these
features.
򐂰 Local interfaces.
122
Migrating WebLogic Applications to WebSphere V5
򐂰 One-to-many CMR.
򐂰 Cascade delete.
From a migration perspective, CMP 2.0 offers a conversion path for simple data
mapping applications, to use a portable data mapping standard. CMP 2.0
features could have a significant impact on future applications because they
begin to fill the need for portable fine-grained, data mapping support. For
WebLogic applications, TopLink has been a major third-party alternative in this
space. It is much more powerful than the current CMP 2.0 features. However,
with its recent acquisition by Oracle, CMP 2.0 data mapping features may start to
become more popular. WebLogic also offers other proprietary data mapping
features that we do not address in this paper.
򐂰 EJB QL extensions, including select distinct, orderby, dynamic query, and
subquery.
򐂰 Primary key features, such as multiple CMP fields, anonymous, and
automatic generation.
򐂰 Multiple table mapping.
򐂰 Automatic table creation.
4.6.2 Decoupling database conversion
In Migrating WebLogic Applications to WebSphere Advanced Edition V4,
SG24-6179, we recommend that database migration be decoupled as much as
possible from application migration. Make sure you have a working application
before and after the database migration. The coordination of the application
migration with the database migration depends on application details. It may be
best to do the database migration before, after, or during the application
migration, or even in multiple phases. We discuss several examples here.
Problem: Target database not available
The one2many example included an optimization for the cascade delete
operation that was designed for an Oracle database server. We did not have an
Oracle database server available during this migration exercise.
Recommendation
In this case, we chose to do the database migration in two phases:
1. Remove the optimized cascade delete dependency before the application
migration. We did this by first migrating to the available PointBase database
server without the optimized cascade delete feature.
2. As the last step of the application migration, we converted the PointBase
database to a DB2 database.
Chapter 4. Migration issues
123
Problem: Schema changes impact application code
The following decoupling dilemma may arise when you attempt to do the
database migration followed by the application migration:
1. The database migration creates a new and different schema.
2. The application code is impacted by the new database schema, so the
database migration cannot be tested until the application is migrated to the
new schema.
3. Since the migration target may be the new server, the application migration
must be done before or in parallel with the database migration.
We experienced this dilemma in the one2many example. Migrating the original
WebLogic schema to DB2 would require application changes that we were not
ready to test until the application itself was migrated to WebSphere. This could
be a serious problem with a large, complex application.
Recommendation
Do a two-phased application migration, starting with a temporary top-down RDB
schema.
1. Generate a temporary schema from the original source code using the
top-down RDB mapping.
2. Create a test database using the temporary schema.
3. Migrate the application to the target server using the temporary schema and
the test database.
4. Based on the original schema, perform the real database migration.
5. Use the meet-in-the-middle RDB mapping to convert the migrated application
to the final database, making additional source code and deployment
changes as needed.
Problem: Convert WebLogic QL to EJB QL
This problem is analogous to “Problem: Target database not available” on
page 123. The query language is available on the target WebSphere server, but
the proprietary WebLogic query language is not. You will not be able to test the
WebLogic QL during application migration.
Recommendation
Convert from WebLogic QL to EJB QL first, before migrating the application. Our
examples do not cover this conversion, but Chapter 9 on Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179 provides a brief
introduction.
124
Migrating WebLogic Applications to WebSphere V5
5
Chapter 5.
Migration examples
This chapter describes the migration of three simple examples that use new
J2EE 1.3 features. Following our step-by-step approach should help you identify
migration issues unique to your project. We provide specific advice on the
migration process and the use of WebSphere Studio Application Developer tools.
© Copyright IBM Corp. 2003. All rights reserved.
125
5.1 Introduction
This chapter contains the step-by-step details of how we migrated three sample
WebLogic applications:
1. 5.2, “One2many example — CMP 2.0 with CMR” on page 126.
2. 5.3, “Message example — MDB and JMS” on page 169.
3. 5.4, “Filters example — servlet filters and authentication” on page 203.
Each example uses a variation on the migration process outlined in 4.2,
“Migration process” on page 99. Each step is presented as a discovery process,
including:
򐂰
򐂰
򐂰
򐂰
What we expected.
What actually happened.
The migration problems we discovered.
Alternatives for solving each problem, and what we actually did.
We provide project and server folder checkpoints for each of the steps as part of
the additional materials. Chapter 4, “Migration issues” on page 97, summarizes
our discoveries into a list of issue areas, problems, and recommendations.
A major theme of these examples is the introduction of WebSphere Studio
Application Developer tools. We highlight the tools we found most useful for
migration work in Chapter 3, “Migration tools” on page 19. The use of other tools
are detailed in this chapter.
5.2 One2many example — CMP 2.0 with CMR
This example is distributed with BEA WebLogic Server V7. We chose it because
it demonstrates the following new features of Enterprise JavaBean 2.0:
򐂰 Local EJBs — see 2.5.1, “Local beans” on page 11.
򐂰 A CMP 2.0 one-to-many relationship — see 2.5.2, “CMP 2.0 and CMR with
cascade delete” on page 12.
򐂰 The WebLogic proprietary cascade delete feature, designed to work with an
Oracle database.
As a small example, it should be easy to migrate, allowing us to come up to
speed on the new WebSphere Studio Application Developer tools support.
This example has no Web component. As depicted in Figure 5-1 on page 127, it
consists of three EJBs and an application client.
126
Migrating WebLogic Applications to WebSphere V5
EJB Srver
Bank
(Session Bean)
Remote
Client
(Application
Client)
Local
Bi-directional
CMR
Cascade
Delete
Customer 1
(CMP 2.0
Entity Bean)
Local
m
Account
(CMP 2.0
Entity Bean)
Figure 5-1 Components of the one2many example
The folder samples/server/src/examples/ejb20/cascadeDelete/one2many
contains the distributed WebLogic source code. It consists of:
򐂰 Java code for:
– A remote session EJB named BankBean.
– Two local entity EJBs named CustomerBean and AccountBean that
participate in a one-to-many relationship — each customer can have
multiple accounts and each account belongs to a single customer.
– An application client named Client.
򐂰 The ejb-jar.xml, application.xml, and WebLogic specific deployment
descriptor files.
򐂰 Associated Javadoc HTML files, including instructions on how to build and
run the example.
򐂰 An Ant build.xml script for building, deploying, and running the example.
򐂰 A table.ddl script designed for an Oracle database, and supporting an
optimized cascade delete feature.
For convenience, these files, with a few minor changes, are provided in the
additional materials for this paper, in the example/one2many/Original folder. This
is the starting point for the following migration steps:
1. Verify that the distributed source runs on WebLogic.
Chapter 5. Migration examples
127
2. Repackage the source and import it into WebSphere Studio Application
Developer.
3. Migrate CMP 2.0 and JNDI deployment descriptors.
4. Migrate the database to DB2.
5. Generate deployment code.
6. Migrate the application client.
7. Test and debug under WebSphere Studio Application Developer test server.
8. Export the final EAR file.
5.2.1 Verify baseline
The Oracle-dependent cascade delete feature of this example was our first
migration issue. Since we did not have a Oracle database available, we could not
verify the original baseline. We chose to convert the database to the PointBase
database provided with the WebLogic V7 distribution. To this end, we made the
following two modifications to the weblogic-cmp-rdbms-jar.xml file:
򐂰 Replace the original DataSource named examples-datasource-oracleXAPool
with examples-datasource-demo.
򐂰 Remove the <db-cascade-delete/> option.
This effectively replaced Oracle with PointBase and turned off the proprietary
WebLogic <db-cascade-delete/> feature. The ejb-jar.xml file still specifies the
standard EJB 2.0 <cascade-delete\> option, so we retained the cascade delete
feature. We just changed the database and the optimization of the
<cascade-delete\> feature.
We followed the instructions provided by WebLogic to build, deploy, and run the
slightly modified one2many example. See package-summary.html in the
WebLogic folder src/examples/ejb20/cascadeDelete/one2many for these
instructions, but ignore the database setup step. Figure 5-2 on page 129 shows
an excerpt of the resulting server console. The complete output is described in
the package-summary.html file. The only difference is that our modified
one2many example performed the standard EJB 2.0 cascade delete operation
using the PointBase database instead of Oracle.
128
Migrating WebLogic Applications to WebSphere V5
Print Customers:
Customer: customer0 has
account2 with
account1 with
account0 with
Customer: customer1 has
Customer: customer2 has
Customer: customer3 has
account4 with
account3 with
Customer: customer4 has
accounts:
balance 2000.0
balance 1000.0
balance 0.0
accounts:
accounts:
accounts:
balance 4000.0
balance 3000.0
accounts:
• • •
Cascade Delete:
Removing customer 0 and cascade delete its accounts
customer0 removed
Print Customers:
Customer: customer0 not
Customer: customer1 has
Customer: customer2 has
Customer: customer3 has
account4 with
account3 with
Customer: customer4 has
Print Accounts:
Account: account0 not
Account: account1 not
Account: account2 not
Account: account3 has
customer3
Account: account4 has
customer3
found
accounts:
accounts:
accounts:
balance 4000.0
balance 3000.0
accounts:
found
found
found
customers:
customers:
Figure 5-2 Excerpt of server console for one2many example
5.2.2 Stage source code
We captured the structure of the one2many example in the staging folder shown
in Figure 5-3 on page 130. Following the guidance in 4.2.3, “Stage source code”
on page 101, we manually copied the original files from
examples/ejb20/cascadeDelete/one2many into two distinct modules.
Chapter 5. Migration examples
129
Figure 5-3 Separate client from application source in the staging folder
򐂰 One2manyApp consists of the application.xml and ejb-jar.xml files, and all of
the Java source files except for Client.java.
򐂰 One2manyClient consists of just the Client.java file.
We omitted the original Javadoc HTML files from the staging folder because they
can be easily regenerated from the Java source — see “Debug Javadoc tags” on
page 162. We also omitted the Ant build.xml and table.ddl files from the staging
130
Migrating WebLogic Applications to WebSphere V5
folder. We wrote a small command script that uses the jar command to package
the staging directories into two archive files:
򐂰 One2manyApp.ear, containing the One2manyApp folder and a Manifest.mf
file.
򐂰 One2manyClient.jar, containing the One2manyClient folder and a Manifest.mf
file.
The Bank and BankHome interfaces are shared between the EJB and client
modules. The WebLogic ejbc command puts copies of these interfaces into a
separate JAR file. As a sanity check, we use this archive to verify that we had
identified all client dependencies.
1. We constructed a One2manyWLClient.jar containing Client.class, Bank.class,
and BankHome.class.
2. Using only the One2manyWLClient.jar, the weblogic.jar, and the Java JDK,
we successfully executed the application client on the WebLogic server.
This verified that there are no additional dependencies between the client and
EJB modules. Although obvious in this simple case, large applications may have
hidden dependencies that you need to identify.
All of the artifacts discussed in this section are available in the additional
materials for this paper:
򐂰 Original and staging folders.
򐂰 The migrate_src and runWLClient command files.
򐂰 One2manyWLClient.jar, One2manyApp.ear, and One2manyClient.jar
archives.
5.2.3 Import source code
At this point, we have two archives ready for importing into WebSphere Studio
Application Developer:
򐂰 The One2manyApp.ear.
This archive contains the Java source and standard deployment descriptors
for the J2EE application. It will be imported first.
򐂰 The One2manyClient.jar.
This archive contains the Java source for the application client. It will be
imported in 5.2.5, “Migrate application client” on page 150, after the J2EE
application is ready for testing.
In accordance with the instructions in 3.3.2, “Import and export” on page 27, we
imported the One2manyApp.ear file as an EAR file type. We accepted all default
Chapter 5. Migration examples
131
settings and named the new project One2manyApp. We got the error shown in
Figure 5-4. Double-click the error message to bring up the application.xml file in
the Source tab of the Application Deployment Descriptor editor. The problem is
that our One2manyApp.ear archive is not well-formed.
Fix JAR names in application.xml file
In the process of migrating and restructuring the source code, we ignored the
original archive names and created brand new ones. We forgot to tell the
application.xml file about the new EJB archive name. This is a fatal error to
WebSphere Studio Application Developer because it needs this name to find the
JAR file for the EJB project. As you can see in the figure, no EJB project was
created. It is easiest to go back to the staging folder to correct the application.xml
file there.
1. Delete the erroneous One2manyApp project from the WebSphere Studio
Application Developer workspace.
2. In the staging folder, correct the <module> stanza of application.xml to
One2manyEjb.jar.
3. Recreate the One2many.ear archive by rerunning the migrate_src command.
4. Import One2many.ear into WebSphere Studio Application Developer a
second time.
Figure 5-4 Incorrect file name caused ill-formed One2manyApp.ear archive
132
Migrating WebLogic Applications to WebSphere V5
The second try produces the expected project structure, as shown in Figure 5-5
on page 134.
򐂰 A J2EE application project named One2manyApp.
򐂰 An EJB project named One2manyEjb.
Before proceeding, we also addressed the problem discussed in “Missing ID in
application.xml file — beta defect” on page 29.
Fix invalid names in <ejb-name> descriptor
There are still eight warnings in the task list. First, we addressed the ejb-jar.xml
errors. Again, these errors are best seen using the Source tab. According to the
EJB 2.0 specification, an ejb-name must be a valid Java identifier. The EJBs in
the WebLogic example are named CustomerEJB-OneToMany and
AccountEJB-OneToMany — the “-” character is invalid. Since these are just
warning messages, we first tried to ignore them. Indeed, AAT did not complain.
However, this caused secondary errors when the invalid “-” characters turned up
in the database schema. As with any standard, the best practice is to follow the
standard.
Chapter 5. Migration examples
133
Figure 5-5 EJB names must be valid Java identifiers
There are two alternatives as to where to fix the invalid ejb-name identifiers:
1. Fix them in the staging folder, recreate import archives, and re-import into
WebSphere Studio Application Developer.
2. Fix them within WebSphere Studio Application Developer.
Since the project structure looked fine, we chose to start making corrections in
the WebSphere Studio Application Developer workspace.
The obvious approach was to replace the two flagged symbols that appear on
lines 19 and 44. However, this is not the best approach. In general, whenever
you change the declaration of an identifier, you need to make sure you find and
change all of its references. WebSphere Studio Application Developer may not
be able to flag all of these references. Indeed, each of the identifiers in this case
appear not just once, but three times. Since some uses of ejb-name are not
134
Migrating WebLogic Applications to WebSphere V5
resolved until runtime, the best practice is to explicitly search for all occurrences
right now. Do not wait for the test server to complain.
1. Select the search text.
2. Select Search -> Search.
3. Click the Search button — you may need to adjust the file name patterns first.
Figure 5-6 on page 136 shows the search results for CustomerEJB-OneToMany.
As you can see, there are actually three instances for this invalid identifier. We
corrected a total of six invalid ejb-name identifiers in the ejb-jar.xml file, using
Find/Replace. See 3.3.9, “Finding Find/Replace” on page 52, for details.
򐂰 CustomerEJB-OneToMany was changed to CustomerEJB_OneToMany.
򐂰 AccountEJB-OneToMany was changed to AccountEJB_OneToMany.
Chapter 5. Migration examples
135
Figure 5-6 Search for all occurrences of invalid identifier
The final six warnings are about invalid use of RemoteException. EJB 2.0
outlaws this exception in EJBs. See Figure 5-7 on page 137. We deleted the
invalid throws clauses to get a clean compilation.
136
Migrating WebLogic Applications to WebSphere V5
Figure 5-7 RemoteException invalid in EJBs
Browse your application
By way of a review, at this point we have accomplished the following:
1. Imported the One2manyApp.ear and constructed its two WebSphere Studio
Application Developer projects.
2. Corrected invalid ejb-name identifiers found in the original ejb-jar.xml
deployment descriptors.
3. Compiled the EJB code.
The Resource Navigator view in Figure 5-8 on page 138 shows the compiled
class files along with the imported Java files. Notice that the class and Java
files are in the same folder. The separate bin folder of WebSphere Studio
Application Developer V4 has been replaced with this more conventional
folder structure.
Chapter 5. Migration examples
137
Figure 5-8 Initial compilation of one2many EJBs
138
Migrating WebLogic Applications to WebSphere V5
It is clear from Figure 5-8 on page 138 that no deployment code has been
generated yet. There are no implementations of the remote and home interfaces,
and there are no concrete extensions of the abstract AccountBean and
CustomerBean entities. These will be generated in 5.2.4, “EJB 2.0 deployment”
on page 142.
This is a good time to pause and use some of the WebSphere Studio Application
Developer features to browse your application. For this simple example, this
helps verify our understanding of its structure. For more complex applications,
this is a good opportunity to learn more about the application’s structure. When
we started this example, we had to glean this information directly from the Java
source code, deployment descriptors, and Ant build script. We used that
information to manually construct Figure 5-1 on page 127. Now that the example
has been imported into WebSphere Studio Application Developer, we have more
powerful tools available for browsing and viewing. We show just two examples
here.
WebSphere Studio Application Developer Relationship editor
The Customer-Account relationship is defined in the ejb-jar.xml deployment
descriptor file. Figure 5-9 on page 140 presents this information using a
UML-style editor. You get there as follows:
1. Select the ejb-jar.xml file.
2. Right-click and select Open With -> Deployment Descriptor.
3. Scroll down to the Relationships 2.0 heading.
4. Click the Edit button to bring up the Edit Relationship pane.
5. Click Next to see the relationship details.
From this editor it is easy to verify the following information:
򐂰 Customer-Account is an EJB 2.0 relationship with the two roles,
Customer-Has-Accounts and Account-Has-Container.
򐂰 Customer-Account is a bi-directional relationship.
򐂰 Customer-Has-Accounts:
– Is one-to-many with AccountEJB_OneToMany.
– Uses the field named accounts to refer to its collection of
AccountEJB_OneToMany instances.
򐂰 Account-Has-Customer:
– Is many-to-one with CustomerEJB_OneToMany.
– Uses the field named customer to refer to its CustomerEJB_OneToMany
instance.
Chapter 5. Migration examples
139
– Cascade delete is specified, meaning all related AccountEJB_OneToMany
instances are deleted when the related CustomerEJB_OneToMany
instance is deleted.
This editor can be used to view, create, or modify EJB 2.0 relationships.
Figure 5-9 View and edit customer account in relationship editor
EJB fields and interfaces
Using the J2EE Hierarchy view, you can easily browse the interfaces and fields
of your EJBs. Figure 5-10 on page 141 provides the following information for our
One2many example:
򐂰
򐂰
򐂰
򐂰
򐂰
BankBean has only remote interfaces.
AccountBean and CustomerBean have only local interfaces.
The keys for account and customer are accountId and name, respectively.
Names and types of other fields.
Names and target beans of relationships.
Clicking some of these entries takes you to an appropriate editor:
򐂰 Click a field to get to the Deployment Descriptor editor for that bean.
140
Migrating WebLogic Applications to WebSphere V5
򐂰 Click an interface to edit the Java code.
򐂰 Clicking a relationship role does nothing.
Figure 5-10 Browse EJB fields and interfaces
Chapter 5. Migration examples
141
5.2.4 EJB 2.0 deployment
It is tempting at this point to just try to generate deployment code, run on the test
server, and then fix problems indicated in the server console. Although this
approach may have been effective with WebSphere Studio Application
Developer V4, it causes too much confusion when using CMP 2.0 features. The
server console will contain many perplexing and unhelpful exceptions:
򐂰 Missing JNDI names for unfamiliar connection factories.
򐂰 Exceptions for missing deployment code — names starting with EJS.
򐂰 Exceptions for missing CMP-support code — names starting with EJSCMP.
We performed the following steps to deploy the one2many J2EE Enterprise
Application. Except as indicated, these steps can be performed in any order. Full
details are covered in later sections.
1. Establish connection factory for CMP 2.0 support.
This is an essential step for CMP 2.0 support. If this is not done before
running on the server, the CMP 2.0 connection factory will not be configured,
and the container will not start properly.
Here are the preferred steps, but the order does not actually matter.
a. Create the DataSource for your database.
You do not have to create the actual database, just the DataSource. You
must indicate that this DataSource is used for CMP code generation.
b. Assign the CMP 2.0 connection factory JNDI name.
The JNDI name of the DataSource is used to construct a second JNDI
name that identifies a connection factory for CMP 2.0 support. The JNDI
name for the CMP connection factory has the form
eis/{databaseJNDIname}_CMP.
2. Generate RDB mapping.
This step should be done before generating the deployment code. Otherwise,
the code generated will use the default nullid schema, which is probably not
what you want.
3. Generate deployment code.
In addition to the standard stubs, ties, and WebSphere server support, this
step also creates the following:
– Concrete classes for your abstract CMP 2.0 entity beans.
– Classes for relationships.
– Support for the RBD mapping fields.
142
Migrating WebLogic Applications to WebSphere V5
4. Bind JNDI names to EJBs.
This step can be performed anytime before running on the server. Failure to
perform this step results in JNDI errors. Startup will give warnings for EJBs
without JNDI names. Missing or incorrect EJB references result in JNDI
lookup failures.
Establish and bind CMP 2.0 connection factory
Follow the instructions in 3.4.1, “CMP 2.0 deployment” on page 57. In this
particular case:
򐂰 We used the following options when defining the database DataSource:
–
–
–
–
–
DB2 JDBC driver.
JNDI name of jdbc/Sample.
DatabaseName of Sample.
User db2amdin.
Password db2admin.
򐂰 As a reminder, since the database JNDI name is jdbc/Sample, the JNDI name
for the CMP connection factory must be eis/jdbc/Sample_CMP.
򐂰 We chose to bind the CMP connection factory at the JAR level.
This information is captured in the ibm-ejb-jar-bnd.xmi deployment descriptor. It
can be viewed through the J2EE Navigator as shown in Figure 5-11.
Figure 5-11 CMP connection factory in ibm-ejb-jar-bnd.xmi deployment descriptor file
Chapter 5. Migration examples
143
Generate top-down RDB mapping
For simplicity, we initially chose to use a top-down RDB mapping. If time permits,
we plan to redeploy later, using a meet-in-the-middle mapping. This strategy
decouples the application migration from the database migration.
We generated a top-down RDB mapping according to 3.4.6, “RDB mapping with
CMR” on page 68. See Figure 3-5 on page 30 for the results. Notice that this
mapping uses foreign key fields to represent the CMR relationship.
This operation results in the creation of a new folder in the One2manyEjb project.
Figure 5-12 on page 145 shows the new folder backends/DB2UDBNT_V72_1. It
contains the newly generated deployment descriptor and database schema files.
This information can be viewed through the Resources or J2EE perspectives.
You can create multiple back-end folders, each using a different data mapping.
144
Migrating WebLogic Applications to WebSphere V5
Figure 5-12 RDB mapping generates back-end folder
Generate deployment code
Now we are ready to generate the deployment code. This is normally just done
automatically as needed, but you can also request it explicitly.
1. Select the One2manyEjb project.
2. Right-click and select Generate -> Deploy and RMIC code.
3. Select Select all and click Finish.
Chapter 5. Migration examples
145
If you start the application on the test server now, the only startup warnings
would concern missing JNDI names for the EJBs. We take care of that problem
in the next section. However, before proceeding, you may wish to browse
through some of the generated code. The view shown in Figure 5-13 on
page 147 is a good place to start.
򐂰 The Concrete classes extend the corresponding abstract CMP 2.0 entity
beans — AccountBean and CustomerBean in this example.
򐂰 The examples.ejb20.cascadeDelete.one2many.websphere_deploy packages
contain classes that implement the relationships.
򐂰 Classes with names starting with an underscore implement stubs and ties.
򐂰 The EJS classes are implementation classes for various container-managed
objects.
For a before and after comparison of code generation, compare the before case
in Figure 5-8 on page 138 with the after case in Figure 5-13 on page 147.
146
Migrating WebLogic Applications to WebSphere V5
Figure 5-13 Generated deployment code
Bind JNDI names to EJBs and EJB references
See 4.3.2, “EJB references” on page 107, for a review of the standards governing
EJB JNDI names. Our strategy for the first cycle through this migration example
was to make only the minimum changes required to get it running. In effect, we
Chapter 5. Migration examples
147
were just looking for critical defects. There are obvious changes that should be
made to JNDI names that we consciously ignored the first time through.
JNDI names for EJBs
Since global JNDI names are found in vendor-specific deployment descriptors,
we lost the original names when we migrated the source code. Examining the
weblogic-ejb-jar.xml file for jndi-name deployment descriptors, we find the
following original names:
򐂰 one2many.BankHome
򐂰 one2many.AccountHome
򐂰 one2many.CustomerHome
There are several reasons why you might want to change these names:
1. JNDI names are organized around contexts. The ‘/’ is the typical delimiter in
WebSphere. An application name is a plausible JNDI context. This suggests
using the following names:
– one2many/BankHome
– one2many/AccountHome
– one2many/CustomerHome
2. As noted in the JNDI chapter of Migrating WebLogic Applications to
WebSphere Advanced Edition V4, SG24-6179, best practice encourages
using a naming strategy that avoids name overloading. This helps avoid
misinterpretations, and suggests further improvements.
– one2many/bankHome
– one2many/accountHome
– one2many/customerHome
For now, however, we stick with the original JNDI names. We follow the
instructions in 3.4.2, “Bind global JNDI name to EJB home” on page 59, to deploy
with the original global JNDI names shown in Table 5-1.
Table 5-1 Global JNDI names for one2many example
EJB home
global JNDI name
BankHome
one2many.BankHome
AccountHome
one2many.AccountHome
CustomerHome
one2many.CustomerHome
JNDI names for EJB references
The ejb-ref deployment descriptors are standard, so we should find them in the
original, imported WebLogic ejb-jar.xml file. All we have to do is follow the
148
Migrating WebLogic Applications to WebSphere V5
instructions in 3.4.3, “Bind local JNDI name to EJB reference” on page 60, to
bind appropriate global JNDI names to the existing EJB reference.
From our knowledge of the application, we expect to find two EJB references in
the BankEJB — one for each of the local entity beans it uses. The WebSphere
Studio Application Developer Deployment Descriptor editor displays the existing
EJB references.
1. Select ejb-jar.xml.
2. Right-click and select Open With -> Deployment Descriptor.
3. Click the References tab.
4. Expand the BankEJB to see its EJB references.
Surprise — there are no EJB references anywhere in the example. The BankEJB
in Figure 5-14 on page 150 should have two EJB references, similar to what is
seen in Figure 5-20 on page 161. This appears to be a common violation of the
EJB 2.0 standard for WebLogic applications. See 4.3.2, “EJB references” on
page 107, regarding this migration issue.
For now, we ignore this problem to see how it manifests itself. This error
highlights one of the primary reasons for requiring EJB references. They
document structural dependencies. In a large application, these important
dependences are often not obvious, so it is important to make them explicit to the
application deployer.
Chapter 5. Migration examples
149
Figure 5-14 Deployment descriptors missing for the two EJB references for BankEJB
5.2.5 Migrate application client
For a discussion of alternative models for J2EE application clients, see 4.5.1,
“Lightweight application client” on page 117.
In the one2many example, the small Client.java program is the heart of a J2EE
application client. It executes in its own JVM and communicates with the J2EE
server through the remote interfaces of the BankEJB. J2EE application clients
are part of the J2EE specification, but historically they have not been well
supported within J2EE products. One of our goals for this example is to
investigate migration issues of lightweight J2EE application clients.
The input to this migration step is the Client.java source, which is contained in
the Client.jar file created in 5.2.2, “Stage source code” on page 129. The
expected output from this step is a JAR file containing the classes needed to run
the client, using the WebSphere server.
1. Import the Client.java code into a WebSphere Studio Application Developer
as a J2EE application client project.
2. Export the resulting application client JAR, ready for execution in its own JVM
using the WebSphere Studio Application Developer test server.
150
Migrating WebLogic Applications to WebSphere V5
Create J2EE application client
WebSphere Studio Application Developer supports the importation of
well-formed J2EE application client JARs. We tried to follow the instructions in
“Import application client” on page 35, to import Client.jar as a J2EE application
client. Unfortunately, this JAR is not well formed. This is because it does not
contain an application-client.xml file. We had to make the following modifications:
1. Add an application.xml file as described in “Missing application-client.xml file”
on page 39.
2. Provide the main class in the meta-inf/Manifest.mf file as described in
“Missing main class” on page 40.
We named the new application client project One2manyClient. It is included as
part of the existing One2manyApp project.
Export J2EE application client
We followed the instructions in “Export application client” on page 41, to export
the One2manyClient project into a One2manyClient.jar file.
Of course we do not expect the application to run properly just yet, but this is the
starting point for the testing cycle. Example 5-1 shows the initial version of a
command, runWASClient.cmd, for testing the application client. The client.jar is
part of the WebSphere distribution. Its size is about a half megabyte, and
provides the necessary environment for application clients.
Example 5-1 Initial runWASClient command for testing one2many application client
@set WAS_BASE=c:\Program Files\IBM\Application Developer\eclipse\base_v5
@set JAVA_HOME=%WAS_BASE%\java
@set CLASSPATH=%WAS_BASE%\lib\client.jar
@set CLASSPATH=%CLASSPATH%;One2manyClient.jar
"%JAVA_HOME%\bin\java" examples.ejb20.cascadeDelete.one2many.Client
5.2.6 Test and debug cycle
Summarizing the current status of our migration, we have done the following:
1. Repackaged the source into an EJB module and a lightweight application
client module.
2. Imported the modules into WebSphere Studio Application Developer projects.
3. Compiled the code.
4. Generated deployment code, including the necessary CMP 2.0 support.
– A side effect of this step was to set up the test server as described in
3.5.1, “Test server setup” on page 71.
Chapter 5. Migration examples
151
5. Done just enough JNDI deployment to get the server to start without errors.
In this section we document the test and debugging cycle. We discovered that
the following tasks were needed to complete the migration effort and get this
example executing properly:
1.
2.
3.
4.
5.
6.
7.
Replace hard-coded WebLogic InitialContext code with portable code.
Add interfaces to the application client.
Fix PortableRemoteObject narrow error.
Add interface stubs to the application client.
Upgrade code to use standard EJB references.
Create the DB2 database.
Debug Javadoc comments.
A checkpoint of the input to each of these tasks is captured in the additional
materials in appropriately named EAR files. For information on the construction
and use of these checkpoints, see 3.3.3, “Project checkpoints” on page 29.
As a rule, we made small incremental changes and kept code changes to a
minimum. The following subsections describe each test and debug cycle. Each
test is executed with the application running on the WebSphere Studio
Application Developer test server, with the application client being executed by
the runWASCient command.
Remove hard-coded JNDI InitialContext properties
Example 5-2 shows the result of our first test run.
Example 5-2 InitialContext hard-coded to WebLogic JNDI properties
We were unable to get a connection to the WebLogic server at
t3://localhost:7001
Please make sure that the server is running.
Unable to look up the beans home: Cannot instantiate class:
weblogic.jndi.WLInitialContextFactory
As this example shows, it is not unusual to find the following hard-coded into a
WebLogic application:
򐂰 Use of the proprietary t3 protocol.
򐂰 Explicit URL for JNDI server.
򐂰 JNDI initial context factory for WebLogic.
We removed the explicit JNDI initial context properties from the source code.
Figure 5-15 on page 153 shows the before and after code for these changes.
152
Migrating WebLogic Applications to WebSphere V5
Figure 5-15 Remove hard-coded JNDI properties [before and after]
For alternatives on how to provide InitialContext factory information in a more
portable way, see 4.5.3, “Portable JNDI InitialContext” on page 120. We chose
the jndi.properties file alternative.
1. Follow the instructions in “New simple file” on page 45 to create a
jndi.properties file in the One2manyClient/appClientModule folder.
2. Enter the parameters needed for the WebSphere Studio Application
Developer JNDI server as shown in Figure 5-16 on page 154.
– The WebSphere initial context factory is
com.ibm.websphere.naming.WsnInitialContextFactory.
– The URL for the WebSphere Studio Application Developer test server is
iiop://localhost:2809. This is displayed in the test server console and is
also available on the JNDI Properties page of the Universal Test Client.
The ORB bootstrap port can be changed via the server ports tab.
Chapter 5. Migration examples
153
Figure 5-16 Add jndi.properties file to appClientModule
Unfortunately, as you can see from the result of our next test, shown in
Example 5-3, the jndi.properties file does not completely solve the JNDI initial
context problem.
Example 5-3 WebSphere uses the optional jndiprovider properties too
The property com.ibm.ws.naming.wsn.factory.initial is not set.
The most likely cause is that the jar which contains the file
com/ibm/websphere/naming/jndiprovider.properties
cannot be found by the class loader.
The WebSphere initial context also makes use of additional parameters. They
are provided by the jndiprovider.properties file in the com.ibm.websphere.naming
package. The jndiprovider.properties file is an optional part of the JNDI
specification. We quickly solved this problem by lifting the jndiprovider.properties
file from the namingclient.jar distributed with WebSphere. We added this file and
its folder structure to the appClientModule using the drag-and-drop method
described in “Drag and drop (cut and paste)” on page 47. The resulting
One2manyClient project is shown in Figure 3-19 on page 48.
Since both of these properties files are contained in the appClientModule of the
One2manyClient project, they are exported as part of the application client JAR
file. This makes them available in the classpath. Our next test verifies that with
these changes, we successful communicate with the WebSphere JNDI server.
154
Migrating WebLogic Applications to WebSphere V5
Add interfaces to application client classpath
The next test result, shown in Example 5-4, verifies something we already knew
— the application client must include the remote BankHome interface. It will also
need the remote Bank interface.
Example 5-4 EJB remote interfaces are needed by application client
Exception in thread "P=954297:O=0:CT" java.lang.NoClassDefFoundError:
examples/ejb20/cascadeDelete/one2many/BankHome
This exception occurred while executing the following One2manyClient statement:
Object home = (BankHome) ctx.lookup("one2many.BankHome");
For a discussion of this issue, see 4.5.4, “EJB interfaces and stubs for lightweight
clients” on page 121. We chose to provide the missing interfaces by adding a
new JAR file to the class path. Since this will be a one-time operation, we settled
for constructing this JAR manually. Here are the steps — see Figure 5-17 on
page 156:
1. Click File -> Export.
2. Select JAR file and click Next.
3. Expand the One2many/ejbModule folder.
4. Select the examples.ejb20.cascadeDelete.one2many package.
5. Check Bank and BankHome — make sure no other classes are checked.
6. Name the JAR One2manyClient_serverclasses.jar.
7. Click Finish.
We added this new JAR to the classpath in the runWASClient command and
proceeded to the next test cycle.
Chapter 5. Migration examples
155
Figure 5-17 Manually construct JAR containing remote interfaces
Use PortableRemoteObject narrow
Our next test cycle failed at the same Java statement, but for a different reason.
Example 5-5 Initial context lookup needs to use PortableRemoteObject narrow
java.lang.ClassCastException: com.ibm.org.omg.CORBA._ObjectStub
156
Migrating WebLogic Applications to WebSphere V5
This exception occurred while executing the following One2manyClient statement:
Object home = (BankHome) ctx.lookup("one2many.BankHome");
According to the EJB 2.0 standard, the above cast should be rewritten to the
following:
Example 5-6 Rewritten file
(BankHome) PortableRemoteObject.narrow(
ctx.lookup("one2many.BankHome"),
BankHome.class);
For background information on this issue, see 4.3.1, “PortableRemoteObject
narrow” on page 104. Also see 3.3.8, “Using type hierarchy browser” on page 48,
on how we used the type hierarchies feature of WebSphere Studio Application
Developer to help better understand this particular problem.
The observed behavior depends on the particular ORB. We used two different
releases of WebSphere Studio Application Developer V5, each with a different
ORB. One release behaved as described here, returning the type _ObjectStub,
and required the PortableRemoteObject narrow. The other release returned the
type _BankHome_Stub, which does not require the PortableRemoteObject
narrow function. This demonstrates that an application may have this error, but
not manifest it immediately. We recommend manually reviewing all uses of
PortableRemoteObject for correct usage. Also see “Problem: Unnecessary use
of PortableRemoteObject narrow” on page 106.
We made the following additional observations about the Java statement in
Example 5-5 on page 156:
1. The (BankHome) cast is superfluous because home is of type Object.
2. The next statement in the program uses the correct casting protocol:
return (BankHome) PortableRemoteObject.narrow(home, BankHome.class);
So a better solution to this particular PortableRemoteObject narrow error is to
simply remove the (BankHome) cast. It was probably unintentionally left over
when this code was upgraded to use the PortableRemoteObject narrow. If it was
then tested using the t3 protocol, the error would not have been detected.
We removed the explicit (BankHome) cast shown in Example 5-5 on page 156,
and moved on to the next test cycle.
Chapter 5. Migration examples
157
Add interface stubs to application client classpath
The next test result, summarized in Example 5-7 on page 158, is a lot like the
previous result, but now we have the critical information that the
_BankHome_Stub class cannot be found. This is, of course, the stub for the
BankHome remote interface. The WebLogic t3 protocol dynamically provides
stubs for remote interfaces. WebSphere does not.
Example 5-7 Remote interface stubs also needed by application client
java.lang.ClassCastException: Unable to load class:
examples.ejb20.cascadeDelete.one2many._BankHome_Stub
This exception occurred while executing the following One2manyClient statement:
return (BankHome) PortableRemoteObject.narrow(home, BankHome.class);
We fixed this problem by adding _Bank_Stub and _BankHome_Stub to the list of
files exported in “Add interfaces to application client classpath” on page 155. We
then had to create the One2manyClient_serverclasses.jar a second time — sorry
for breaking the earlier promise to just create this JAR once.
Upgrade to use standard EJB references
The next test cycle is the first to actually execute some of the application’s server
code. Example 5-8 shows a summary of the result. There is a problem with the
JNDI lookup of the AccountHome from the BankBean — the BankBean cannot
find the local AccountHome interface. The same problem will occur for the
CustomerHome lookup.
Example 5-8 Local interface stub not found
Creating bank ...
Bank successfully created
Create Accounts and customers:
There was an exception while creating and using the Accounts.
javax.naming.NameNotFoundException: one2many.AccountHome
This exception occurred while executing the following BankBean statement:
accountHome = (AccountHome) ic.lookup("one2many.AccountHome");
Consider the following possible reasons for this problem:
1. There is no PortableRemoteObject narrow — this is not the problem.
a. The error obviously occurs earlier in the JNDI lookup.
b. Since AccountHome is a local interface, the PortableRemoteObject
narrow is not needed — the normal Java cast is fine.
158
Migrating WebLogic Applications to WebSphere V5
2. The JNDI name one2many.AccountHome has not been bound in the
deployment descriptor of AccountHome. We verified that this was not the
problem two different ways:
– We examined the deployment descriptor.
– We used the JNDI Explorer — notice the [Local EJB beans] entries in
Figure 5-18 on page 160.
3. The JNDI lookup does not use the mandated java:comp/env local JNDI
context, and associated EJB reference deployment descriptor.
This is the cause of the problem. It is clear from Figure 5-18 on page 160 that
the JNDI entries for local interfaces are kept in a special local context and are
therefore not accessible by global JNDI lookups.
We made the following changes to conform to the J2EE standard.
1. We modified the BankBean code, as indicated in Figure 5-19 on page 161, to
use local JNDI names:
– java:comp/env/ejb/accountHome for AccountHome
– java:comp/env/ejb/customerHome for CustomerHome
2. We followed the steps in 3.4.3, “Bind local JNDI name to EJB reference” on
page 60, to bind the local JNDI names to the existing global JNDI names —
see Figure 5-20 on page 161 for the results.
– Retain the original global JNDI names.
– Make sure to change the EJB reference names to those use in the Java
code:
• ejb/accountHome replaces ejb/AccountEJB_OneToMany
• ejb/customerHome replaces ejb/CustomerEJB_OneToMany
These are the first changes to the application server code. The application client
code remains unchanged. We restarted the test server before running the next
test cycle.
Chapter 5. Migration examples
159
Figure 5-18 Use JNDI Explorer to verify local JNDI names
160
Migrating WebLogic Applications to WebSphere V5
Figure 5-19 Replace global JNDI references with local java:comp/env names [before and after]
Figure 5-20 Bind EJB references to original global JNDI names
Chapter 5. Migration examples
161
Create DB2 database
This is the last test cycle for the one2many application. Example 5-9 summarizes
the result. Although we created the DataSource for our database in 5.2.4, “EJB
2.0 deployment” on page 142, we never created the database tables themselves.
This is the first time we have actually tried to access the database, so of course
we get the indicated error.
Example 5-9 Database not found
Exception: COM.ibm.db2.jdbc.DB2Exception: [IBM][CLI Driver][DB2/NT] SQL0204N
"DB2ADMIN.ACCOUNTEJB_ONETOMANY" is an undefined name. SQLSTATE=42704
This exception occurred while executing the following BankBean statement:
Account ac = (Account) PortableRemoteObject.narrow(
accountHome.create(id, balance, accountType),
Account.class);
We solved this problem by creating the database using the Table.ddl file in folder
ejbModule/meta-inf/backends/DB2UDBNT_V72_1. This file was generated for
us in “Generate top-down RDB mapping” on page 144. We modified the syntax
slightly so it could be used from a DB2 command window, as follows:
db2 connect to SAMPLE user db2admin using db2admin
db2 -f table-modified.ddl
db2 terminate
With this update, our migrated one2many example runs to completion and
generates the identical output, summarized in Figure 5-2 on page 129.
Debug Javadoc tags
Remember that we ignored the original Javadoc files back in 5.2.2, “Stage
source code” on page 129. As a final step, we regenerated the Javadoc HTML
files by following the instructions in 3.3.6, “Javadoc export” on page 43. To our
surprise, the Javadoc console reported five errors in the original Javadoc tags.
Note that the code is correct, just the Javadoc tags are incorrect. They all appear
to be the result of unedited cut-and-pasted text taken from other examples.
򐂰 Three different local home methods in AccountHome and CustomerHome
document that they throw RemoteException. Local methods do not throw a
RemoteException.
򐂰 Two different CustomerBean methods document that they throw a
RemoteException. Beans should not throw RemoteExceptions.
We did not correct these errors.
162
Migrating WebLogic Applications to WebSphere V5
5.2.7 Meet-in-the-middle RDB mapping
In “Generate top-down RDB mapping” on page 144, we made the decision to
temporarily ignore the original schema of the target database. Instead, we used
the schema from the top-down RDB mapping. Now that the application has been
migrated to the new server, it is time to do the real database migration. This
typically requires a meet-in-the-middle RDB data mapping.
Migrating WebLogic Applications to WebSphere Advanced Edition V4,
SG24-6179 describes the meet-in-the-middle RDB mapping process. Since the
basic steps are unchanged, we just outline the differences here.
1. In the J2EE Navigator perspective, select the One2manyEjb project.
2. Right-click and select Generate -> EJB to RDB mapping.
This starts the RDB mapping wizard shown in Figure 5-21 on page 164. As
you can see, we already have a back-end map for the top-down mapping. We
are about to create a second back-end map, this one for a meet-in-the-middle
mapping.
3. Select Create a new backend folder and click Next.
4. Select the Meet In The Middle option and click Next.
5. Connect to your database to select the relevant table definitions.
This process is described in Migrating WebLogic Applications to WebSphere
Advanced Edition V4, SG24-6179.
– The database must exist at this point.
– Choose to do a manual data mapping.
– Our SAMPLE2 database uses the original Table.ddl distributed by
WebLogic.
– To see the differences between this schema and the top-down schema,
compare the tables in Figure 3-35 on page 70 with those in Figure 5-23 on
page 167.
Figure 5-22 on page 165 shows the resulting second back-end folder. You can
use this back-end map to deploy your CMP 2.0 beans by using the
corresponding CMP connection factory JNDI name. But first, we must complete
its meet-in-the-middle mapping. The errors in Figure 5-22 on page 165 indicate
that we have not yet done the mapping.
Chapter 5. Migration examples
163
Figure 5-21 Create second back-end map for meet-in-the-middle RDB mapping
164
Migrating WebLogic Applications to WebSphere V5
Figure 5-22 Second back-end map for SAMPLE2 database
Chapter 5. Migration examples
165
Map CMP 2.0 fields and relations
1. Select the appropriate Map.mapxmi file.
2. Right-click and select Open With -> Mapping Editor.
3. Map the EJB fields to their table fields as described in Migrating WebLogic
Applications to WebSphere Advanced Edition V4, SG24-6179.
Figure 5-23 on page 167 shows the results of this process. Notice that we still
have a couple of error messages:
– The CMR has not been mapped yet, so the accounts and customers roles
have errors.
– The type of balance is different in the new database, so we will have to
add a type converter.
4. Select customer and CUST_NAME entries as shown in Figure 5-23 on
page 167.
5. Right-click and select Create Mapping.
If you save the results right now, you will see that the accounts and customers
roles have been mapped properly, and their error messages are gone.
The type converter is next:
1. Select the Properties tab as shown in Figure 5-24 on page 168.
2. Select the EJB balance field in the Overview window.
3. Use the selector to the right of the Transformation property to assign an
appropriate converter.
– You may have to first click this entry to make the selector appear.
– When you save, the conversion complaint about balance will disappear.
4. Save your changes.
166
Migrating WebLogic Applications to WebSphere V5
Figure 5-23 Map CMP 2.0 relationship
Chapter 5. Migration examples
167
Figure 5-24 Define a type converter for an RDB mapping
5.2.8 Summary
We demonstrated the use of the following WebSphere Studio Application
Developer tools and migration techniques:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
CMP 2.0 Deployment Descriptor editors.
CMP 2.0 RDB mapping.
WebSphere CMP 2.0 deployment.
Source staging.
Lightweight application client.
Decoupling application and database migration.
This example verified that the following new EJB 2.0 features work as advertised
in both WebLogic and WebSphere:
򐂰
򐂰
򐂰
򐂰
168
Local EJB interfaces.
CMP 2.0.
CMR.
The cascade-delete option.
Migrating WebLogic Applications to WebSphere V5
We discovered and solved the following migration problems, present in the
original WebLogic example:
򐂰 J2EE 1.3 standards violations.
– Syntax errors in ejb-name deployment descriptors.
– No standard deployment descriptors for EJB references, and no use of the
local JNDI environment. These missing references caused the application
to fail in WebSphere.
򐂰 Other portability or standards problems.
– Hard-coded JNDI InitialContext and use of t3 protocol.
– Incorrect use of PortableRemoteObject narrow, both missing and
unnecessary.
5.3 Message example — MDB and JMS
This is another simple example from the WebLogic 7.0 distribution. It
demonstrates the migration of the following features. For a brief introduction to
these features, see 2.5.3, “MDB and Embedded JMS” on page 13.
򐂰 EJB 2.0 MDB (message-driven bean) deployment using the new WebSphere
Studio Application Developer.
򐂰 Configuration of JMS connection factories, destinations, and listener ports for
the new WebSphere Embedded Messaging support.
򐂰 Migration of a WebLogic JMS client.
As depicted in Figure 5-25 on page 170, the message example consists of two
pieces:
1. A pair of message-driven beans running in a J2EE server container.
Both beans are instances of the same class, so they are identical. Each bean
is a subscriber to a JMS topic destination that provides stock quote
messages.
2. A Java client program that publishes JMS messages to the topic destination.
Even though this client does not use EJBs, we plan to treat it as a J2EE
application client within WebSphere Studio Application Developer.
Decoupling is an important feature of JMS applications. In this case, the client
publisher does not know that MDBs are subscribers, and the MDBs know nothing
about the client publisher. Indeed, unlike normal EJBs, MDBs have no public
interfaces. The advantage of an MDB is that it is an easy way to construct a JMS
listener.
Chapter 5. Migration examples
169
The MDBs simply print the quotes they receive on the server console.
Example 5-10 shows the expected output. Each quote is printed by each of the
two MDB instances.
J2EE Server
Client
MDB1
JMS
Stock Quote
Destination
MDB2
Container
Figure 5-25 Message example structure
Example 5-10 Message example server console output
Received new quote : BEAS 40 1/8
Received new quote : BEAS 40 1/8
Received new quote : SUNW 79 1/2
Received new quote : SUNW 79 1/2
Received new quote : IBM 82 1/4
Received new quote : IBM 82 1/4
End message.Client...
We used the following variation on our basic migration process:
1. Validate baseline.
We ran the example out of the box as described in the WebLogic
documentation. It produced the advertised output.
170
Migrating WebLogic Applications to WebSphere V5
2. Stage source code.
This example has similarities with the one2many example, so we reused
some of its results.
– The module structure is the same with one client module and one EJB
module.
– We had similar problems with the application-client.xml and
application.xml files.
3. Import source code.
We imported both modules in this step and corrected a couple of errors.
4. Deploy application — this required two separate steps:
a. Deploy the MDB with WebSphere Studio Application Developer tools.
b. Configure the JMS service with WebSphere Administrative Console.
5. Migrate client code to remove WebLogic dependencies and make it more
portable.
6. Test cycle.
The test cycle did not go as planned. We experienced the following problems:
– Our beta version of Embedded Messaging had a problem with topic
destinations.
– Our lightweight client approach had to be modified to look up the JMS
connection factory.
We modified our original plan to include two additional steps:
a. Convert the example to use a JMS queue destination.
b. Make use of the standard J2EE application client model.
5.3.1 Stage source code
Figure 5-26 on page 172 shows the staging folder for the message example.
Based on our experience with the one2many example, we anticipated the
following problems and corrected them in the staging folder:
򐂰 “Fix JAR names in application.xml file” on page 132.
򐂰 “Missing application-client.xml file” on page 39.
Chapter 5. Migration examples
171
Figure 5-26 Staging folder for the message example
5.3.2 Import source code
We imported both the MessageApp.ear and MessageClient.jar archive files.
1. MessageApp.ear was imported according to 3.3.2, “Import and export” on
page 27.
The following errors were flagged by WebSphere Studio Application
Developer:
– Use of the proprietary weblogic.rmi.RemoteException, as shown in
Figure 5-27 on page 173.
Since this class is not used, we just removed the import statement.
– Invalid exception for MDB class, as shown in Figure 5-28 on page 174.
The J2EE specification disallows application exceptions from MDBs. This
is because application clients do not invoke MDB methods. We removed
the invalid throws clause for CreateException.
172
Migrating WebLogic Applications to WebSphere V5
We also experienced the problem described in “Missing ID in application.xml
file — beta defect” on page 29, and applied its recommended fix.
2. MessageClient.jar was imported according to “Import application client” on
page 35, modified as follows:
– The MessageClient project does not depend on the MessageApp project.
– We had to provide the main class in the Manifest.mf file as described in
“Missing main class” on page 40.
There were no errors. We chose to defer other modifications until 5.3.5,
“Migrate client code” on page 183.
Figure 5-27 Unused proprietary import
Chapter 5. Migration examples
173
Figure 5-28 MDB classes should not thrown application exceptions
5.3.3 Deploy MDB
For MDBs, J2EE specifies the following:
򐂰 The basic container interface methods, such as ejbCreate and ejbActivate.
򐂰 MDB specific interface methods, in particular the onMessage method.
򐂰 Standard MDB deployment descriptor elements, such as <transaction-type>,
and the JMS related <destination-type> and <subscription-durability>.
However, the J2EE specification does not define how the MDB binds to the
vendor’s JMS. The vendor defines this binding.
Figure 5-29 on page 176 shows the MDB Deployment Descriptor editor of
WebSphere Studio Application Developer. You get there as follows:
1. Select the ejb-jar.xml file.
2. Right-click and select Open With -> Deployment Descriptor Editor.
3. Select the Beans tab.
You may not see the MDB specific descriptors, because this page takes
different forms depending on the bean type — session, BMP, CMP, and MDB.
What you should see are the names of the two MDB instances in the
message example — exampleMessageDriven1 and
exampleMessageDriven2.
174
Migrating WebLogic Applications to WebSphere V5
4. Select an MDB to see its descriptors — we chose exampleMessageDriven1.
The distributed ejb-jar.xml contained the following standard deployment
descriptors for the exampleMessageDriven1 MDB instance. They have been
imported correctly.
– The Destination Type is topic.
– Subscription durability was not specified, so it defaults to NonDurable.
– Transaction type is Container.
5. WebSphere uses a listener port to bind an MDB to JMS.
We must provide this vendor-specific descriptor. We chose the name
QuotePort as the name for the listener port. The same name was provided to
the second MDB instance, after clicking exampleMessageDriven2. These
descriptors are stored in the ibm-ejb-jar-bnd.xmi file.
6. Save your modifications.
Example 5-11 shows the corresponding vendor-specific MDB binding for
WebLogic. It is in the weblogic-ejb-jar.xml file.
Example 5-11 WebLogic MDB deployment
<message-driven-descriptor>
<destination-jndi-name>quotes</destination-jndi-name>
</message-driven-descriptor>
From this, it is clear the WebSphere and WebLogic use different techniques to
bind an MDB to the JMS provider. In both cases, two JNDI names are needed to
use a JMS service — one for the JMS connection factory and one for the JMS
destination.
򐂰 WebSphere uses an indirect technique based on a listener port.
The listener port contains both of the JNDI names. We define a listener port in
5.3.4, “Configure JMS service” on page 176, as part of configuring the JMS
server.
򐂰 WebLogic uses a more direct technique. Both JNDI names are contained
directly in the extended deployment descriptor.
Although only the destination JNDI name appears in Example 5-11, the
connection factory JNDI name can also be provided. If not specified explicitly,
it defaults to weblogic.jms.MessageDrivenBeanConnectionFactory, found in
the config.xml file.
Chapter 5. Migration examples
175
Figure 5-29 Deployment descriptors for message-driven bean
5.3.4 Configure JMS service
The Embedded Messaging support is configured through the WebSphere
Administrative Console. See Figure 3-41 on page 74 for the console’s welcome
page. The same procedure works both for WebSphere, and for WebSphere
Studio Application Developer test server. For launching the latter, see 3.6.3, “Run
the Administrative Console in test server” on page 84. We show the WebSphere
Studio Application Developer test server procedure here.
We need to configure the following for the publish-subscribe message example:
򐂰 The JMS topic connection factory.
򐂰 The JMS topic destination.
򐂰 The listener port used in the MDB deployment.
The first two are configured as WebSphere Resources. They can have a scope
of cell, node, or server. We configured them with the scope of node. The listener
port is configured for a particular server.
176
Migrating WebLogic Applications to WebSphere V5
Create JMS topic connection factory
1. Expand the Resources folder.
2. Click Configure WebSphere JMS Providers.
3. Scroll down and click WebSphere Topic Connection Factories.
4. Click New.
In short, click Resources -> Configure WebSphere JMS Providers ->
WebSphere Topic Connection Factories -> New.
5. Enter the following, as shown in Figure 5-30 on page 178:
– Name: Quote Connection Factory — this is just a display name.
– JNDI Name: jms/quoteCF.
Although this particular choice mimics the recommended J2EE local JNDI
naming standard, this standard does not apply to global JNDI names.
Follow your installation’s global JNDI naming convention.
6. Scroll down and click OK.
The newly created topic connection factory is shown in Figure 5-31 on
page 178. The modified configuration has not been saved yet — see “Save
modified configuration” on page 181 for how to save.
Chapter 5. Migration examples
177
Figure 5-30 Create topic connection factory for message example
Figure 5-31 Completed topic connection factory for message example
178
Migrating WebLogic Applications to WebSphere V5
Create JMS topic destination
This follows the same pattern used to create the connection factory:
1. Expand Resources folder.
2. Click Configure WebSphere JMS Providers.
3. Scroll down and click WebSphere Topic Destinations.
4. Click New.
In short, click Resources -> Configure WebSphere JMS Providers ->
WebSphere Topic Destinations -> New.
5. Enter the following, as shown in Figure 5-32 on page 180:
– Name: Quote Destination — this is another display name, but if you are
defining a queue destination, see the restriction in “Declare new JMS
queue name” on page 192.
– JNDI Name: jms/quoteDN — same comments as for the topic connection
factory.
– Basic Topic Name: quoteTopic — this is the name of the topic as defined
by the JMS provider.
6. Scroll down and click OK.
Figure 5-33 on page 180 shows the newly created topic destination.
Chapter 5. Migration examples
179
Figure 5-32 Create topic destination for message example
Figure 5-33 Completed topic destination for message example
180
Migrating WebLogic Applications to WebSphere V5
Save modified configuration
We are done configuring the Resources, so this is a good time to save the
modifications. Whenever there are unsaved modifications in the Administrative
Console, you will see a warning at the top of the page, as shown in Figure 5-34.
1. Click the Save link to apply the changes — this brings up the actual save
window shown in Figure 5-35.
2. Click the Save button.
Figure 5-34 Unsaved configuration changes
Figure 5-35 Confirm changes to configuration
Create listener port for MDB
1. Expand Servers folder.
2. Click Application Servers.
3. Click server1 — or whichever server you are using.
4. Scroll down and click Message Listener Service.
5. Click Listener Ports.
6. Click New.
In short, click Servers -> Application Servers -> server1 -> Message
Listener Service -> Listener Ports -> New.
7. Enter the following as shown in Figure 5-36 on page 182:
– Name: QuotePort — the listener port name used for MDB deployment.
Chapter 5. Migration examples
181
– Connection factory JNDI Name: jms/quoteCF — as defined in “Create
JMS topic connection factory” on page 177.
– Destination JNDI Name: jms/quoteDN — as defined in “Create JMS topic
destination” on page 179.
8. Scroll down and click OK.
Figure 5-37 on page 183 shows the newly created listener port.
9. Save the changes as described in “Save modified configuration” on page 181.
Figure 5-36 Create listener port for message example
182
Migrating WebLogic Applications to WebSphere V5
Figure 5-37 Completed listener port for message example
5.3.5 Migrate client code
Although WebSphere Studio Application Developer found no errors when
importing the Client.jar file, some changes are required to migrate the client
code. Since this client is similar to the one2many example, we first reviewed the
code manually for similar errors. We found and corrected the following problems:
1. Hard-coded JNDI InitialContext properties.
We made the same modifications reported in “Remove hard-coded JNDI
InitialContext properties” on page 152.
– Removed hard-coded properties.
– Added jndi.properties file.
– Added jndiprovider.properties file.
2. Failure to use PortableRemoteObject narrow method.
There are two JNDI lookups — one for the JMS topic connection factory and
one for the JMS topic destination. We corrected both of these as described in
“Use PortableRemoteObject narrow” on page 156.
The two original JMS-related JNDI names are also hard-coded:
򐂰 The topic connection factory JNDI name is weblogic.jms.ConnectionFactory.
򐂰 The topic destination JNDI name is quotes.
Chapter 5. Migration examples
183
Since there are only two such values, we chose to convert them to command
parameters, as recommended in 4.5.5, “Portable environment variables in
lightweight clients” on page 122.
򐂰 The modified code, partially shown in Figure 5-38, uses variables for the JNDI
names that are provided by command parameters:
– connectionFactoryName
– TOPIC_NAME
򐂰 The runWASClient.cmd was modified to pass in the corresponding JNDI
names:
– jms/quoteCF
– jms/quoteDN
Since the message Client.jar does not need EJB interfaces, there is no need to
add interfaces and stubs as we had to do for the one2many example.
Figure 5-38 Parameters for JNDI names make code more portable
184
Migrating WebLogic Applications to WebSphere V5
5.3.6 Test cycle
The testing cycle for this example did not go as planned. We had planned to test
the message example with the same lightweight client used in the one2many
example. We had the following problems:
1. Initially, the Embedded Messaging support for JMS topics did not work in our
beta systems.
Embedded Messaging was not yet operational in our WebSphere Studio
Application Developer test server. In our WebSphere system, the JMS queue
support worked fine, but the topic support did not.
These beta defects were subsequently corrected.
2. The lightweight client, constructed in 5.3.5, “Migrate client code” on page 183,
caused the exception shown in Example 5-12.
The lightweight client locates the JMS connection factory with a global JNDI
lookup. We expected a javax.jms.TopicConnectionFactory type to be
returned. Instead, we got a javax.naming.Reference type to a
javax.jms.TopicConnectionFactory.
Example 5-12 JMS connection factory not available via global JNDI lookup
java.lang.ClassCastException: javax.naming.Reference at
com.ibm.rmi.javax.rmi.PortableRemoteObject.narrow
This exception occurred while executing the following Client statement:
TopicConnectionFactory cf = (TopicConnectionFactory)
PortableRemoteObject.narrow
(m_context.lookup(“jms/quoteCF”), TopicConnectionFactory.class);
Change of strategy
Dealing with these problems gave us the opportunity to investigate two additional
features. We temporarily changed our plan as follows:
1. Convert the message example from a JMS topic to a JMS queue.
This made it a different application, but the queues were working at the time.
From a migration perspective, queues expose essentially the same migration
issues.
2. Use a standard J2EE application client to get the application up and running.
The J2EE application client is standard, so it should cause fewer problems.
After the application is running, we revisit the lightweight application client
issue. See 5.3.9, “Lightweight JMS client” on page 201.
Chapter 5. Migration examples
185
5.3.7 JMS queue variation on the message example
The two parts to this conversion are covered in the following subsections:
򐂰 Convert the Client and MDB modules.
򐂰 Configure the server for a JMS queue.
Convert Client and MDB modules
The Client and MDB modules require different treatments. We did both of these
with WebSphere Studio Application Developer.
1. Client module — change the Java code.
Deployment of the modified Client module is described in 5.3.8, “Standard
J2EE Application Client” on page 191.
2. MDB module — modify deployment descriptors.
No Java source code changes were needed to convert the MDB module. In
general, an MDB does not need to know if it is for a topic or a queue
destination.
The Client.java code was changed with the following global text changes.
Change all strings regardless of case, but maintain the original case:
򐂰 Change topic to queue.
򐂰 Change publish to send.
Figure 5-39 on page 187 shows a portion of the resulting Java code.
186
Migrating WebLogic Applications to WebSphere V5
Figure 5-39 Change topic to queue, and publish to send
We changed the MDB deployment descriptors in the Beans tab of the
WebSphere Studio Application Developer Deployment Descriptor editor.
1. Delete the exampleMessageDriven2 — in a point-to-point queue, each
message is delivered to just one subscriber.
a. Select the exampleMessageDriven2 bean.
b. Click the Remove button.
c. Select the Delete Bean Only and the Delete Deployed Code options, as
shown in Figure 5-40 on page 188. Either of the other options will cause
the source code to be deleted too.
2. Change the destination type to queue.
a. Select the exampleMessageDriven1 bean.
b. Use the Destination type selector to specify the queue type, as shown in
Figure 5-41 on page 188.
3. Save the changes.
4. Export the modified EAR file.
Chapter 5. Migration examples
187
Figure 5-40 Only remove the bean instance and its deployment code
Figure 5-41 Change destination type from topic to queue
188
Migrating WebLogic Applications to WebSphere V5
Non-portable JMS code
Notice the code in the catch clause in Figure 5-39 on page 187. It appears to be
creating the destination object on the fly, and binding it to a global JNDI name.
Unfortunately, it violates the J2EE specifications and is highly non-portable.
1. The JMS specification say the following about the createQueue and
createTopic methods:
– Their use is not portable.
– They are not designed to create physical queues or topics. Physical
queues and topics are created by administrative tasks and are not initiated
by the JMS API.
– They do not create temporary queues or topics. These are created by the
createTemporaryQueue and createTemporaryTopic methods.
2. Although the JNDI bind is legal for a global JNDI context, it will not make
these queue or topic objects available for use in WebSphere.
3. The J2EE specification disallows the JNDI bind for the local java:comp/env
context. We must use the local JNDI context in a standard J2EE application
client container.
This code is most likely a design error, and it has no plausible conversion to
WebSphere. A migration effort is an opportunity to correct such errors. We
recommend that the catch clause be deleted, allowing the exception to
propagate to the caller. We did not actually make this change.
Configure JMS queue
The instructions in 5.3.4, “Configure JMS service” on page 176, configure the
WebSphere Studio Application Developer test server for a JMS topic application.
This section describes how to configure WebSphere for a JMS queue
application. In both cases we use the Embedded Messaging JMS provider. Since
these procedures are almost identical, we show only the differences here.
Listener port
For clarity, we used different JNDI names for the queue connection factory and
destination. These are shown in Figure 5-42 on page 190. Compare this figure
with Figure 5-36 on page 182. The only other difference is to make sure that you
enable the listener port. Check the Enabled box as shown in Figure 5-43 on
page 191. The page will appear after defining the listener port.
Chapter 5. Migration examples
189
Figure 5-42 Listener port for queue version of message example
190
Migrating WebLogic Applications to WebSphere V5
Figure 5-43 Enable message listener service
Queue connection factory and destination
For the queue connection factory, see Figure 5-44 on page 192 and compare it
with the topic connection factory in Figure 5-30 on page 178. For the queue
destination, see Figure 5-45 on page 192 and compare it with the topic
destination in Figure 5-32 on page 180. The differences are as follows:
1. We used the new JNDI names for the queue configuration.
2. In the queue destination, there is nothing corresponding to the topic
identification.
3. The name of the queue destination must not contain blanks — see “Declare
new JMS queue name” on page 192 for an explanation of this restriction.
Chapter 5. Migration examples
191
Figure 5-44 JMS Quote Queue Connection Factory
Figure 5-45 JMS queue destination
Declare new JMS queue name
In addition to defining the connection factory and destination JNDI names, the
queue name must also be added to a list of names in the internal JMS server.
This is not needed to configure a JMS topic. The queue name is the
administrative name provided in the queue destination. For example,
QuoteQueueDestination is the queue name in Figure 5-45. This name must not
contain blanks.
192
Migrating WebLogic Applications to WebSphere V5
If the queue name is not added to the internal JMS server list, an attempt to use
the JMS queue results in the exception shown in Example 5-13.
Example 5-13 Queue name missing form the internal JMS server list
javax.jms.InvalidDestinationException: MQJMS2008: failed to open MQ queue
Here is how to add this name to the internal JMS server:
1. Expand Servers folder.
2. Click Managed Application Servers.
3. Click server1 — or whichever server you are using.
4. Scroll down and click Server Components.
5. Click JMS Server.
In short, click Servers -> Managed Application Servers -> server1 ->
Server Components -> JMS Server.
6. Add the new queue name to the queueNames list, as shown in Figure 5-46 on
page 194.
7. Click OK.
8. Save the changes as described in “Save modified configuration” on page 181.
9. Restart the server to make these changes effective.
One way to verify that the JMS queue configuration is correct is to install the
application and check the AppServer/logs/server1/SystemOut.log for any errors.
Also examine createMQ.log. Install the application client by following the
instructions in 3.6.4, “Install EAR into WebSphere” on page 86.
Chapter 5. Migration examples
193
Figure 5-46 Add queue name to internal JMS server
5.3.8 Standard J2EE application client
For migration purposes, we have treated the client code as a standard J2EE
application client within the WebSphere Studio Application Developer
environment. But we have also followed the restrictions discussed in 4.5.1,
“Lightweight application client” on page 117. In this section, we abandoned those
restrictions and implemented the full J2EE application client standard. Three
steps are needed:
1. Use the local JNDI environment for module and resource references, in
particular for JMS connection factory and destination references.
2. Use the clientConfig tool to complete deployment for the JMS connection
factory resource.
3. Use the launchClient tool to execute the client.
194
Migrating WebLogic Applications to WebSphere V5
Deploy local JNDI environment
We have to create deployment descriptors for the following two references:
1. A resource reference for the JMS connection factory.
This replaces the global JNDI lookup that failed in 5.3.6, “Test cycle” on
page 185, and it is the reason we chose to move to the standard J2EE
application client model. Using a local JNDI lookup solves this problem.
We use java:comp/env/jms/ConnectionFactory for this reference. There is no
corresponding global JNDI name. In this case, the JNDI name jms/quoteQCF
is not configured into the application client.
2. A resource environment reference for the JMS queue destination.
We actually have a choice here, because this lookup works with either the
local JNDI context or the global JNDI context. To conform to the standard, we
chose the local JNDI context.
We use java:comp/env/jms/quoteQueue for this reference. It corresponds to
the global JNDI name jms/quoteQDN.
It is common practice to hard-code local JNDI names into the Java code.
However, it is easier to provide them through the parameters introduced in 5.3.5,
“Migrate client code” on page 183. Moreover, since no Java code changes are
required — only deployment descriptor changes — we chose to use AAT instead
of WebSphere Studio Application Developer. The same changes can be
performed by either tool.
Resource reference for JMS queue connection factory
1. Start AATby clicking Start -> Programs -> IBM WebSphere -> Application
Server v5.0 -> Application Assembly Tool.
2. Open an existing EAR file — MessageApp04-messageQueue.ear in this
case.
3. Expand Application Clients -> MessageClient. You will see entries for
Resource Environment References and Resource References as shown in
Figure 5-47 on page 196.
4. Select Resource References.
5. Right-click and select New. See the New Resource Reference window in
Figure 5-47 on page 196.
6. Complete the following fields on the General tab:
– Name: jms/ConnectionFactory — this corresponds to the local JNDI name
java:comp/env/jms/ConnectionFactory.
– Use the Type selector to enter type javax.jms.QueueConnectionFactory.
Chapter 5. Migration examples
195
7. Click OK.
Note that the Bindings tab is not used to configure this reference.
Figure 5-47 Deploy client resource reference for JMS queue factory connection
Resource environment reference for JMS queue destination
Continue with the AAT example:
1. Select Resource Environment References.
2. Right-click and select New.
3. Complete the fields on the General tab. The results are shown in Figure 5-48
on page 197.
– Name: jms/quoteQueue. This corresponds to the local JNDI name
java:comp/env/jms/quoteQueue.
– Use the Type selector to enter the type javax.jms.Queue.
196
Migrating WebLogic Applications to WebSphere V5
4. Click the Bindings tab.
5. Enter jms/quoteQDN for the JNDI name, as shown in Figure 5-48. This is the
global JNDI name for the destination.
6. Click OK.
7. Click File -> Save.
8. Click File -> Exit.
Figure 5-48 Deploy client resource environment reference for JMS queue destination
The resulting deployment descriptors are placed in the application-client.xml and
the ibm-application-client-bnd.xmi files. See Example 5-14 and Example 5-15 on
page 198 for excerpts from these files.
Example 5-14 Message client application-client.xml file
<application-client id="Application-client_ID">
<display-name>MessageClient</display-name>
<resource-ref id="ResourceRef_1">
<res-ref-name>jms/ConnectionFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<res-auth>Application</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-env-ref id="ResourceEnvRef_1">
<resource-env-ref-name>jms/quoteQueue</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>
</application-client>
Chapter 5. Migration examples
197
Example 5-15 Message client ibm-application-client-bnd.xmi file
<resourceRefs xmi:id="ResourceRefBinding_1">
<jndiName xsi:nil="true"/>
<bindingResourceRef
href="META-INF/application-client.xml#ResourceRef_1"/>
</resourceRefs>
<resourceEnvRefBindings xmi:id="ResourceEnvRefBinding_1"
jndiName="jms/quoteQDN">
<bindingResourceEnvRef
href="META-INF/application-client.xml#ResourceEnvRef_1"/>
</resourceEnvRefBindings>
Configure client
The clientConfig tool binds java:comp/env/jms/ConnectionFactory to the JMS
queue connection factory. It does this by adding a client-resource.xmi file to the
client deployment descriptors. Without this WebSphere-specific deployment
descriptor, the connection factory lookup fails with the exception shown in
Example 5-16.
Example 5-16 Exception for missing client-resource.xmi file
javax.naming.NameNotFoundException: Name "comp/env/jms/ConnectionFactory"
not found in context "java:".
1. Open a command prompt.
2. cd to WebSphere/AppServer/bin.
3. Enter the clientConfig command — see Figure 5-50 on page 200.
4. Click File -> Open and browse to the EAR file —
MessageApp04-messageQueue.ear in this case.
5. Expand MessageClient.jar -> JMS Providers -> WebSphere JMS
Provider.
6. Select WAS Queue Connection Factory.
7. Right-click and select New to bring up the properties window shown in
Figure 5-49 on page 200.
8. Under the General tab, enter the following:
– Name: Connection Factory — this is a display name.
– JNDI Name: jms/ConnectionFactory — this is the local JNDI name
java:comp/env/jms/ConnectionFactory.
– Node: ITSO — this is the node name of the application server.
198
Migrating WebLogic Applications to WebSphere V5
9. Click OK — the Connection Factory property is added as shown in
Figure 5-50 on page 200.
10.Click File -> Save.
11.Click File -> Exit.
Example 5-17 shows the salient contents of the newly generated
client-resource.xmi file. This includes the local JNDI name, the node, and the
WASQueueConnectionFactory type.
Example 5-17 The message example client-resource.xmi file
<resources.jms:JMSProvider xmi:id="JMSProvider_1" name="MQ JMS Provider"
description="Default - cannot be changed"/>
<resources.jms:JMSProvider xmi:id="JMSProvider_2"
name="WebSphere JMS Provider" description="Default - cannot be changed">
<factories
xmi:type="resources.jms.internalmessaging:WASQueueConnectionFactory"
xmi:id="WASQueueConnectionFactory_1" name="Connection Factory"
jndiName="jms/ConnectionFactory" description="" node="ITSO">
<propertySet xmi:id="J2EEResourcePropertySet_1"/>
</factories>
</resources.jms:JMSProvider>
Chapter 5. Migration examples
199
Figure 5-49 BInd local JNDI name to queue connection factory resource
Figure 5-50 The clientConfig tool binds connection factory to application client
200
Migrating WebLogic Applications to WebSphere V5
Launch client
A standard J2EE application client is executed by passing the application’s EAR
file to the launchClient command. We do this from the code shown in
Example 5-18. Its name is runWASClient-queue. The parameters are for the
two JNDI names as implemented in 5.3.5, “Migrate client code” on page 183.
They are being used here for local JNDI names.
Example 5-18 Execute J2EE application client with launchClient command
@set WAS_BASE=c:\Program Files\WebSphere
@set launchClient=%WAS_BASE%\AppServer\bin\launchClient
"%launchClient%" c:\itso3\examples\message\export\MessageApp04-messageQueue.ear
java:comp/env/jms/ConnectionFactory
java:comp/env/jms/quoteQueue
1. Start the WebSphere server by clicking Start -> Programs -> IBM
WebSphere -> Application Server v5.0 -> Start the Server.
2. Install the EAR into WebSphere by following the instructions in 3.6.4, “Install
EAR into WebSphere” on page 86.
3. Start a Command Prompt window for the application client.
4. cd to examples/message/Export.
5. Enter the command runWASClient-queue.
Examine the AppServer/logs/server1/SystemOut.log for the expected output as
shown in Example 5-10 on page 170. Since we removed the second MDB
instance, there should be just three messages — one for each quote.
5.3.9 Lightweight JMS client
Now that the message application has been migrated according to the J2EE
standards, we return to the issue of a lightweight JMS application client. Think of
this as an optional optimization step. In general, the result will be non-standard
and non-portable, so retain the standard J2EE application client for maintenance
and testing purposes. In this case, the only difference turned out to be the
command script itself.
The problem in 5.3.6, “Test cycle” on page 185, was that the global JNDI lookup
of the connection factory returned the type javax.naming.Reference. This type is
used to represent an object stored outside the JNDI system. The Reference
refers to the type of the object’s factory. When the Reference is returned to the
application client, the name manager attempts to use the identified factory to
instantiate the actual object. If the factory cannot be found, or if it fails, the
Chapter 5. Migration examples
201
Reference itself is returned by the lookup method. A common reason for failure is
a missing JAR in the classpath of the application client.
We used the correctly executing J2EE application client as a starting point for a
trial-and-error search for the missing JAR files.
򐂰 Its lookup returns type com.ibm.mq.jms.MQXAQueueConnectionFactory.
򐂰 The launchClient command script provided a list of possible folders and JAR
files.
We discovered the following dependencies:
򐂰 The connection factory class is in the MQSeries java/lib/com.ibm.mqjms.jar.
򐂰 The WebSphere lib/messagingImpl.jar drives the conversion of the JNDI
Reference object.
򐂰 The MQException class is used, and it is found in MQSeries
java/lib/com.ibm.mq.jar.
򐂰 Properties are provided by the MQSeries java/lib folder.
Exploiting this knowledge makes our application WebSphere specific. However,
since we provide the critical JNDI names as parameters, no source code is
affected. The only difference is a different command script. In this case, at least,
we were able to construct a lightweight application client that is also J2EE
portable. The lightweight JMS application client is implemented by the
runWASClient-lw command script shown in Example 5-19. This command
generates the same output as 5.3.8, “Standard J2EE application client” on
page 194.
Example 5-19 Command script for lightweight JMS application client
set WAS_BASE=c:\Program Files\WebSphere\AppServer
set JAVA_HOME=%WAS_BASE%\java
set JAVA=%JAVA_HOME%\bin\java
set CLASSPATH=%WAS_BASE%\lib\client.jar
set CLASSPATH=%CLASSPATH%;MessageClient-queue.jar
set
set
set
set
set
MQ_BASE=c:\Program Files\IBM\MQSeries
CLASSPATH=%CLASSPATH%;%MQ_BASE%\java\lib\com.ibm.mqjms.jar
CLASSPATH=%CLASSPATH%;%WAS_BASE%\lib\messagingImpl.jar
CLASSPATH=%CLASSPATH%;%MQ_BASE%\java\lib\com.ibm.mq.jar
CLASSPATH=%CLASSPATH%;%MQ_BASE%\java\lib
"%JAVA%" examples.ejb20.message.Client jms/quoteQCF jms/quoteQDN
202
Migrating WebLogic Applications to WebSphere V5
5.3.10 Summary
We demonstrated use of the following features and tools:
򐂰 Deployment of an MDB.
򐂰 Configuration of WebSphere Embedded JMS Messaging:
– For both topic and queue.
– For both WebSphere and WebSphere Studio Application Developer test
server.
򐂰 Deployment of a standard J2EE application client. We used the following
tools for this:
– AAT.
– The clientConfig tool.
– The launchClient tool.
We discovered and solved the following migration problems present in the
original WebLogic example:
򐂰 J2EE 1.3 standards violations:
– Invalid exceptions in MDB.
򐂰 Other portability or standards problems:
–
–
–
–
–
Hard-coded JNDI InitialContext and use of t3 protocol.
Missing PortableRemoteObject narrow.
Proprietary WebLogic RemoteException.
Making hard-coded variables portable in application clients.
Non-portable JNDI bind of a JMS destination object.
We implemented two different application client models for this JMS example:
The standard J2EE application client.
򐂰 An optimized lightweight application client that uses WebSphere specific
libraries.
Moreover, we showed how to do this with no source code changes, and thus
retain J2EE portability.
5.4 Filters example — servlet filters and authentication
This example highlights two of the new Web features in J2EE 1.3:
򐂰 Filters — see 2.5.4, “Filters” on page 15.
򐂰 Form-based authentication — see 2.5.5, “J2EE form-based authentication”
on page 16.
Chapter 5. Migration examples
203
The filters example is part of the WebLogic 7.0 distribution. Although it is a small
example, it presented a number of interesting migration issues:
򐂰 J2EE standards for filters.
There were several versioning and syntax errors in the distributed
deployment descriptors.
򐂰 Converting from proprietary WebLogic authentication to portable J2EE
form-based authentication.
Migrating proprietary authentication code is usually a problem. The J2EE 1.3
form-based authentication offers a portable solution for basic user
ID/password Web authentication. In particular, we address the intricacies of
deploying form-based authentication on WebSphere.
򐂰 Creating a standard EAR archive for a Web application.
Collecting source code, and organizing it into a standard EAR format is a
recurring migration problem. This example addresses this task for a Web
application.
Figure 5-51 on page 205 shows the pieces of the filters example along with its
flow of control.
򐂰 The welcome page, index.html, links to /filterWebApp/session, and the URL is
mapped to sessionServlet.java.
򐂰 The two filters, loginFilter.java and logFilter.java, intercept every reference to
/filterWebApp/session before invoking sessionServlet.
– loginFilter redirects the request to the loginForm.jsp if the user has not
been authenticated yet.
•
Authentication is performed by authenticate.jsp and error.jsp, if
needed.
•
A session variable records the authentication state.
– logFilter just measures the time spent in sessionServlet.
– Control flow through the two filters and the sessionServlet is defined by
deployment descriptors. All other control flow is explicit.
– Since filters act like wrappers, each filter has control both before and after
it invokes the next member of the filter chain.
򐂰 sessionServlet tracks the session, counting the number of times it is invoked
within the same session.
204
Migrating WebLogic Applications to WebSphere V5
index.html
URL: /filterWebApp
loginFilter.java
URL: /filterWebApp/session
loginForm.jsp
authenticate.jsp
error.jsp
logFilter.java
sessionServlet.java
Figure 5-51 Filters example flow of control
We migrated this example from WebLogic to WebSphere, using WebSphere
Studio Application Developer. It follows a variation on the migration process
described in 4.2, “Migration process” on page 99.
1. Verify baseline.
The baseline verification was straightforward. We followed the WebLogic
instructions and the example worked as advertised.
2. Stage source code.
Since this is the only Web module that we migrated for this paper, we
describe the staging of the source code, and the construction of an EAR file
for import into WebSphere Studio Application Developer.
3. Import source code.
We corrected several versioning problems, removed some WebLogic
dependencies, and disabled the proprietary authentication so we could focus
first on getting the filters to work.
4. We converted to J2EE form-based authentication to make the example more
portable.
Two different variations on authentication and session tracking are presented:
a. Non-secure authentication using cookies for session tracking — this
mimics the original example.
b. Secure authentication using SSL session tracking.
5.4.1 Stage source code
The goal of this step is to create a standard EAR file that will import into
WebSphere Studio Application Developer. The source for the filters example is
Chapter 5. Migration examples
205
provided in a single folder, named examples/servlets/filters. This corresponds to
the package name of the Java code, but HTML and JSP files are found in the
folder as well. The Ant build script places files into the correct WebLogic folders,
but it does not create a standard EAR file. As described in 4.2.3, “Stage source
code” on page 101, we recommend using a staging folder to create an EAR file
containing all source code. If the initial import fails, it is easy to make corrections
and additions to the staging folder.
Staging Web source
Figure 5-52 on page 207 shows the staging folder for the filters example. The
migrate_src.cmd creates a FilterApp.ear file and places it into the corresponding
Import folder ready for use. As a Web module, it has the following structure:
򐂰 The Java source code is organized by packages in the web-inf/classes folder.
򐂰 The web.xml file is in the web-inf folder.
򐂰 The HTML and JSP files are at the top level of the FilterWeb module folder.
It took a couple of debugging cycles before the resulting EAR file would import
into WebSphere Studio Application Developer. We made the following errors:
򐂰 When the examples.servlets.filters package was not in the web-inf/classes
folder, WebSphere Studio Application Developer flagged web.xml references
as broken links because they could not be found.
򐂰 We had to add the application.xml file, as described in the next section.
206
Migrating WebLogic Applications to WebSphere V5
Figure 5-52 Staging folder for the filters example
Need application.xml file
A proper EAR file requires an application.xml file. Indeed, WebSphere Studio
Application Developer refuses to import an EAR file without an application.xml
file. Since the original source for this example does not include an
application.xml file, we constructed one and added it to the staging folder. This
file is shown in Figure 5-53 on page 208. It contains the minimum required by
WebSphere Studio Application Developer for the filters example.
򐂰 The version information, provided in the DOCTYPE header. Our example
includes filters, so we made sure the version level is J2EE 1.3.
򐂰 The name of the WAR file.
򐂰 The root context.
Chapter 5. Migration examples
207
An easy way to determine what WebSphere Studio Application Developer
requires is to create a similar dummy project, and then replicate its
application.xml file. That is what we did. We later experienced the problem
described in “Missing ID in application.xml file — beta defect” on page 29, and
applied its recommended fix at that time.
Figure 5-53 Constructed application.xml for the filters example
5.4.2 Import source code
Figure 5-54 on page 209 shows the results of importing our newly constructed
EAR file into WebSphere Studio Application Developer:
򐂰 33 errors — logFilter.java, loginFilter.java, web.xml, and authenticate.jsp.
򐂰 4 warnings — error.jsp and loginForm.jsp.
At this point, the messages in the task list can help prioritize the migration effort.
We examined the messages in the following order:
1. Errors in web.xml file.
Errors in deployment descriptor files can have a big impact on other
resources, so it is wise to investigate them first.
2. Other errors.
After fixing errors in deployment descriptors, there are often fewer, or at least
different, errors in other files.
3. Warnings.
Sometimes, warnings and informational messages can be ignored.
208
Migrating WebLogic Applications to WebSphere V5
Figure 5-54 Results of importing constructed EAR file for the filters example
Chapter 5. Migration examples
209
Correct web.xml file
The original web.xml file contained two basic errors:
1. The DOCTYPE header line, shown in Example 5-20, had inconsistent and
incorrect version information.
This is a serious error, because different versions of deployment descriptor
files have different syntaxes. The web.xml file cannot be parsed properly
without the correct version level. This file contains <filter> and
<filter-mapping> descriptors, which were introduced with the web-app_2_3
DTD.
We corrected this error by updating the DOCTYPE version information to the
web-app_2_3 DTD level. This corrected one error, but that was immediately
replaced by another error in the same file. Now that the file was being parsed
by the correct DTD, WebSphere Studio Application Developer reported
syntax errors.
Example 5-20 Inconsistent and incorrect version information in web.xml file
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 1.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
2. The web.xml syntax error is depicted in the XML editor in Figure 5-55 on
page 211.
The problem is that the web-app DTD requires that <filter> and
<filter-mapping> stanzas appear before the <servlet> stanza. The distributed
web.xml file has these reversed. This is also a serious error, because as a
result, the deployment descriptor information is not processed.
We fixed this error by moving the <servlet> and <servlet-mapping> stanzas
after the <filter-mapping> stanzas. This was easy, and even fun, because the
XML editor supports drag-and-drop editing. This resolved the web.xml errors.
210
Migrating WebLogic Applications to WebSphere V5
Figure 5-55 Syntax error in web.xml file — filters should come before servlets
More version problems
Now that the web.xml version level and syntax errors were corrected, we
expected that some of the other errors would disappear as a side effect.
Surprising, this did not happen. As an example, look at the logFilter.java file,
shown in Figure 5-56 on page 212. It still does not recognize the Filter
dependencies supported in version level 2.3!
If something looks like a versioning problem, double-check the version level of
the resource. Figure 5-57 on page 213 shows that the J2EE version level of the
FilterWeb resource was set to 1.2. It should be 1.3. This is a side effect of the
original DOCTYPE versioning problem, which specified the incorrect
web-app_2_2 DTD. Find and correct this problem as follows:
1. Select the FilterWeb project.
2. Right-click and select Properties at the very bottom of the pop-up menu.
3. Select Web, as seen in Figure 5-57 on page 213.
4. Adjust the J2EE level to 1.3.
5. Click OK.
The result is no errors in the logFilter.java file, and Filters are now recognized.
Chapter 5. Migration examples
211
Figure 5-56 Unrecognized Filter dependency suggests another version level error
212
Migrating WebLogic Applications to WebSphere V5
Figure 5-57 Correct J2EE version level of FilterWeb resource
Remove WebLogic dependencies
Now there are only two files with errors:
򐂰 authenticate.jsp — 6 errors.
򐂰 loginFilter.java — 3 errors.
Both of these files depend on the proprietary WebLogic ServletAuthentication
class included by means of:
import weblogic.servlet.security.*;
In loginFilter.java, this class is actually never used, so we just removed the
import statement and related variable. This unused code was probably left over
from an earlier version of the example.
This brings us to the final set of errors. Looking at Figure 5-58 on page 214, it is
clear that authenticate.jsp is the heart of the custom, WebLogic-specific
Chapter 5. Migration examples
213
authentication code. We plan to replace this code with portable J2EE form-base
authentication in 5.4.4, “Convert to portable form-based J2EE authentication” on
page 220. To stay focused on the filters code for now, we temporarily replaced
authenticate.jsp with the code shown in Figure 5-59. This effectively deactivates
authentication by accepting any and all user IDs and passwords. It also takes
care of the last of our error messages.
Figure 5-58 Original WebLogic-specific authenticate.jsp code
Figure 5-59 Temporary replacement for authenticate.jsp
Fix minor HTML errors
Finally, there are four warning messages remaining on the task list. Figure 5-60
on page 215 shows examples of these problems. These problems do not affect
runtime behavior, so we could ignore them, but they are easy to fix. The HTML
214
Migrating WebLogic Applications to WebSphere V5
<font> tag should only enclose text, not other constructs. Replicating the <font>
tag where needed and adding </font> closures solves this problem.
To help analyze this sort of error, the WebSphere Studio Application Developer
Context Assist is often quite helpful. It tells you what syntactic elements are legal
at any particular position. It can be launched by pressing Ctrl+spacebar, or
right-clicking and selecting Context Assist. Using the Context Assist ensures
syntactically correct elements.
Figure 5-60 Incorrect use of <font> tag
5.4.3 Deploy and test filters
All necessary deployment has already been done. Although we did have to
correct versioning and syntax problems in web.xml, we did not need to change
Chapter 5. Migration examples
215
any of the original deployment descriptors. The imported deployment descriptors
are available under different tabs in the Web Deployment Descriptor editor:
򐂰 The index.html welcome page and the /error.jsp 404 error page are under the
Pages tab.
򐂰 The mapping of the sessionServlet to the /session URL is under the Servlets
tab.
򐂰 The loginFilter and logFilter filter chain, and their mappings to the /session
URL, are under the Filters tab, as shown in Figure 5-61.
򐂰 The XML text version of web.xml is available under the Source tab.
The Web Deployment Descriptor editor is accessed in the normal way. Either
double-click web.xml, or:
1. Select web.xml.
2. Right-click and select Open With -> Deployment Descriptor Editor.
Figure 5-61 Filter chain and URLs in Web Deployment Descriptor editor
Test run
To help trace the behavior of the filters, we instrumented the code with
System.out.println statements.
򐂰 In loginFilter and logFilter — on entry to doFilters, and before and after the
nested FilterChain doFilters call.
򐂰 In sessionServlet — on entry to doGet.
The migrated, instrumented code behaved as expected, following these steps:
1. Create a test server as described in 3.5.1, “Test server setup” on page 71.
216
Migrating WebLogic Applications to WebSphere V5
2. Start the Web application in the test server.
a. Select the FilterApp project.
b. Right-click and select Run on Server.
3. Open your favorite browser.
4. Enter the URL http://localhost:9080/filterWebApp — see Figure 5-62.
– The HTTP port setting of 9080 is displayed in the server console after
startup. It can be modified under the Ports tab of the server configuration
editor.
– The root context of filterWebApp is found under the Module tab of the
application.xml Deployment Descriptor editor.
5. Click the Click here link — see the loginForm in Figure 5-63 on page 218.
6. Enter any user ID/password and click the Login button — see the
sessionServlet in Figure 5-64 on page 219.
Remember that any user ID/password will be accepted at this point in the
migration.
Figure 5-62 Filters example welcome page
Chapter 5. Migration examples
217
Figure 5-63 Filters example loginForm authentication page
218
Migrating WebLogic Applications to WebSphere V5
Figure 5-64 Filters example sessionServlet session tracking page
Trace output
Example 5-21 on page 220 shows our instrumented trace output. It is clear that
the filters are behaving as advertised.
򐂰 On its first entry, loginFilter :
a. Redirects to loginForm to set up the authentication dialog.
b. Aborts further filter chaining.
Chapter 5. Migration examples
219
The authenticate JSP sets a user-defined session variable named
authenticated. This can be seen in both the original code in Figure 5-58 on
page 214 and in the modified code in Figure 5-59 on page 214. The
loginFilter tests this variable to control its redirection logic.
򐂰 On its second entry, loginFilter proceeds with normal filter chaining.
This is because authenticate.jsp has recently set the authenticated session
variable to true.
Example 5-21 Filters example trace output [edited and indented for readability]
I
O
O
O
O
I
I
O
O
O
O
O
O
I
O
[FilterWeb.war] [/filterWebApp] [Servlet.LOG]: sessionServlet: init
[loginFilter]: loginFilter invoked ...
[logFilter]: logFilter invoked ...
[loginFilter] doFilter entered.
[loginFilter] redirecting to loginForm.jsp.
[FilterWeb.war] [/filterWebApp] [Servlet.LOG]: /loginForm.jsp: init
[FilterWeb.war] [/filterWebApp] [Servlet.LOG]: /authenticate.jsp: init
[loginFilter] doFilter entered.
[loginFilter] before nested doFilter call.
[logFilter] doFilter entered.
[logFilter] before nested doFilter call.
[sessionServlet] doGet entered.
logFilter] after nested doFilter call.
[FilterWeb.war] [/filterWebApp] [Servlet.LOG]:
[logFilter]Time to process servlet request /filterWebApp/session :
0millis
[loginFilter] after nested doFilter call.
5.4.4 Convert to portable form-based J2EE authentication
Now we are ready to replace the deactivated authentication logic with J2EE 1.3
form-based authentication. This demonstrates the following:
򐂰 Introduce more adaptable code during a migration process.
Since we must migrate the proprietary WebLogic code, this is an excellent
opportunity to introduce a more portable solution.
򐂰 Demonstrate the use of another of the new J2EE 1.3 features.
See 2.5.5, “J2EE form-based authentication” on page 16 for a short
introduction to this feature. When combined with filters, it can be used for
elegant security control. For more in-depth coverage of WebSphere security
and authentication, see IBM WebSphere V5.0 Security Handbook,
SG24-6573. It describes the use of filters and J2EE form-base authentication
in the context of an LDAP registry.
220
Migrating WebLogic Applications to WebSphere V5
򐂰 More practice with using WebSphere Studio Application Developer tools.
In particular, we introduce the Pages and Security tabs of the Web
Deployment Descriptor editor, and the Security tab of the Application
Deployment Descriptor editor.
򐂰 Practical example of how to implement Web authentication in a WebSphere
application.
Since some aspects of security code are not covered by the J2EE
specifications, a small amount of WebSphere-specific knowledge is still
required.
Conceptually, this conversion is simple:
򐂰 Reuse the loginForm.jsp and error.jsp pages for J2EE form-based
authentication.
򐂰 Eliminate authenticate.jsp and its invocation.
In practice, this conversion has several tasks. Moreover, it is hard to find some of
the appropriate editors in WebSphere Studio Application Developer. We outline
the entire process here, and cover the details in the following sections.
򐂰 Make current code portable:
– Convert loginForm.jsp and error.jsp to the J2EE standard.
– Remove redirection from loginFilter.
򐂰 Do the J2EE portable part of deployment:
– Deploy form-based authentication.
– Make the /session URL a protected resource.
•
Define a J2EE security role — we called it login.
•
Deploy a security constraint for the /session URL using the login role.
򐂰 Do the WebSphere-specific part of deployment:
– Enable security for local operating system authentication.
– Map the login role to the AllAuthenticatedUsers special subject.
Make current code portable
J2EE form-based authentication mandates the use of the names
j_security_check, j_username, and j_password in the form-login and form-error
pages. We modified the loginForm.jsp and error.jsp pages accordingly:
򐂰 Replace action=”authenticate.jsp” with action=”j_security_check”.
򐂰 Replace name=”username” with name=”j_username”.
򐂰 Replace name=”password” with name=”j_password”.
Chapter 5. Migration examples
221
Figure 5-65 shows the modified loginForm.jsp page.
There are no remaining references to the authenticate.jsp page. The only
reference to the loginForm is the redirection logic in loginFilter. This will not be
needed with the J2EE form-based authentication, so we removed this logic along
with references to the session variable, named authenticated. The effect of these
changes is the following:
򐂰 The authenticate.jsp file is no longer referenced and can be deleted.
򐂰 The loginFilter no longer does anything meaningful. We chose to retain the
loginFilter for comparison with the trace output produced in Example 5-21 on
page 220.
Figure 5-65 Filters example loginForm converted to a J2EE form-login-page
Do J2EE part of deployment
As a reminder, here are the standard J2EE aspects of deploying form-based
authentication:
򐂰 Deploy form-based authentication.
The loginForm.jsp and error.jsp pages are now free to be reused for
deployment with J2EE form-based authentication.
222
Migrating WebLogic Applications to WebSphere V5
򐂰 Make the /session URL a protected resource.
– Define a J2EE security role — we called it login.
– Deploy a security constraint for the /session URL using the login role.
J2EE form-based authentication is only triggered for protected resources. We
define a protected resource by defining an appropriate security role, and
associating the resource with that security role. Only sessions that have that
security role will be allowed to access the resource.
Deploy form-based authentication
1.
2.
3.
4.
5.
6.
7.
Select the web.xml resource.
Right-click and select Open With -> Deployment Descriptor.
Select the Pages tab — see Figure 5-66 on page 224.
Chose Form from the Authentication method selector.
Browse for the Login page, select loginForm.jsp, and click OK.
Browse for the Error page, select error.jsp, and click OK.
Save the modifications.
Notice in Figure 5-66 on page 224 that we now have two distinct deployments for
the /error.jsp page:
򐂰 The login-error-page.
򐂰 The Error Code 404 page for page not found.
These cannot both be correct! Semantically, our /error.jsp is a login-error-page.
The 404 error page is part of the original deployment descriptor, and it is an error.
During migration testing, an error like this can be very confusing — when a page
is not found, you are asked to correct your login? An appropriate new 404 error
page should be written and deployed. We did not make this correction.
Chapter 5. Migration examples
223
Figure 5-66 Deploy J2EE form-based authentication
Make the /session URL a protected resource
J2EE security is based on security roles. In general, security roles are defined by
application assemblers and mapped to various resources, including methods
and URLs. We defined a security role named login and mapped it to the /session
URL.
This task has three operations, all of which are performed under the Security tab
of the Web Deployment Descriptor editor:
1. Select the web.xml resource.
2. Right-click and select Open With -> Deployment Descriptor.
3. Select the Security tab — see Figure 5-66.
The three operations are.
1. Define the login security role.
2. Define a security constraint for the /session URL.
3. Authorize the login security role for the /session security constraint.
224
Migrating WebLogic Applications to WebSphere V5
Figure 5-67 shows how to define the login security role in the Security tab of the
Web Deployment Descriptor editor.
1. Make sure the Security Roles subtab has been selected at the top of this
page.
2. Click the Add button — (New Security Role) will be added to the list of
security roles.
3. Modify (New Security Role) to the name of our security role — that is, login.
4. Save the modifications.
Figure 5-67 Define the login security role
Figure 5-68 on page 226 shows how to define a security constraint that includes
the /session URL. This is also done in the Security tab of the Web Deployment
Descriptor editor, but it is performed under the Security Constraint subtab.
1. Select the Security Constraints subtab within the Security tab of the Web
Deployment Descriptor editor.
2. Click Add under the Security Constraints list.
– A new Security Constraint entry appears in the Security Constraints list.
– A new (New Web Resource Collection) entry appears in the Web
Resource Collections list.
3. Select the (New Web Resource Collection) entry and click Edit on the Web
Resource Collections list.
– The Web Resource Collections editor appears as shown in Figure 5-68 on
page 226.
4. Enter a name for this resource collection — we chose the name login
required.
5. Click Add next to the URL Patterns list.
Chapter 5. Migration examples
225
– (New URL pattern) appears in the list.
6. Select the (New URL pattern) entry and modify it to /session.
7. Click OK and save.
Figure 5-68 Define security constraint for /session URL
Finally, Figure 5-69 on page 227 shows how to add the login security role to the
authorization list for the newly created /session security constraint.
1. Make sure the Security Constraints subtab is still selected within the
Security tab of the Web Deployment Descriptor editor.
2. Select our login required Web Resource Collection.
226
Migrating WebLogic Applications to WebSphere V5
3. Click Edit for the Authorized Roles list — the Define Authorization Constraint
window appears as shown in Figure 5-69.
4. Check the box next to the login role.
5. Click OK and save the modifications.
Figure 5-69 Authorize login security role for a security constraint
Do WebSphere part of deployment
What we have done so far is portable to any J2EE 1.3 compliant server.
However, it is not sufficient to trigger authentication. Authentication is ultimately
done by the server, possibly with the help of the underlying operating system, so
Chapter 5. Migration examples
227
some sort of server-specific configuration is also needed. For the filters example,
running on the WebSphere Studio Application Developer test server, we will
need to do the following:
򐂰 Enable security for local operating system authentication.
If you run the filters application without enabling security, there will be no
attempt to authorize users, and all users will be able to access the /session
resource. Local operating system authentication means the user ID/password
service of the underlying operating system will be used. See IBM WebSphere
V5.0 Security Handbook, SG24-6573, for an example using an LDAP server.
򐂰 Map the login role to the AllAuthenticatedUsers special subject.
The login security role that we have defined must be bound to the real
authentication mechanism. WebSphere defines special subjects for this
purpose. Special subjects can be mapped to J2EE security roles. The
AllAuthenticatedUsers special subject will be used to map any authenticated
user to the login security role. If we enable security without providing this
mapping, authentication will be triggered, but access to the /session URL will
be denied to all users.
Enable WebSphere security
Figure 5-70 on page 229 shows how to enable security for the WebSphere
Studio Application Developer test server:
1. Select the server perspective.
2. Select the server configuration.
3. Right-click and select Open.
4. Select the Security tab.
5. Check the Enable security box.
6. Enter the user ID/password of an account with authentication privileges, for
example, the Windows 2000 Administrator account. WebSphere will use this
account to authenticate user ID/password data.
7. Save the modifications.
228
Migrating WebLogic Applications to WebSphere V5
Figure 5-70 Enable WebSphere security using local operating system authentication
As with many of the options in the server configuration editor, you can
accomplish the same thing by using the WebSphere Administrative Console. So
you could also enable security with the following steps:
1. Run the WebSphere Administrative Console — see 3.6.3, “Run the
Administrative Console in test server” on page 84.
2. Expand Security -> User Registries.
3. Select Local OS User Registry.
4. Enter the user ID and password for the authentication account.
5. Click OK — the Global Security page should appear.
6. Check the Enable box.
7. Scroll down and click OK.
8. Click the Save link at the top of the page.
9. Click the Save button.
Chapter 5. Migration examples
229
Map login security role
The login security role is mapped to the AllAuthenticatedUsers special subject in
the Security tab of the Application Deployment Descriptor:
1. Select the application.xml file.
2. Right-click and select Open With -> Deployment Descriptor Editor.
3. Select the Security tab — see Figure 5-71.
4. Click the Gather button — the login security role should appear.
5. Select the login security role.
6. Check the All authenticated users box under WebSphere Bindings.
7. Save the modifications.
This mapping is stored in the application.xml and ibm-application-bnd.xmi files.
Figure 5-71 Bind All authenticated users to the login security role
Test J2EE form-based authentication
We ran the same test sequence described in “Test run” on page 216. The
browser pages look the same. The only difference is that you must enter a valid
operating system user ID/password on the authentication page. We changed the
text of the authentication page to reflect its portable J2EE nature. See
Figure 5-73 on page 234. The login-error page is activated now for an invalid
user ID/password, and you cannot access the /session resource without proper
authentication.
230
Migrating WebLogic Applications to WebSphere V5
The trace output in Example 5-22 provides a better understanding of the
differences introduced by using J2EE form-based authentication. Compare it with
the original trace in Example 5-21 on page 220.
򐂰 Authentication is now done before the first invocation of loginFilter. Notice
where /loginForm.jsp is initialized. The filters are not even initialized until after
a successful authentication.
򐂰 The loginFilter always performs its filter chain invocation.
򐂰 Otherwise, filter chaining is the same as before.
By comparison, this is a cleaner design.
򐂰 Authentication occurs before application code is executed.
򐂰 There is no need for the error-prone sharing of the authenticated session
variable between loginFilter, and the authenticate.jsp, loginForm.jsp, and
error.jsp pages.
Example 5-22 Filters trace with J2EE form-based authentication [edited, indented]
I
I
O
O
O
O
O
O
O
O
I
O
[FilterWeb.war] [/filterWebApp] [Servlet.LOG]: sessionServlet: init
[FilterWeb.war] [/filterWebApp] [Servlet.LOG]: /loginForm.jsp: init
[loginFilter]: loginFilter invoked ...
[logFilter]: logFilter invoked ...
[loginFilter] doFilter entered.
[loginFilter] before nested doFilter call.
[logFilter] doFilter entered.
[logFilter] before nested doFilter call.
[sessionServlet] doGet entered.
[logFilter] after nested doFilter call.
[FilterWeb.war] [/filterWebApp] [Servlet.LOG]:
[logFilter]Time to process servlet request /filterWebApp/session :
10millis
[loginFilter] after nested doFilter call.
5.4.5 Secure session tracking
Authentication depends on session tracking. The session object retains the
status of a user’s authentication. At least three different mechanisms are
commonly used for session tracking:
򐂰 Cookies.
򐂰 URL rewriting.
򐂰 SSL ID tracking.
Chapter 5. Migration examples
231
So far in the filters example, we have relied on the least sophisticated of these
techniques — that is, cookies.
򐂰 The cookie technique fails if the user’s browser does not cooperate.
򐂰 Protecting sensitive data, such as passwords, demands the more secure
technique of SSL ID tracking.
In this section, we convert the filters example, with its J2EE form-based
authentication, to use SSL ID session tracking.
Enable SSL ID session tracking
1. Start the WebSphere Administrative Console as described in 3.6.3, “Run the
Administrative Console in test server” on page 84.
2. Expand Servers and select Application Servers.
3. Select server1.
4. Scroll down and click Web Container.
5. Scroll down and click Session Management.
In short, click Servers -> Application Servers -> server1 -> Web Container
-> Session Management.
6. Check the Enable SSL ID tracking box — see Figure 5-72 on page 233.
7. Scroll down and click OK.
8. Click the Save link to apply changes to master configuration.
9. Click Save button.
10.Restart the test server for changes to take effect.
After making this change, we could not get back to the WebSphere
Administrative Console to turn off SSL ID session tracking. We just deleted the
server configuration after testing.
232
Migrating WebLogic Applications to WebSphere V5
Figure 5-72 Enable SSL ID session tracking
Filters example test using SSL ID session tracking
Before running the filters example using SSL ID session tracking, we had to
change the index.html link to use HTTPS:
򐂰 Changed href="/filterWebApp/session" to
href="https://localhost:9443/filterWebApp/session”.
In a real application, this would be the URL of your secure site. You would
also want to provide a security certificate for your secure site.
Figure 5-73 on page 234 and Figure 5-74 on page 235 show the authentication
and sessionServlet pages of the filters example using SSL ID session tracking.
򐂰 Both pages are using the secure HTTPS address, and the browser displays
the secure lock icon on the bottom line.
򐂰 The sessionServlet report verifies that cookies are not being used.
Chapter 5. Migration examples
233
The trace output is identical to the cookie-based version described in “Test J2EE
form-based authentication” on page 230.
Figure 5-73 Filters example authentication page using SSL ID session tracking
234
Migrating WebLogic Applications to WebSphere V5
Figure 5-74 Filters example sessionServlet page using SSL ID session tracking
5.4.6 Summary
We demonstrated use of the following WebSphere Studio Application Developer
tools and migration techniques:
򐂰 Source staging for a Web application.
򐂰 Deployment of Web filters.
Chapter 5. Migration examples
235
򐂰 Deployment of J2EE form-based authentication.
򐂰 Secure session tracking in WebSphere.
This example verified that the following new J2EE 1.3 features work as
advertised in WebSphere:
򐂰 Web filters.
򐂰 J2EE form-based authentication and its configuration in WebSphere, using
both cookies and SSL ID session tracking.
We discovered and solved the following migration problems present in the
original WebLogic example:
򐂰 J2EE 1.3 standards violations:
– Versioning problems on web.xml DOCTYPE header.
– Invalid syntax for filter descriptors in web.xml.
򐂰 Other portability or standards problems:
– Removal of WebLogic proprietary ServletAuthentication and conversion to
J2EE form-based authentication.
– Several HTML syntax errors.
236
Migrating WebLogic Applications to WebSphere V5
A
Appendix A.
Additional material
This Redpaper refers to additional material that can be downloaded from the
Internet as described below.
Locating the Web material
The Web material associated with this Redpaper is available in softcopy on the
Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/redp0448
Alternatively, you can go to the IBM Redbooks Web site at:
ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with
the redbook form number, redp0448.
Using the Web material
The additional Web material that accompanies this Redpaper includes the
following files:
File name
redp0448.zip
© Copyright IBM Corp. 2003. All rights reserved.
Description
Zipped Code Samples
237
System requirements for downloading the Web material
The following system configuration is recommended:
Hard disk space:
Operating System:
3 MB minimum
Windows
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.
238
Migrating WebLogic Applications to WebSphere V5
Abbreviations and acronyms
API
Application Programming
Interface
JNDI
Java Naming and Directory
Interface
BMP
Bean-Managed Persistence
JNLP
CMP
Container-Managed
Persistence
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
MDB
Message-Driven Bean
EJB
Enterprise JavaBean
RMI
Remote Method Invocation
EJB-QL
EJB Query Language
RMIC
RMI Compiler
ENC
Environment Naming Context
WLQL
WebLogic Query Language
HTML
HyperText Markup Language
XMI
XML Metadata Interchange
HTTP
HyperText Transfer Protocol
XML
eXtensible Markup Language
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. 2003. All rights reserved.
239
240
Migrating WebLogic Applications to WebSphere V5
Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this Redpaper.
IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks”
on page 242.
򐂰 Migrating WebLogic Applications to WebSphere Advanced Edition V4,
SG24-6179
򐂰 WebSphere V3.5 Handbook, SG24-6161
򐂰 WebSphere Version 4 Application Development Handbook, SG24-6134
򐂰 IBM WebSphere V4.0 Advanced Edition Handbook, SG24-6176
򐂰 IBM WebSphere V5.0 Security Handbook , SG24-6573
Referenced Web sites
These Web sites are also relevant as further information sources:
򐂰 was40utils download from ejbinfo.com
http://www.ejbinfo.com/FTP/was40utils.zip
򐂰 XML DTD for the J2EE 1.3 application client deployment descriptor
http://java.sun.com/dtd/application-client_1_3.dtd
򐂰 The Weblogic2WebSphere (WL2WAS) migration tool
http://www7b.software.ibm.com/wsdd/zones/studio/wl2was.html
򐂰 XDoclet Javadoc tool
http://xdoclet.sourceforge.net
򐂰 Cacheon home page
http://www.cacheon.com
򐂰 WebSphere InfoCenter
http://www-3.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter
© Copyright IBM Corp. 2003. All rights reserved.
241
򐂰 XML DTD for the J2EE 1.3 Web application deployment descriptor
http://java.sun.com/j2ee/dtds/web-app_2_2.dtd
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.
242
Migrating WebLogic Applications to WebSphere V5
Index
A
AAT 21, 89
adaptable 2
Application Assembly Tool
See AAT
application client 29, 34, 150
container 117
main class 40
application.xml 29, 38
application-client.xml 39
automation 93
B
baseline 100
best practices 2
C
Cacheon Migrator 95
cascade delete 12
checkpoints
WebSphere Studio Application Developer 29
ClearCase 9
CMP 10, 12, 23, 113, 126, 166
deployment 57
CMP connection factory 113, 143
CMR 7, 10–12, 68, 126
Container managed relationships
See CMR
CORBA 105
CVS 9
D
DADX 10
data mapping 122
database 123, 162
DataSource 58, 74
DB2 8, 22, 162
installation 25
deployment 145
code 145
deployment descriptors 8, 38, 55
editors 67
© Copyright IBM Corp. 2003. All rights reserved.
extended 8
migrate 8
Web editor 67
deployment MDB 174
DOCTYPE 111
E
EAR 101
Eclipse 21
EJB 6
2.0 specification 11
container 117
deployment 142
local interfaces 11
references 107, 115, 158
EJB home 59
EJB QL 7, 64, 124
EJB query language
See EJB QL
ejb-link 115
Embedded Messaging 8, 23, 176
Enterprise JavaBeans
See EJB
environment variables 122
events 7
examples 3, 10, 125–126
filters 10
JMS messaging 169
message 10
One2many 10, 126
One2many summary 168
exceptions 112
export 27
F
filters 7, 15, 111
finders 64
H
home interface 59
243
I
IIOP 105
import 27
InitialContext 120, 152
installation
DB2 25
EAR 86
tools 20
WebSphere Application Server 22
WebSphere Studio Application Developer 21
issues 97
client environment variables 122
client interfaces and stubs 121
client portability 117
CMP 2.0 122
construct valid EAR for import 101
data mapping 122
databases 123
DOCTYPE 111
EJB references 107
ejb-link 115
ejb-name 111
exceptions 112
filters 111
form base authentication 115
InitialContext 120
learning new tools 100
listener port 114
local interfaces 114
lookup of local EJBs 106
migration process 99
missing or incorrect artifacts 100
override of system library 103
PortableRemoteObject narrow 104
shared JARs 102
standards 98, 104
syntax errors 110
t3 119
WebLogic QL 124
J
J2EE 2–3, 5, 34
1.3 features 112
form-based authentication 10, 16, 115
standards 6
J2EE Connector Architecture 7
J2SE 6
JAAS 6–7
244
JAF 7
JAR 38, 101
Java 2 Platform, Standard Edition
See J2SE
Java API for XML Parsing 7
Java Authentication and Authorization Service 6
Java Message Service 7
Java Naming and Directory Interface 7
Java Servlets 6
events 7
filters 7
Javadoc 43, 162
JavaMail 7
JavaServer Pages
See JSP
JAXP 7
JCA 7
JDBC 7, 25, 79
JDBC provider 79
JMS 7–8, 13, 113, 169
configure service 176
listener port 181, 189
queue 186, 189
topic connection factory 177
topic destination 179
JNDI 7, 11, 58–59, 107, 120, 143, 147
JSP 6
flush 7
iteration 7
tag library 7
try/catch 7
L
listener port 114, 181, 189
local beans 10–11
local interface 59
local interfaces 114
M
MDB 7, 10, 14, 23, 113, 169
deployment 174
Message-driven beans
See MDB
migration 2
examples 2, 10, 125
See also examples
issues 1, 3, 97
See also issues
Migrating WebLogic Applications to WebSphere V5
process 2–3, 98, 126
tools 2
P
pass by reference 11
PDE 9
perspectives 9
portable 2
PortableRemoteObject 11
PortableRemoteObject narrow 104, 156
process 126
Q
queue 186, 189
queue connection factory 191
R
RDB mapping 68, 144, 163
Redbooks Web site 242
Contact us x
remote interface 59
RMI-IIOP 7
S
source code 101
SQL 9
standards 6
stubs 158
T
t3 105, 119
tag library
standardization 7
validator 7
tools 3, 19, 100
automation 21, 93
installation 20
topic destination 179
U
UDDI 10
W
was40utils 94
Web container 117
Web services 8
web.xml 111
web-app_2_2 DTD 111
web-app_2_3 DTD 111
WebLogic QL 124
WebSphere Administrative Console 8, 21, 81, 176
launch 82
login 83
run in test server 84
WebSphere Application Server 8, 81
install EAR 86
installation 22
WebSphere Studio Application Developer 3, 8, 20,
101, 168
Application deployment descriptor editor 68
checkpoints 29
CMP 2.0 deployment 57
Configure JDBC provider 79
configure JMS 176
create DataSource 74
create new file 44
deployment descriptor editors 55
EJB projects 26
export 27
export application client 41
find replace 52
folder structure 26
import 27
import application client 35
installation 21
Java Browsing perspective 53
javadoc export 43
RDB mapping 68
Relationship editor 139
run WebSphere Administrative Console 84
server configuration 70
tasks 25
test server 20, 70
type hierarchy browser 48
Web deploment descriptor editor 67
wizards 9
WL2WAS 94
V
VisualAge for Java 53
X
XDoclet 95
Index
245
XML 10
XSL 9
246
Migrating WebLogic Applications to WebSphere V5
Back cover
Migrating WebLogic
Applications to
WebSphere V5
Understanding
migration issues and
preparing a
migration strategy
Guidelines for
writing portable
applications
Implementing a
migration
This Redpaper is a preliminary discussion of some of the
issues we expect that developers will encounter when
migrating Java 2 Platform, Enterprise Edition applications
from BEA WebLogic Server to WebSphere Application Server
V5.
The Redpaper builds on the work done in the IBM Redbook
Migrating WebLogic Applications to WebSphere Advanced
Edition V4, SG24-6179. We expect our readers to be familiar
with the contents of this redbook.
When we wrote this Redpaper we were using a beta version
of WebSphere Application Server V5, so we have tried to
identify only the major differences between WebLogic and
WebSphere, and to identify the areas that will have the
highest likelihood of providing migration challenges.
Our aim is to provide practical guidance to developers who
have to deploy existing WebLogic applications on WebSphere
and to discuss how to design and develop J2EE applications
that will be portable and adaptable.
®
Redpaper
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