Migrating WebLogic Applications to WebSphere V5 Front cover
by user
Comments
Transcript
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