Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Download Migrating WebLogic Applications to WebSphere Advanced Edition
Document related concepts
Transcript
Migrating WebLogic Applications to WebSphere Advanced Edition Understanding the migration issues and preparing a migration strategy Guidelines for writing portable applications Considerations for completing and implementing a migration Bill Moore Robert Janker Benjamin Papez Leigh Power Robert Watkins ibm.com/redbooks SG24-5956-00 International Technical Support Organization Migrating WebLogic Applications to WebSphere Advanced Edition January 2001 Take Note! Before using this information and the product it supports, be sure to read the general information in Appendix B, “Special notices” on page 237. First Edition (January 2001) This edition applies to Version 3.5 of WebSphere Application Server, Advanced Edition for use with Windows NT, Windows 2000 Server, and AIX. Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 678 P.O. Box 12195 Research Triangle Park, NC 27709-2195 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © Copyright International Business Machines Corporation 2001. All rights reserved. Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Chapter 1. Introduction . . . . . . . . . . . 1.1 Our objectives . . . . . . . . . . . . . . . 1.1.1 A practical migration guide . . . 1.1.2 More portable applications . . . 1.2 Our focus . . . . . . . . . . . . . . . . . . . . 1.2.1 Prerequisites . . . . . . . . . . . . . 1.2.2 J2EE application architecture . 1.3 Migration issues . . . . . . . . . . . . . . . 1.3.1 Types of migration issues . . . . 1.3.2 Use of examples. . . . . . . . . . . 1.3.3 Documenting migration issues 1.4 How to use this guide . . . . . . . . . . . 1.4.1 Analyze your application. . . . . 1.4.2 Incremental migration . . . . . . . 1.4.3 The basic process . . . . . . . . . 1.4.4 Plan for the future . . . . . . . . . . 1.5 Structure of this guide . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 . .2 . .2 . .2 . .3 . .3 . .4 . .6 . .7 . .8 . .9 . 10 . 11 . 11 . 13 . 14 . 15 Chapter 2. Features comparison and migration strategy 2.1 Covered versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 WebLogic Server . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.2 WebSphere Application Server, Advanced Edition . 2.2 Feature comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 Core J2EE feature levels . . . . . . . . . . . . . . . . . . . . 2.2.2 Other J2EE feature levels . . . . . . . . . . . . . . . . . . . . 2.2.3 Relevant WebLogic extensions. . . . . . . . . . . . . . . . 2.3 Reasons for migrating . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4 Migration strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.1 Big picture migration strategies . . . . . . . . . . . . . . . 2.4.2 Migrating J2EE-based applications . . . . . . . . . . . . . 2.5 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 . 17 . 17 . 18 . 19 . 19 . 21 . 23 . 26 . 26 . 26 . 27 . 30 Chapter 3. Configuration . . . . . . . . . . . . . . . 3.1 Platform . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1 Development machine . . . . . . . . . . . 3.1.2 WebLogic Server test configuration . 3.1.3 WebSphere test configuration. . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. . . . . . . . . . . . . . . . . 33 . 33 . 33 . 34 . 34 © Copyright IBM Corp. 2001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. iii iv 3.2 Setting up the development machine . . . . . . . . . . . . . . . . . . 3.2.1 Install JDK 1.2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.2 Install and configure IBM Universal Database 7.1 . . . . . 3.2.3 Install BEA WebLogic Server 5.1 . . . . . . . . . . . . . . . . . 3.2.4 Install WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.5 WebSphere configuration . . . . . . . . . . . . . . . . . . . . . . . 3.2.6 Database configuration. . . . . . . . . . . . . . . . . . . . . . . . . 3.2.7 Configuring IBM HTTP Server . . . . . . . . . . . . . . . . . . . 3.2.8 IBM WebSphere Studio 3.5 . . . . . . . . . . . . . . . . . . . . . 3.2.9 IBM VisualAge for Java, Enterprise Edition Version 3.5 3.2.10 Tomcat 3.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Setting up the WebLogic Server lab machine . . . . . . . . . . . . 3.4 Setting up the WebSphere lab machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 . 34 . 35 . 38 . 40 . 45 . 51 . 55 . 55 . 56 . 57 . 58 . 58 Chapter 4. Development tools . . . . . . . . . . . . . . . . . . . 4.1 IBM VisualAge for Java, Enterprise Edition . . . . . . . 4.1.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.2 Overview of useful VisualAge for Java features 4.1.3 WebSphere Test Environment . . . . . . . . . . . . . 4.1.4 EJB Development Environment . . . . . . . . . . . . 4.1.5 Persistence access builder . . . . . . . . . . . . . . . . 4.1.6 Apache Tomcat test environment . . . . . . . . . . . 4.1.7 BEA WebLogic Server Integration Kit . . . . . . . . 4.2 jetace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 WebSphere Studio and other JSP, HTML - Editors. . 4.4 Other tools and products . . . . . . . . . . . . . . . . . . . . . 4.4.1 J2EE Reference Implementation server . . . . . . 4.4.2 Converter and migration tools . . . . . . . . . . . . . . 4.4.3 Persistence mapping tools . . . . . . . . . . . . . . . . ..... ..... ..... ..... ..... ..... ..... ..... ..... ..... ..... ..... ..... ..... ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 . 59 . 60 . 62 . 65 . 71 . 78 . 78 . 80 . 81 . 82 . 83 . 83 . 83 . 84 Chapter 5. JavaServer Pages . . . . . . . . . . . . . . . . 5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Developing JSPs . . . . . . . . . . . . . . . . . . . . . . . 5.2.1 Tag libraries . . . . . . . . . . . . . . . . . . . . . . . 5.3 Deploying JSPs . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1 Deploying JSPs in WebLogic Server. . . . . 5.3.2 Deploying JSPs in WebSphere . . . . . . . . . 5.3.3 Parameter settings for JavaServer Pages. 5.3.4 Deploying JSPs in WebSphere . . . . . . . . . 5.3.5 Using tag libraries. . . . . . . . . . . . . . . . . . . 5.3.6 Securing JSPs . . . . . . . . . . . . . . . . . . . . . 5.4 Migrating JSP examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . 85 . . 85 . . 86 . . 87 . . 91 . . 91 . . 92 . . 92 . . 95 . . 98 . . 99 . 100 Migrating WebLogic Applications to WebSphere Advanced Edition .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . Chapter 6. Java Servlets . . . . . . . . . . . . . . . . . . . . . 6.1 Technology overview . . . . . . . . . . . . . . . . . . . . . . 6.2 Web application design . . . . . . . . . . . . . . . . . . . . 6.3 The importance of being a servlet . . . . . . . . . . . . 6.4 Migration examples . . . . . . . . . . . . . . . . . . . . . . . 6.5 Differences in implementation . . . . . . . . . . . . . . . 6.6 Deploying an unpackaged servlet In WebSphere . 6.6.1 Problems converting servlets . . . . . . . . . . . . 6.7 Migrating a J2EE Web application . . . . . . . . . . . . 6.7.1 Problems With converting Web applications . 6.8 Converting J2EE references . . . . . . . . . . . . . . . . . 6.9 Converting J2EE security . . . . . . . . . . . . . . . . . . . 6.9.1 Migrating the user database . . . . . . . . . . . . . 6.9.2 Changes required for security migration . . . . 6.10 Migrating htmlKona . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 . 109 . 110 . 112 . 112 . 113 . 114 . 116 . 118 . 119 . 120 . 122 . 122 . 123 . 125 Chapter 7. Enterprise JavaBeans . . . . . . . . . . . . . . . . . 7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 Major migration issues . . . . . . . . . . . . . . . . . . . . . . . . 7.2.1 Summary of recommendations . . . . . . . . . . . . . . 7.3 EJBException replaces RemoteException in EJBs . . . 7.3.1 Revert to RemoteException . . . . . . . . . . . . . . . . 7.3.2 Use unchecked EJBExceptionMigrate . . . . . . . . 7.3.3 EJBException subclasses. . . . . . . . . . . . . . . . . . 7.4 JNDI lookups expanded . . . . . . . . . . . . . . . . . . . . . . . 7.4.1 env-entry lookups . . . . . . . . . . . . . . . . . . . . . . . . 7.4.2 ejb-ref and resource-ref lookups . . . . . . . . . . . . . 7.5 Deployment descriptors replaced . . . . . . . . . . . . . . . . 7.6 Finders expanded to Collection . . . . . . . . . . . . . . . . . 7.6.1 Convert Collection Finder to Enumeration Finder 7.7 HomeHandle added . . . . . . . . . . . . . . . . . . . . . . . . . . 7.7.1 Use JNDI names in place of HomeHandles . . . . 7.8 CMP ejbCreate change . . . . . . . . . . . . . . . . . . . . . . . 7.8.1 Revert to the EJB 1.0 CMP ejbCreate rule . . . . . 7.8.2 Use inheritance from implementation objects . . . 7.9 Transaction changes . . . . . . . . . . . . . . . . . . . . . . . . . 7.10 Authentication method changes . . . . . . . . . . . . . . . . 7.10.1 Replace Principal with Identity . . . . . . . . . . . . . 7.11 Read-only EntityBeans . . . . . . . . . . . . . . . . . . . . . . . 7.11.1 Use read-only method attributes . . . . . . . . . . . . 7.12 Non-issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.12.1 Tightenings. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.12.2 Clarifications. . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 . 127 . 129 . 130 . 130 . 132 . 133 . 134 . 134 . 136 . 137 . 139 . 141 . 142 . 144 . 144 . 145 . 146 . 147 . 148 . 148 . 149 . 150 . 150 . 150 . 151 . 152 v Chapter 8. Database connectivity and persistence . . . . . . 8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.1 DataSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.2 Connection pools . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.3 Available drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.4 Distributed transactions . . . . . . . . . . . . . . . . . . . . . . 8.2.5 Summary: Writing portable JDBC applications . . . . . 8.3 jDriver (jdbcKona) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.4 dbKona . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.5 Business objects - persistence frameworks . . . . . . . . . . . 8.5.1 Container-managed persistence (CMP) entity beans 8.5.2 Bean-managed persistence (BMP) entity beans . . . . 8.5.3 TOPLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.5.4 Other persistence managers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 . 155 . 156 . 157 . 163 . 164 . 168 . 173 . 174 . 175 . 176 . 177 . 178 . 178 . 179 Chapter 9. Migration example: The Java Pet Store 9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.1 Why Java Pet Store? . . . . . . . . . . . . . . . . . . 9.2 Understand the application . . . . . . . . . . . . . . . . . . 9.2.1 Java Pet Store user interface . . . . . . . . . . . . 9.2.2 Java Pet Store implementation . . . . . . . . . . . 9.2.3 Java Pet Store architecture . . . . . . . . . . . . . 9.2.4 Java Pet Store database . . . . . . . . . . . . . . . 9.2.5 The migration plan . . . . . . . . . . . . . . . . . . . . 9.2.6 Migration strategy . . . . . . . . . . . . . . . . . . . . . 9.3 Migrating EJBs . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.1 Tools and techniques . . . . . . . . . . . . . . . . . . 9.3.2 Source changes . . . . . . . . . . . . . . . . . . . . . . 9.3.3 JNDI ENC changes. . . . . . . . . . . . . . . . . . . . 9.3.4 EJBException changes . . . . . . . . . . . . . . . . . 9.3.5 Principal/Identity changes. . . . . . . . . . . . . . . 9.3.6 Collection finder changes . . . . . . . . . . . . . . . 9.3.7 DB2 database support . . . . . . . . . . . . . . . . . 9.4 Java Pet Store deployment . . . . . . . . . . . . . . . . . 9.4.1 VisualAge for Java steps . . . . . . . . . . . . . . . 9.4.2 WebSphere steps . . . . . . . . . . . . . . . . . . . . . 9.4.3 Redeployment cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 . 181 . 181 . 182 . 183 . 184 . 188 . 190 . 193 . 194 . 195 . 196 . 198 . 200 . 205 . 206 . 207 . 208 . 208 . 210 . 218 . 232 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . Appendix A. Using the additional material . . . . . . . . . . . . . . . . . . . . . . 235 A.1 Locating the additional material on the Internet . . . . . . . . . . . . . . . . . . . 235 A.2 Using the Web material. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 A.2.1 System requirements for downloading the Web material . . . . . . . . 235 vi Migrating WebLogic Applications to WebSphere Advanced Edition A.2.2 How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Appendix B. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Appendix C. Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 C.1 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 C.2 IBM Redbooks collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 C.3 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 C.4 Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 IBM Redbooks fax order form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 IBM Redbooks review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 vii viii Migrating WebLogic Applications to WebSphere Advanced Edition Preface This redbook will help you plan the migration of an application developed for BEA WebLogic Server, so that the application will run on WebSphere Application Server, Advanced Edition. We explain the differences between the implementations of WebLogic and WebSphere, provide guidance to developers on how to deploy existing applications from WebLogic to WebSphere, and discuss how to design portable new applications that may be deployed on WebSphere or WebLogic. It is not our intention to provide a feature-by-feature comparison of WebLogic vs WebSphere, or to argue the relative merits of the products, but to produce practical technical advice for developers who have to migrate applications from WebLogic to WebSphere. The team that wrote this redbook This redbook was produced by a team of specialists from around the world working at the International Technical Support Organization Raleigh Center. Bill Moore is a WebSphere Specialist at the International Technical Support Organization, Raleigh Center. He writes extensively and teaches IBM classes on WebSphere and related topics. Before joining the ITSO, Bill was a Senior Aim Consultant at the IBM Transarc lab in Sydney, Australia. He has 16 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 the VisualAge family of application development tools, object-oriented programming and design, and e-business application development. Robert Janker is an I/T Specialist at HypoVereinsbank AG in Munich, Germany. He has seven years of experience in application development and I/T architecture. He holds a degree in computer science from Fachhochschule Muenchen. His areas of expertise center around middleware technologies. Benjamin Papez is a Senior System Architect at UNiQUARE Financial Solutions(formerly GENESiS Software & Consulting) based in Austria, where he has been involved in many successful large-scale projects. He acquired his current expertise during 10 years of application development and system architecture with a variety of operating, database and back-end systems, programming languages, and development tools. He has three years of experience in Java technology in relation to network computing architectures © Copyright IBM Corp. 2001 ix (J2EE, CORBA, e-business) and has good practical knowledge of VisualAge (Java and Smalltalk), WebSphere and WebLogic Server. 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. Robert Watkins is a Software Engineer in Australia. He has six years of experience in the IT industry, and two years within the J2EE enterprise computing field. He holds a degree in Computer Science from the Northern Territory University. His areas of expertise include J2EE design and development. Figure 1. The authors: Robert Watkins, Benjamin Papez, Robert Janker, Leigh Power, and Bill Moore Thanks to the following people for their invaluable contributions to this project: Margaret Ticknor Linda Robinson International Technical Support Organization, Raleigh Center Wayne Beaton IBM Toronto x Migrating WebLogic Applications to WebSphere Advanced Edition Adam Matz Jim Van Oosten Pete Schommer IBM Rochester Leigh Williamson IBM Austin Harald Murgas IBM Germany Roman Kharkovski IBM Pittsburgh Juergen Wakonig Senior System Architect, UNiQUARE Financial Solutions, Austria Ralf Pichler System Specialist, UNiQUARE Financial Solutions, Austria Comments welcome Your comments are important to us! We want our Redbooks to be as helpful as possible. Please send us your comments about this or other Redbooks in one of the following ways: • Fax the evaluation form found in “IBM Redbooks review” on page 255 to the fax number shown on the form. • Use the online evaluation form found at ibm.com/redbooks • Send your comments in an Internet note to [email protected] xi xii Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 1. Introduction In today’s high-end, Java-based, enterprise application server market, the two leading products are WebSphere Application Server, Advanced Edition from International Business Machines Corporation, and BEA WebLogic Server from BEA. Both of these products offer robust support for complex Web-based enterprise applications. Moreover, by adhering to Java standards, they offer a level of portability far beyond that attained by earlier transaction monitor technologies. In addition to exploiting the write-once feature of the Java language, these products closely adhere to the Java 2 Platform, Enterprise Edition (J2EE) specification and associated reference implementation from Sun Microsystems. J2EE promotes an architecture for building and deploying Web-based enterprise applications based, in part, on the following standards: • Java Development Kit (JDK) • JavaServer Pages (JSP) • Java Servlets • Enterprise JavaBeans • Java Database Connectivity (JDBC) • Java Naming and Directory Interface (JNDI) • HyperText Markup Language (HTML) • eXtensible Markup Language (XML) Portability and adaptability are key properties of enterprise applications. By adhering to the J2EE standard, application developers automatically gain a high degree of portability. Given the J2EE support in BEA WebLogic Server and WebSphere Application Server, Advanced Edition, it should be, at least in theory, a trivial task to take an application written for a WebLogic system, and move it over to run on a WebSphere system. In practice, however, there are various reasons why this migration can be non-trivial. As a practical guide, this book identifies the potential trouble spots in such a migration, and guides the reader through this migration task. One word of caution — although WebLogic supports J2EE, its use is optional. The primary focus of this book is on migrating J2EE-compliant applications to WebSphere. Common noncompliant features of WebLogic are also mentioned. © Copyright IBM Corp. 2001 1 1.1 Our objectives In this book, we present our findings on how to migrate J2EE enterprise applications from BEA WebLogic Server to WebSphere Application Server, Advanced Edition. We offer a practical guide on how to accomplish this task with the current release levels of these products — BEA WebLogic Server Version 5.1 and WebSphere Application Server, Advanced Edition Version 3.5. We identify the specific differences in these products that must be addressed during the migration task, and offer detailed solutions to these differences. We also offer guidance for the future. Since an enterprise application tends to have a very long life cycle, it is likely to be migrated again in the future. By relying on good design practice and standard system architectures, we outline how to reduce the effort of future migrations and general application upgrades. 1.1.1 A practical migration guide Our primary goal is a practical migration guide. To this end, we have cataloged a detailed list of migration issues that must be resolved during the migration process. To the extent that your application follows the standards for J2EE applications, migration issues are relatively easy to identify, describe, and resolve. In some cases, it is simply a matter of performing a similar step with slightly different tools. Other cases require minor source code changes. To the extent that your application exploits vendor-specific features, the migration effort can become more complex. The good news is that the majority of your application will require only minor changes, and possibly none at all. As a practical guide, we have attempted to be comprehensive, but not exhaustive. There are certainly applications that have subtle dependencies that we have not anticipated — these cases are obviously not covered. Our goal has been to include the major migration issues that we expect most clients will encounter. 1.1.2 More portable applications Our secondary goal is to encourage the production of more standard and more portable code. This topic is addressed when there is a clear trade-off in resolving a particular migration issue. We do not, however, intend to provide a general guide for best practices and portable code. 2 Migrating WebLogic Applications to WebSphere Advanced Edition Some migration issues are simple and straightforward to resolve. For these, you will find a single, simple recommendation. More complex migration issues can often be resolved in more than one way. When the easiest solution is not necessarily the best one, we outline the alternatives and make a recommendation. This recommendation is based on good practice and likely future system changes. By investing effort to make code more standard and portable, future migration and maintenance effort should be reduced. Ultimately, reducing the effort of future migration and maintenance requires the impossible skill of being able to tell the future. Fortunately, the Java and J2EE standards efforts provide guidance about future developments. Where appropriate, we encourage your current migration task to prepare for these likely future developments. In this context, you should also consider the likely evolution of your enterprise applications. 1.2 Our focus This book is narrowly focused on two specific products and is primarily intended for application developers. • Migration from BEA WebLogic Server 5.1 to WebSphere Application Server, Advanced Edition 3.5. • As stated already, this is not a general-purpose migration guide. It is focused on the task of migrating J2EE and other Java applications from WebLogic to WebSphere. J2EE issues form the core of our migration recommendations, but common non-J2EE components are also covered. Given the rapid pace with which these server products and associated specifications change, we expect this guide to be of practical value for a relatively short period of time. It may, however, have some value for other more general migration tasks. • Targeted at application developers and system administrators. We assume that our audience is familiar with the specifications and tools used to build J2EE applications. That is, they are primarily Java application developers and application server system administrators. This guide may also be useful for other technical professionals who wish to evaluate, plan, and manage migration projects in the near future. 1.2.1 Prerequisites We assume that the reader is familiar with the relevant Java and J2EE specifications. This does not mean that you have to know all the subtle details of these specifications; a general familiarity is all that is required. We point out any special details that you need to know. Chapter 1. Introduction 3 These specifications correspond roughly to chapters in this book. If you are not familiar with a particular specification, you may choose to skip that chapter. We also assume the reader is familiar with the BEA WebLogic Server 5.1 product, but less familiar with the WebSphere Application Server, Advanced Edition 3.5 product and associated development tools. We do not provide tutorials for the use of these products. Instead, we document how we used the tools and identify problems that we experienced during migration exercises. 1.2.2 J2EE application architecture Although the term enterprise application covers a broad spectrum of architectural possibilities, we focused our attention on the general Web-based e-business architecture depicted in Figure 2 on page 5. This is the style of architecture recommended by the J2EE specification and vendors of J2EE server products. Some of our recommendations may also benefit variations on this architecture. 4 Migrating WebLogic Applications to WebSphere Advanced Edition EAR WAR HTML Servlet JSP JAR EJB Home Remote J2EE Application Server Client Tier 1 Browser Applet Deployment Tools Web Container HTML/XML Enterprise Info Tier 4 2 JDBC DataSource Tag Lib JSP Servlet R M I I I O P T r a n s a c t i o n EJB Container M o n i t o r Database System 3 Legacy Java Application RMI-IIOP Session Bean Entity Bean JDBC DataSource Lookup properties, resources, EJBs env Context JNDI DataSource Server EJB Home Figure 2. J2EE application server architecture This style of enterprise application has the following identifiable components: • A browser-based user interface using HTTP protocol. • A server-side front end that manages user sessions and translates HTTP requests into method calls on business objects in the enterprise server. Java Servlets and JavaServer Pages are used to implement this component in conjunction with a traditional Web server. Chapter 1. Introduction 5 • An object-oriented business logic server is implemented using Enterprise JavaBeans. The Enterprise JavaBeans are mapped onto the underlying database and legacy systems. • Multiple Enterprise JavaBeans servers may be interconnected, both locally or remotely, to form complex distributed object-oriented systems. These servers support distributed transactions to maintain data integrity across remote databases. • Java applications can also interact directly with the Enterprise JavaBeans server. • One or more firewalls are typically present for system security. By encouraging a general architecture for e-business applications, the J2EE approach promotes portability. The business logic is restricted to the Enterprise JavaBeans, while issues such as security, database mapping, transactions, load balancing, and communications are handled by the vendorprovided J2EE platform. Migrating from one vendor’s platform to another is reduced to migrating the business-provided Enterprise JavaBeans, Java Servlets, JavaServer Pages, and Web pages. Moreover, if these components have been written in a vendor-neutral way, it is possible to migrate one component at a time. For example, an underlying database can be migrated independently of the Enterprise JavaBeans that access it. 1.3 Migration issues The technical content of this guide is a set of migration issues specific to BEA WebLogic Server 5.1 and WebSphere Application Server, Advanced Edition3.5. Each migration issue describes a problem that you are likely to encounter during the migration of an application from WebLogic to WebSphere. For each problem, we provide one or more solutions designed to resolve the issue. In most cases, you will have to do one of the following things to get your application installed and running under WebSphere: • Make a change to the original WebLogic application. • Use a different process, or a different tool to get your application installed and running on WebSphere. We employed a combination of techniques to discover these migration issues: • Review and compare relevant product documentation and J2EE specifications. • Perform actual migrations of simple examples. 6 Migrating WebLogic Applications to WebSphere Advanced Edition The value of each technique depends largely on details of the kind of component being migrated. In some cases, the documentation was the most fruitful source of migration issues. For example, the Enterprise JavaBeans specifications provided most of the clues for Enterprise JavaBeans migration issues. This is because WebLogic 5.1 requires Enterprise JavaBeans 1.1, while WebSphere 3.5 requires Enterprise JavaBeans 1.0. A careful reading of the changes to the specifications provided most of the clues. In other cases, where documentation was minimal, we had to rely more heavily on experimentation and hands-on experience. An example of this is the way we discovered the differences in the way you define DataSource and JDBC driver objects for the two servers. Regardless of how a migration issue was discovered, we verified the issue and the solution by means of examples. Examples were run on both WebLogic and WebSphere servers. 1.3.1 Types of migration issues There are several possible causes of migration problems. From the viewpoint of just getting your code to run, these reasons may seem irrelevant. However, understanding the underlying reason for a change helps you choose the most appropriate solution. Here are some of the types of problems we found: • Application uses vendor-specific services. Although use of a vendor-specific service will generally lead to nonportable code, try to determine the deeper reason for its use. Some vendor-specific services provide proprietary features that may be critical to your application. In this case, you will probably have to do some redesign to obtain the desired result, possibly becoming dependent on another vendor’s services. We do not cover this case in general. Our recommendation is to use a standard service whenever possible so your application becomes more portable in the future. Older applications may be using vendor-specific services simply because that was the only service available when the application was written. As the J2EE specification evolves, some of these cases have become standardized. A migration project is a good time to upgrade to the newer specification. Since you will have to make a change anyway, why not move toward the current J2EE standard? • Application uses J2EE standards, but still contains non-portable code. It is possible to use the J2EE standard and still write non-portable code. For example, the JDBC APIs provide many opportunities to embed vendor-specific strings, for example, table names and database types. An Chapter 1. Introduction 7 EntityBean with bean managed persistence could therefore easily be nonportable. For this case, we may recommend the use of the Enterprise JavaBeans environment services in conjunction with more portable JDBC APIs. Use good judgment and good programming practice to make these decisions. • J2EE support is partial or differs between server products. The J2EE specification is a moving target and vendor support is bound to lag behind the latest standard. Although your application may be running on a J2EE-compliant server, loopholes in the J2EE implementation may expose migration issues. In some cases, the J2EE specification has been interpreted differently. Since it is difficult to predict these migration issues, we rely on experimentation to identify them. In these cases, we try to guide you in the direction of the latest J2EE specifications to avoid future problems. • Vendors support different versions of the J2EE specification. It is relatively easy to identify these migration issues by reviewing the relevant J2EE specifications. We are faced with the fact that the WebLogic 5.1 supports Enterprise JavaBeans 1.1 while WebSphere 3.5 supports Enterprise JavaBeans 1.0. This impacts both Java code and deployment descriptors. For each of these migration issues, we try to preserve as much of the Enterprise JavaBeans 1.1 code as possible, to facilitate future updates to Enterprise JavaBeans 1.1. These migration issues are generally localized and well-defined, making the use of automation attractive. • Vendors provide needed services that are not yet covered by the J2EE specification. The J2EE specification does not cover all situations. The J2EE 1.3 and Enterprise JavaBeans 2.0 draft specifications provide clues for future directions, but covering these specifications is beyond the scope of this guide. For now, you may simply have to ignore these portability issues. Instead, just focus on getting your application running on WebSphere Application Server, Advanced Edition. 1.3.2 Use of examples Given our limited resources and time schedule, we were not able to perform a realistic full-fledged migration. Instead we used small, focused examples geared to test particular language and tool features. In addition to these small examples, we used the Java Pet Store example available from Sun Microsystems. It is considerably larger and it is also well-known in the industry. These examples serve the following purposes: 8 Migrating WebLogic Applications to WebSphere Advanced Edition • Help uncover migration issues. In this book, we use small examples adapted from the WebLogic distribution. We also use short examples that we wrote ourselves. In general, we preferred to use existing examples rather than spend resources writing new ones. We have published most of the examples we used. If an example failed to uncover a migration issue, then it had served its purpose and was ignored. • Help resolve migration issues. Two versions of an example are needed — the before case and the after case. A comparison of the two highlights a solution to the migration issue. In some cases, we may develop multiple solutions for the same example. • Help document our recommendations. It is often easiest to understand a migration issue by examining the before and after code. You will see many short examples used for this purpose. Since these examples highlight detailed migration issues with specific J2EE components, they will be found in their respective chapters. - Chapter 5, “JavaServer Pages” on page 85 - Chapter 6, “Java Servlets” on page 109 - Chapter 7, “Enterprise JavaBeans” on page 127 - Chapter 8, “Database connectivity and persistence” on page 155 • Demonstrate a mini-migration effort. A migration effort is more than just resolving a set of migration issues. It is important to follow some sort of process. To this end, we have used the Java Pet Store example as a mini-migration project. Although this example only exercises some of the identified migration issues, it demonstrates a complete migration process for a non-trivial application. Moreover, this example was designed to be a highly portable J2EE application. Our minimigration project is documented in Chapter 9, “Migration example: The Java Pet Store” on page 181. Of course, being a very small project, we do not address important process issues such as planning, risk assessment, scheduling, and quality control. 1.3.3 Documenting migration issues In general, you want to know the following sorts of things about any particular migration issue: • Do you have the problem? Chapter 1. Introduction 9 You need an easy way to determine if your application has the problem. Some issues apply to most applications. Conversion of Enterprise JavaBeans deployment descriptors is an example of this. Other issues are seen rarely and will not be a problem for most applications. The presence of a particular class name may be the clue for such an issue. • Why is it a problem? You need some background information on why this problem exists. This may be an elaboration on the items listed in 1.3.1, “Types of migration issues” on page 7. For example, the definition for EJBException changed between Versions 1.0 and 1.1 of the Enterprise JavaBeans specification. • Can you ignore the problem? What happens if you do not address this issue? The answer to this question may be anything from nothing to your application will not compile. If an issue can be ignored, this is the place to describe why you might want to address the issue anyway. • Show an example of the problem. This may be a small piece of code or an option on a menu that has changed. An example should be included only if it helps understand the solution. • Show an example of the solution. Again, either code or a command option may be sufficient. If there are alternative solutions, this is the place to mention the trade-offs and make a recommendation. Where appropriate, we have documented migration issues according to this prescription. 1.4 How to use this guide The primary technical content of this guide is a set of migration issues. Each issue identifies a problem you may encounter, and a solution that you may need in a real migration effort. This is a good start, but by itself, it is not enough for a complete migration effort. You should also consider the migration process itself. 1.3, “Migration issues” on page 6 outlines the process we used to create this migration guide. This section describes how you can use our results to guide your own migration process. Since no single process works for any two projects, you must adapt this advice to suit your own situation. Large migration efforts are likely to need a more formal process while small efforts 10 Migrating WebLogic Applications to WebSphere Advanced Edition can do nicely with little or no formal process. In either case, the basic steps are the same. 1.4.1 Analyze your application First, you must understand the application you plan to migrate. This goes beyond just understanding the application domain and what the application is actually supposed to be doing. It also includes understanding technical details about: • The overall application software architecture • Its use of major tools, server components, databases, and third-party components • Implementation languages, APIs, and other dependencies of the various software components • What pieces will need to be changed, reconfigured, and redeployed into WebSphere Application Server, Advanced Edition This guide is intended to help with the details of migrating the J2EE-compliant pieces of your application -- that is, the last of the above bullets. If your application follows the J2EE architecture, understanding the other three bullets is straightforward. To the extent that your application depends heavily on non-J2EE APIs or services, or on vendor-specific components, this should be factored into your overall migration strategy. You may want to partition your migration to first make your application more compliant with J2EE, and then migrate from WebLogic to WebSphere. In particular, you should determine just how compliant your application is with the J2EE specification. It is possible to write an application in WebLogic that uses none of the J2EE APIs. Other than possibly helping you discover this fact, this guide will be of little immediate help in migrating an application that is completely non-compliant with the J2EE specification. If you do not know if your WebLogic application is J2EE compliant, take a quick look at Chapter 2, “Features comparison and migration strategy” on page 17 for some clues and general advice. 1.4.2 Incremental migration After understanding your application from the perspective of a J2EE migration, you are in a position to plan the migration itself. If you are dealing with a large, potentially high-risk migration, you should consider breaking up the migration into a sequence of smaller stages. This is even a good strategy for many small migrations. Any migration can be risky because of the potential for global effects from some of the changes. By proceeding in Chapter 1. Introduction 11 relatively small steps, you have better control over quality, and can more easily isolate unexpected problems. At the end of each stage you should have a stable, operational application whose behavior can be compared with the original application. Although each stage requires additional setup, and regression testing, this extra cost is generally worth the added benefits of better quality control and risk management. It is possible to partition a J2EE application in many different ways to accomplish an incremental migration. Indeed, this is one of the salient features of a component’s application. For example, you can select several Enterprise JavaBeans for migration now while leaving the others for a later time. Or you can choose to migrate your Enterprise JavaBeans now and Java Servlets later. 2.4, “Migration strategies” on page 26 outlines techniques to partition your application into more manageable migration pieces. It is even possible to migrate independent components in parallel. Just how you choose to partition your application depends on many factors. We mention a few. • Homogeneous changes. There is generally a benefit to making all of the same kinds of changes at one time. Practice makes perfect, and sometimes leads to efficiencies through automation. For example, consider migrating Java Servlets independently of Enterprise JavaBeans. • Application subcomponent. Identify major application subcomponents as potential independently migratable pieces. • Database migration. It is generally a good idea to do any necessary database migration independently of J2EE enterprise server migration. This is because database migrations are very likely to involve vendor-specific changes that have nothing to do with J2EE server differences. A database migration may be done either before or after the enterprise server migration. • Some redesign needed. Generally, the closer your code conforms to the J2EE standards, the easier it will be to migrate. Minor redesign is sometimes needed to get closer to the standard. For example, moving embedded vendor-specific strings to environment variables is a small but non-trivial design change. It is usually better to make these kinds of design changes before migrating the enterprise server. 12 Migrating WebLogic Applications to WebSphere Advanced Edition If more extensive application redesign is contemplated, you may prefer to do a quick and dirty migration first and address more serious redesign later. However, if the goal of the redesign is improved portability, it may pay to do it first. • Availability of source code. Unfortunately, the current state of the art frequently requires source code changes. Fortunately, this is becoming less of a problem over time. If your application uses third-party components, you may not have control over the source code. This can significantly impact a migration. Alternatives include rewriting code, obtaining upgrades, or deferring a portion of the migration. • Costs and priorities. Cost and priorities are always important. Maintaining licenses for multiple enterprise servers can be expensive. Business and resource considerations may dictate priorities. The good news is that a J2EE component’s application can be migrated piecemeal in a variety of ways. 1.4.3 The basic process Whether you have one or several migration stages, each stage of the migration will proceed through a variation of the following steps: • Assess the kinds of changes needed. Much of this will have been done earlier, but you will revisit this topic in detail when the migration actually begins. • Install the tools you need. The first time around, this will involve the installation of WebSphere Application Server, Advanced Edition 3.5 and associated tools. Since much of this will be new to you, make sure to allocate sufficient learning time. Based on our experience, we provide some helpful hints in Chapter 3, “Configuration” on page 33. • Establish a migration environment. Expanding a bit on the value of incremental migration, we recommend that you perform each migration stage in a non-production migration environment. This should be obvious, but deserves mentioning. This includes building small migration databases and networks. • Make required changes. Follow the guidance provided in the remainder of this book. It should cover most of the issues you will have to deal with. No doubt, you will also find a few of your own. Chapter 1. Introduction 13 • Verify migrated results. • Convert to production environment. 1.4.4 Plan for the future As a large application evolves, its original architecture tends to become obscured and outdated. Applications become brittle and harder to modify. A migration effort is an excellent opportunity to reassess your application’s architecture. Indeed, many of the issues addressed during a migration, point to the overall quality and flexibility of your architecture and design. An easy migration is a sign of a flexible design. A tutorial on modern e-business architectures and design guidelines is beyond the scope of the book. However, you are encouraged to take this opportunity to consider the future of your application in the light of industry standards and modern tools and practices. What you learn may well change the course of your current migration effort, making future upgrades proceed more smoothly. For example, taking the time to restructure your application into independent components can help with your current migration effort and the future scalability of your application. International Business Machines Corporation provides excellent source materials to help architect and design e-business application. For basic architectural advice, look at the IBM Application Framework for e-business at http://www.ibm.com/software/ebusiness. This work closely parallels the J2EE architectural work. For more in-depth advice on application design within the IBM Application Framework for e-business, take a look at the Patterns for ebusiness site http://www.ibm.com/software/developer/web/patterns/. 1.4.4.1 Framework for e-business The advent of e-business, with the requirement for interoperability that it brings, has been a major catalyst for the more rapid adoption of standards by the industry. The IBM Application Framework for e-business establishes: • A recommended approach for building systems. • Innovative technology delivered in a rich product portfolio. • Cross-platform standards, including Java and XML. The Framework, with the standards it proscribes for e-business systems and their components, can be applied to: • Custom application code • Application packages • Software products 14 Migrating WebLogic Applications to WebSphere Advanced Edition 1.4.4.2 Patterns for e-business The Patterns for e-business are an integral part of the IBM Application Framework for e-business. The Patterns make it easy to apply the technologies, standards, and products of the Application Framework to provide an e-business solution.The Patterns for e-business describe different scenarios, such as Business-to-Business and User-to-Business, that result in different infrastructure requirements. These considerations, for example, affect the positioning of firewalls and the specific needs of Web application servers. The Patterns for e-business aim to communicate in a highly accessible fashion the business pattern, systems architecture (application and runtime topologies), product mappings, and guidelines required for different classes of applications. For the User-to-Business Patterns there is also an associated Pattern Development Kit, which provides sample application code to illustrate effective use of those patterns. The Patterns for e-business are published on IBM developerWorks, a portal for developers, located at: http://www.ibm.com/software/developer/web/patterns You can also register at this site for pattern-related updates, which will include the Pattern Development Kit for user-to-business when it is available. 1.5 Structure of this guide This guide has a chapter for each of the major technical areas that affect your migration effort. Each chapter contains specific migration advice and examples for its corresponding APIs and tools. • Chapter 2, “Features comparison and migration strategy” on page 17 This chapter contains details of the different tools and API specification levels supported by the BEA WebLogic Server and WebSphere Application Server, Advanced Edition servers. It sets the context for the chapters that address specific APIs. It also provides details on how to partition your application for incremental migration. • Chapter 3, “Configuration” on page 33 This is where we document how we set up our migration environment for BEA WebLogic Server and WebSphere Application Server, Advanced Edition. • Chapter 4, “Development tools” on page 59 Chapter 1. Introduction 15 BEA WebLogic Server and WebSphere Application Server, Advanced Edition rely on different tools sets. This chapter explains what we learned about these tools and how we used them in our migration examples. • Chapter 5, “JavaServer Pages” on page 85 • Chapter 6, “Java Servlets” on page 109 • Chapter 7, “Enterprise JavaBeans” on page 127 • Chapter 8, “Database connectivity and persistence” on page 155 • Chapter 9, “Migration example: The Java Pet Store” on page 181 This chapter brings it all together with a complete mini-migration example of the Java Pet Store. We follow our own migration process to migrate this application to WebSphere. In the process we have to deal with many of the common migration issues described elsewhere in this guide. 16 Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 2. Features comparison and migration strategy In this chapter we give a brief outline of the features of BEA WebLogic Server and of WebSphere Application Server, Advanced Edition. We then discuss a strategy for migrating applications from WebLogic to WebSphere. 2.1 Covered versions This book deals with issues in migrating Java 2 Platform, Enterprise Edition (J2EE) applications (possibly with extensions) from WebLogic Server 5.1 (Service Pack 6) to WebSphere 3.5 (Fix Pack 2), using Sun’s JDK 1.2.2 Specification level. 2.1.1 WebLogic Server WebLogic Server started life as the Tengah Application Server. It was acquired by BEA Systems, and renamed to WebLogic Server. As of Version 3.1, it has been adopting many aspects of the various specifications that comprise Sun’s Java 2 Platform, Enterprise Edition, largely by converting existing services provided by WebLogic Server to conform with the appropriate J2EE specification. For example, the dynamic Web page technology implemented in WebLogic Server 3.1, known as JHTML, evolved to conform to the JavaServer Pages specification. WebLogic Server 5.1 is a J2EE-based server, but not yet a fully J2EEcompliant server. It does not fully implement all of the J2EE specifications, but it does provide support for most of them. In addition, it has a rich API of its own, which provides additional functionality not covered by the J2EE specifications. WebLogic Server should not be confused with WebLogic Enterprise. WebLogic Enterprise is a separate product, with a very different feature set. A Java-based server, WebLogic Server is available on many platforms. In its current version, it supports Java 1.1 through to Java 1.3 (not all features are fully available in Java 1.1). For further information about WebLogic Server, visit the BEA WebLogic Server 5.1 Documentation Center, at http://www.weblogic.com/docs51/ resources.html. © Copyright IBM Corp. 2001 17 2.1.2 WebSphere Application Server, Advanced Edition WebSphere Application Server, Advanced Edition is one of the foundation products in the IBM WebSphere software platform, which is shown in Figure 3. WebSphere Application Server, Advanced Edition is an extension to WebSphere Application Server, Standard Edition and adds support for Enterprise JavaBeans, enhanced security management and distributed processing. The Standard Edition provides support for JavaServer Pages, Java Servlets, JDBC Connection Pooling, and more. WebSphere Software Platform B2C B2E Process Automation e-Markets B2B WebSphere Commerce Suite WebSphere Homepage Builder VisualAge for Java Versata Studio Lotus Domino WebSphere Studio WebSphere Transcoding Publisher WebSphere Business Components WebSphere WebSphere Voice Server Personalization VisualAge Generator WebSphere Portal Server WebSphere B2B Integrator MQSeries Workflow WebSphere Everyplace Suite Web Content Management WebSphere Site Analyzer WebSphere Edge Server MQSeries Integrator Tivoli Policy Director WebSphere Host Integration i2 Ariba Siebel Razorfish Extricity marchFIRST E&Y Macromedia Mercury Interactive Versant Rational WebSphere Application Servers MQSeries Red Hat Novell Caldera Figure 3. The WebSphere software platform WebSphere was developed by IBM in order to implement the Java Servlets 1.0 Specification, and the original focus of WebSphere was on providing servlet support. WebSphere has always been focused on the various Java APIs and specifications. 18 Migrating WebLogic Applications to WebSphere Advanced Edition WebSphere Application Server, Advanced Edition 3.5.2 is a J2EE-based server. However, it is not yet a J2EE-compliant server, as it does not fully implement the J2EE specifications. Support for most of various APIs is available, either as part of WebSphere, or through integrations with other IBM products (for example, MQSeries for Java Message Services). However, in some cases, the support is not for the current version of the specification. As an example, WebSphere only supports Enterprise JavaBeans V1.0, not the current version of V1.1. Historically, IBM has not been as rapid an adopter of the Java specifications as BEA, preferring to wait until the specifications have stabilized before releasing their implementations. However, IBM is fully committed to supporting the J2EE platform, and to making WebSphere the leading J2EE server. A mostly Java-based server, WebSphere Application Server, Advanced Edition is available on several platforms. It supports Java 1.2.2. For further information about WebSphere Application Server, Advanced Edition, visit the WebSphere Application Server Web site at http://www4.ibm.com/software/webservers/appserv/. 2.2 Feature comparison Below is a partial feature comparison of WebLogic Server 5.1 to WebSphere Application Server, Advanced Edition 3.5. It is not intended to be a complete comparison, but focuses on the technical differences, in terms of the J2EE specification levels, between the two products, with a view to migrating from WebLogic to WebSphere. The information used for this comparison was obtained from the public documentation that both BEA Systems and IBM provide for their respective products. 2.2.1 Core J2EE feature levels In this section we compare the core Java 2 Platform, Enterprise Edition feature levels supported by WebLogic and WebSphere. Table 1. Comparison of J2EE specification levels J2EE Feature WebLogic WebSphere Enterprise JavaBeans (EJB) 1.1 1.0+ JavaServer Pages (JSP) 1.1 1.1 Servlet and Web applications 2.2 2.2 Chapter 2. Features comparison and migration strategy 19 2.2.1.1 Differences for Enterprise JavaBeans The two major areas of difference for Enterprise JavaBeans revolve around the specification level difference and the differences in deployment. WebLogic Server fully supports the EJB 1.1 specification, with a beta available for EJB 2.0. For the purposes of this document, we will ignore the EJB 2.0 support, since it is not (at the time of writing) fully available. In addition to the specification support, WebLogic has some good extensions for Enterprise JavaBeans which are very valuable and widely used. WebSphere Application Server, Advanced Edition supports what it denotes as EJB 1.0+, indicating that it has full support for EJB 1.0, and has numerous extensions. A detailed synopsis of what changes were made between EJB 1.0 and EJB 1.1 is available in Appendix C: “Revision History” of the Enterprise JavaBeans Specification, V1.1 which is available from http://java.sun.com/products/ejb/ docs.html. While this focuses on efforts needed to upgrade existing EJBs, it also provides information on what rules were relaxed or tightened, allowing them to be used as a guide for devolving EJBs from the 1.1 Specification to the 1.0 Specification supported by WebSphere. In addition to the API changes, there are different deployment requirements. Although both WebLogic and WebSphere use XML-based deployment descriptors, they do so in different ways. WebLogic uses the EJB 1.1 style of having two descriptors, one for generic information, and one for the WebLogic-specific and localized information. WebSphere uses the EJB 1.0 style of having a single deployment descriptor, with localized information. Translating the deployment descriptors will form a large part of any migration project to move Enterprise JavaBeans from WebLogic to WebSphere. In addition to the task of moving from one format to another, there will be a need to translate WebLogic specific data (such as CMP-related information) into WebSphere. For further information on the differences between WebLogic and WebSphere, with regards to Enterprise JavaBeans, see Chapter 7, “Enterprise JavaBeans” on page 127. 20 Migrating WebLogic Applications to WebSphere Advanced Edition 2.2.1.2 Differences for JavaServer Pages Both WebLogic Server 5.1 and WebSphere Application Server, Advanced Edition 3.5.2, provide a complete implementation of the JavaServer Pages 1.1 Specification. Migrating JSPs from WebLogic to WebSphere is therefore a fairly painless task, consisting largely of configuring WebSphere to match the WebLogic settings. For further information on the differences between WebLogic and WebSphere, with regards to Java Server Pages, see Chapter 5, “JavaServer Pages” on page 85. 2.2.1.3 Differences for servlets Both WebLogic Server 5.1 and WebSphere Application Server, Advanced Edition 3.5.2 provide an implementation of the Java Servlets 2.2 Specification. Migrating Java Servlets from WebLogic to WebSphere is a fairly painless task, largely consisting of transferring the configuration used in WebLogic to WebSphere. However, WebSphere Application Server, Advanced Edition does not provide support for the J2EE Web application component of the Java Servlets 2.2 Specification. This is an optional part of the specification, and causes some difficulties. It is possible to import Web application archives, but there are some programmatic differences, especially in regards to the security API, and J2EE references. For further information on the differences between WebLogic and WebSphere, with regards to servlets and Web Applications, see Chapter 6, “Java Servlets” on page 109. 2.2.2 Other J2EE feature levels This section compares other Java 2 Platform, Enterprise Edition feature levels supported by WebLogic and WebSphere. Table 2. Other J2EE features J2EE Feature WebLogic Spec Level WebSphere Spec Level JDBC 2.0 2.0 JMS 1.0.1 JMS interface to MQ Series Full J2EE Specification Partial Partial Chapter 2. Features comparison and migration strategy 21 2.2.2.1 JDBC Both WebLogic Server and WebSphere Application Server, Advanced Edition provide support for JDBC 2.0. WebLogic ships with JDBC drivers for several databases, whereas WebSphere requires you to obtain the JDBC drivers appropriate for your database from the database vendor. As a rule, this requirement is not a problem, since most major database vendors provide JDBC drivers for their product (Microsoft, with SQL Server, is the major exception). For further information on the differences between WebLogic and WebSphere, with regards to JDBC and other persistence technologies, see Chapter 8, “Database connectivity and persistence” on page 155. 2.2.2.2 Java Message Service (JMS) WebLogic Server provides, as part of the base product, an implementation of the Java Message Service 1.0.1 API. However, it is not clear that the JMS implementation is a robust and scalable solution. WebSphere Application Server, Advanced Edition, by contrast, does not provide an implementation of JMS. However, if you have the IBM MQSeries messaging software (which sets the industry standard for messaging software), IBM provides a free plug-in that integrates MQSeries with WebSphere, providing full and robust JMS support to WebSphere-based applications. 2.2.2.3 Java 2 Platform, Enterprise Edition (J2EE) specification Neither WebLogic nor WebSphere fully support the J2EE 1.2 Specification. The main common area of non-compliance is the inability to deploy enterprise archives, also known as EAR files. This also has implications for deployment. In WebLogic, to deploy multiple applications that are not required to share resources (such as class files and configuration data) with each other (which is the goal of the enterprise archive), it is necessary to configure multiple servers. Each server would represent one enterprise application. In WebSphere, it is possible to create enterprise applications that are analogous to, but not identical to, the enterprise archives. Enterprise applications in WebSphere are an administrative tool. They allow groups of EJBs and Web resources to be administered collectively, but do not enforce the separation and demarcation represented in the J2EE 1.2 Specification. The other main difference between WebLogic and WebSphere has to do with the JNDI name space and with resources. 22 Migrating WebLogic Applications to WebSphere Advanced Edition As per the J2EE 1.2 Specification (and parts of the EJB 1.1 and Java Servlets 2.2 Specifications), in WebLogic, EJBs (and servlets and JSPs deployed as part of a Web application) can have resource references defined in their respective deployment descriptors. This allows the EJB developer to specify a local JNDI name for a resource (such as a JDBC DataSource or an EJB Home reference) confidently, while also allowing the deployer to assign JNDI names that suit its own particular requirements. The mapping from the developer-assigned local name to the deployer-assigned global name is handled in the deployment descriptor. Retrieving such a resource is a simple routine: javax.naming.Context ctx = new javax.naming.InitialContext(); Object homeObject = ctx.lookup(“java:comp/env/ejb/MyEjbHome”); MyEjbHome ejbHome = (MyEjbHome)javax.rmi.PortableRemoteObject.narrow(homeObject, MyEjbHome.class); The java:comp/env name space is set up by the WebLogic container, and is read-only. By contrast, WebSphere does not support this feature, even for the Web application part of the Java Servlets 2.2 Specification. One possible workaround is to have a JNDI prefix string that is maintained as an environment variable, or in a configuration file. javax.naming.Context ctx = new javax.naming.InitialContext(); Object homeObject = ctx.lookup(theJNDIPrefixString + “ejb/MyEjbHome”); MyEjbHome ejbHome = (MyEjbHome)javax.rmi.PortableRemoteObject.narrow(homeObject, MyEjbHome.class); This would allow the same code to work correctly under WebLogic and WebSphere, with the difference in the implementation being stored as metadata. (Retrieving the meta-data is not shown.) SInce a different JDBC prefix could be provided at any desired level of granularity, an overall effect equivalent to the java:comp/env name space is achieved. 2.2.3 Relevant WebLogic extensions Extensive use of non-standard API sets, such as the WebLogic extensions, is something guaranteed to make for problems during migration. It is beyond the scope of this document to provide explicit and detailed information on how to Chapter 2. Features comparison and migration strategy 23 solve these problems, but we will give some general background information to help you out. Table 3. Mapping of WebLogic extensions to WebSphere extensions WebLogic Feature WebSphere Feature COM Support None - available from third party Jolt for WebLogic CICS Support WebLogic Events None TOPLink For WebLogic TOPLink For WebSphere 2.2.3.1 How do I migrate COM support? The short answer is that you don’t. WebLogic Server has very good support for COM, and, depending on the nature of your application, it is possible that you have made extensive use of this. WebSphere Application Server, Advanced Edition, however, provides no direct support for COM. There are some high-quality COM-to-Java and Java-to-COM bridges out there. Two examples are JIntegra, by Linar Ltd, and the J2EE CAS COM Bridge, available from Sun Microsystems. If you have a need for Java/COM inter operability, we suggest that you investigate one of these. Having decided on the technology to use, you should then migrate to that technology while still running under WebLogic, before proceeding to migrate to WebSphere. 2.2.3.2 How do I migrate Jolt support? Jolt for WebLogic is a Java-based interface to BEA Tuxedo, a transaction processing system. Migrating from Jolt for WebLogic to another transaction processing system is not a trivial task. It may not even be required. If you are retaining a Tuxedo-based transaction processor, you will have to obtain a license for BEA Jolt, to allow you to retain the Java-based interface to Tuxedo. It is relatively simple to migrate from Jolt for WebLogic to Jolt, since it is essentially the same product. BEA Jolt is a pure Java-based product, and should work well within WebSphere. If you are not retaining BEA Tuxedo, you would be well-advised to replace your Jolt-dependent code with the appropriate API for your new transaction processor in parallel with the migration from WebLogic to WebSphere. This would allow you to avoid the unnecessary expense of purchasing a BEA Jolt license for a temporary solution. 24 Migrating WebLogic Applications to WebSphere Advanced Edition WebSphere Application Server, Advanced Edition provides similar integration to CICS, the IBM transaction processor that WebLogic Server offers with Jolt to connect to TUXEDO. The biggest problem with such a migration will, most likely, be migrating off Tuxedo to your new transaction processor. This will be a full-scale migration project in its own right, quite possibly much larger than the migration from WebLogic to WebSphere. 2.2.3.3 How do I migrate WebLogic Events? WebLogic Events is a hangover from the days when WebLogic Server did not support the J2EE specifications. It is being phased out in favor of Java Messaging Service (JMS). If your J2EE application makes use of WebLogic Events, we suggest that you bite the bullet and upgrade to Java Messaging Service. WebSphere Application Server, Advanced Edition does not support Java Messaging Service directly. However, it integrates very well with IBM MQSeries, to provide a full and flexible JMS implementation. 2.2.3.4 How do I migrate TOPLink for WebLogic? TOPLink for WebLogic is a tool to aid in mapping complex EJB data structures to relational databases, while allowing the ease-of-development permitted by Container-Managed Persistence techniques. It is a very popular third-party product used with WebLogic Server. It is currently sold by WebGain Inc. In October, 2000, WebGain announced that they intended to release TOPLink for WebSphere. The target release time was fourth quarter, 2000. At the time of writing, we were not able to evaluate this product for ourselves, so we can not comment on how easy or difficult it would be to migrate from TOPLink for WebLogic to TOPLink for WebSphere. For further information on TOPLink for WebSphere, consult WebGain’s Web site at http://www.webgain.com/. This is also covered in more detail in 8.5.3, “TOPLink” on page 178 2.2.3.5 How do I migrate this third-party API? In general, migrating a third-party API from WebLogic to WebSphere should be a simple procedure. All that should need to be done is modification of the classpath used for WebSphere. For information on how to do this, please consult the WebSphere administration documentation. Chapter 2. Features comparison and migration strategy 25 2.3 Reasons for migrating This book is intended as an aid in a migration process, from WebLogic Server to WebSphere Application Server, Advanced Edition. It is technically oriented around this task, and is not intended to be a marketing document. We assume that you have already made the decision to migrate your J2EE-based application from WebLogic to WebSphere. That said, it is worthwhile to review briefly common reasons for migrating, and then to discuss the migration strategy. Some of the more common reasons for migrating are: • Cost of server licenses. • Consolidation of existing servers into one. • Scalability. • The added value of the WebSphere family of products. • Political. • Ease of development, and integration with development tools. This is far from a comprehensive list, and in many cases more than one reason would apply. The key issue is to determine the reason why you are migrating, as this has an impact on the strategy you should follow during the migration process. 2.4 Migration strategies This section discusses a number of possible migration strategies that you should consider. 2.4.1 Big picture migration strategies Migration of a J2EE-based application would rarely take place in a vacuum. There would be likely to be other, perhaps even many, migration projects occurring, either in sequence or in parallel to the WebLogic to WebSphere migration. Some examples would be: • Moving from one database to another (for example, from Oracle 8i to DB2). • Changing the operating system or hardware platform (for example, from Microsoft Windows NT 4 on an Intel-based processor to Sun Solaris on a Sun Enterprise Server). • Re-designing the application to remove bottlenecks or add new features. • Moving from a fat client system to a Web-based thin client system. 26 Migrating WebLogic Applications to WebSphere Advanced Edition The most important piece of advice that we can give you for this sort of bigpicture migration is to take it one step at a time. Migration projects are large and complex, and it is important to reduce that complexity down to a manageable level. It is true that taking a piecemeal approach will generate more work (or seem to, at least). After all, if you migrate your database over, you’ll have to update the clients to that database, so why not migrate those clients (including the J2EE application) at the same time? The answer to this is that if you increase the complexity, you increase the chance of failure. The advantages of taking a slower piecemeal approach are manyfold. The bigger advantages are: • Reduced complexity. With each step being more focused, the tasks are simpler and more manageable. This dramatically increases the chances of success. • Earlier payback. If there is a serious bottleneck in your current system that you are trying to overcome, a piecemeal approach may assist you here, for immediate benefits. For example, if the application you are using has database-related performance problems, the database can be migrated first, giving an immediate performance improvement while the rest of the application system is migrated. Identifying exactly where in the big-picture migration the WebLogic-toWebSphere migration fits in is crucial to the success of the migration project. 2.4.2 Migrating J2EE-based applications Just as a big-picture migration is more likely to succeed if broken down into smaller steps, this is also true for a J2EE application. Although there are as many ways to break down a J2EE-based application as there are to build them, we will be focusing on the classic J2EE-based architecture, consisting of a Web tier comprised of servlets and JavaServer Pages, communicating to an application tier comprised of Enterprise JavaBeans. Chapter 2. Features comparison and migration strategy 27 1 Web Browser Servlet EJB Database . EJB JSP 2 3 Client Tier J2EE Layer Back End Figure 4. Decomposing a J2EE-based application The servlets and JSP pages can be migrated separately to the EJBs. The EJBs themselves can be migrated one step at a time, as well. J2EE application clients (as defined in the J2EE 1.2 Specification, Chapter 9) are ignored in this scenario, since neither WebLogic nor WebSphere implement support for application clients at this time. The strategy we chose in migrating our sample application was to migrate each of the Enterprise JavaBeans one at a time, starting with the foundation entity beans and working upwards. Having migrated the EJBs over, the Web tier was migrated over as a block, using WebSphere’s ability to convert WAR files. 2.4.2.1 Resolving JNDI names One problem with writing generic applications is locating resources in the JNDI name space. The developer needs to know the location of the desired resource, but, at the same time, the administrators of the system want the flexibility to name objects according to local policies, and to resolve naming conflicts. In the Enterprise JavaBeans 1.1 Specification, and the Web application portion of the Java Servlets 2.2 Specification, support is provided for resolving JNDI names indirectly, via mappings specified in the deployment descriptor. As an example, the deployment descriptor for an EJB could look like this: <session> <description>My EJB</description> 28 Migrating WebLogic Applications to WebSphere Advanced Edition <display-name>MyEJB</display-name> <ejb-name>MyEJB</ejb-name> <home>itso.examples.MyEJBHome</home> <remote>itso.examples.MyEJB</remote> <ejb-class>itso.examples.MyEJBImpl</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> <ejb-ref> <ejb-ref-name>ejb/MyOtherEJB</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>itso.examples.MyOtherEJBHome</home> <remote>itso.examples.MyOtherEJB</remote> </ejb-ref> </session> In order for the itso.examples.MyEJBImpl class to locate MyOtherEJB, it would perform a JNDI lookup similar to this: javax.naming.Context ctx = new javax.naming.InitialContext(); itso.exaples.MyOtherEJBHome otherEJBHome = (itso.examples.MyOtherEJBHome)javax.rmi.PortableRemoteObject.narrow(ctx.lo okup(“java:comp/env/ejb/MyOtherEJB”), itso.examples.MyOtherEJBHome.class); The mapping from the indirect reference of java:comp/env/ejb/MyOtherEJB would be defined by an ejb-link element, or by another deployment descriptor that is specific to the EJB container being used. In addition to EJB references, other items, such as DataSources and environment variables, can be bound indirectly in this fashion. However, for EJB 1.0 implementations, and servlets that are not deployed as part of a J2EE Web application, this feature does not exist. Instead, the absolute location must be used to retrieve values from the JNDI name space. One solution is to implement a helper class to perform the JNDI lookups. This would provide a possibility to map the java:comp/env JNDI names to absolute locations, possibly in a different server. For example, the following method performs a mapping so that all the EJB references are retrieved from a running WebLogic server, while other references are retrieved from a running WebSphere server. public java.lang.Object lookup(java.lang.String name) throws NamingException { String newName = name; Context ctx; if (name.startsWith(“java:/comp/env”)) { Chapter 2. Features comparison and migration strategy 29 newName = name.substring(“java:/comp/env”.length()); } if (name.startsWith(“java:/comp/env/ejb”)) { ctx = getWebLogicContext(); } else { ctx = getWebSphereContext(); } return ctx.lookup(newName); } Retrieving the WebSphere and WebLogic JNDI naming contexts is not shown, but is covered in their respective developer documentation. 2.4.2.2 Separate test system Do not try to migrate a J2EE-application, or any other application, that is fully in production. The development needs during migration conflict with the needs of a production system (mainly stability and reliability). We strongly recommend that you establish a separate copy of the application, running on its own servers and with its own database, and migrate that. As the migration process moves forward, you can then copy the migrated parts of the test system back to the production system as the situation warrants. 2.4.2.3 Use automated tests for verification In any migration project, it is vitally important that the system being migrated does not have any strange bugs introduced into it. We strongly recommended that, as part of the migration project, that you construct automated tests and run them regularly during the migration. These tests should confirm that the output of the application is still the same on the new platform, and verify that the behavior of the application has not altered. The ideal goal of a such a test suite is to be able to test each and every component of your system independently, and to test the integration between the components. 2.5 More information For more information about WebLogic, see http://www.bea.com/products/ weblogic/server/. For more information about WebSphere, see http://www.ibm.com/software/ webservers/appserv/ 30 Migrating WebLogic Applications to WebSphere Advanced Edition For more information about Java 2 Platform, Enterprise Edition, see http:// java.sun.com/j2ee/. There is a good informative comparison of WebLogic and WebSphere, along with other J2EE-based application servers, at http://www.theserverside.com. Chapter 2. Features comparison and migration strategy 31 32 Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 3. Configuration In this chapter we describe the installation and configuration of the products used to test the migration examples discussed in this redbook. We do not provide detailed documentation of how to do the base installation of all the products, but give you overview information about additional steps to the standard product installation. Our aim is to describe the development and test environments we used for migration, so that you will be able to reproduce our examples and to use this configuration as a basis for your own migration efforts. When writing this redbook we set up a development environment and a migration testing environment. For migration testing we set up two lab machines, one with WebLogic Server and the other with WebSphere Application Server, Advanced Edition. On our development workstations we installed both WebLogic and WebSphere. 3.1 Platform This section summarizes the configuration of our development and test environments. 3.1.1 Development machine We used the following environment: • PCs with Pentium III 700 MHz processors, 512 MB RAM and 20 GB HDD (2 GB C: partition and 18 GB D: partition) • Microsoft Windows NT 4.0 with SP6 • Netscape Communicator 4.7 and Microsoft Internet Explorer 5.0 We installed the following products: • Sun JDK 1.2.2 • IBM Universal Database Enterprise Edition 7.1 FP1 • BEA WebLogic Server 5.1 SP6 • IBM WebSphere Application Server 3.5, Advanced Edition PTF2 • IBM WebSphere Studio 3.5 FP1 • IBM VisualAge for Java, Enterprise Edition 3.5 • Tomcat 3.1 © Copyright IBM Corp. 2001 33 3.1.2 WebLogic Server test configuration We used the following environment: • PC with Pentium III 700 MHz processor, 512 MB RAM and 20 GB HDD (2 GB C: partition and 18 GB D: partition) • Microsoft Windows NT 4.0 with SP6 • Netscape Communicator 4.7 and Microsoft Internet Explorer 5.0 We installed the following products: • Sun JDK 1.2.2 • IBM Universal Database Enterprise Edition 7.1 FP1 • BEA WebLogic Server 5.1 SP6 3.1.3 WebSphere test configuration We used the following environment: • PC with Pentium III 700 MHz processor, 512 MB RAM and 20 GB HDD (2 GB C: partition and 18 GB D: partition) • Microsoft Windows NT 4.0 with SP6 • Netscape Communicator 4.7 and Microsoft Internet Explorer 5.0 We installed the following products: • IBM Universal Database Enterprise Edition 7.1 FP1 • IBM WebSphere Application Server 3.5, Advanced Edition PTF2 3.2 Setting up the development machine This section describes the installation and basic configuration of the desktop development machines. 3.2.1 Install JDK 1.2.2 We installed Sun JDK 1.2.2 for use with WebLogic Server. Sun JDK 1.2.2 is available at http://java.sun.com/products/jdk/1.2. We installed it manually using D:\JDK1.2.2 as the directory name. For use with WebSphere Application Server, Advanced Edition we used the IBM JDK that comes with the WebSphere 3.5 install. It was automatically installed with the WebSphere full installation option. So you have nothing to 34 Migrating WebLogic Applications to WebSphere Advanced Edition do here. The exact level was (you can test with “java -version” at a command prompt) Classic VM (J2RE 1.2.2 IBM build cn122-20000725a (JIT enabled: jitc)) Make sure that you use the same JDK. 3.2.2 Install and configure IBM Universal Database 7.1 1. Make sure that you have sufficient rights for the installation. As described in the installation documentation, you need a local administrator’s account with the following advanced user rights: - Act as part of the operating system - Create token object - Increase quotas - Replace a process level token 2. We installed UDB 7.1 with the typical installation options as shown in Figure 5. Figure 5. UDB installation option Chapter 3. Configuration 35 Without rebooting we added the latest fixpack (FP1). After rebooting, the window shown in Figure 6 should appear: Figure 6. DB2 welcome window 3. Now you should create the sample database. Just click Create Sample Database. 4. Open the DB2 Command Center and execute the script shown in Figure 7. 36 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 7. Script for testing DB2 installation If the list of projects appears, then the installation was successful. 5. We then created a new database with the DB2 Control Center. You can start the DB2 Control Center with Start->Programs->IBM DB2->Control Center. Select Database->Create->Database Using Wizard as shown in Figure 8. In the resulting window type the database name ITSO and and click Finish. The database ITSO is created. Chapter 3. Configuration 37 Figure 8. Create a new database For more information about IBM Universal Database, look at the product documentation and visit the IBM Universal Database Web site: http:// www.ibm.com/software/data/db2/udb/ 3.2.3 Install BEA WebLogic Server 5.1 1. Basic installation The basic installation is quite easy. You have only to choose an installation directory and nearly at the end of the installation you have to enter a system password. We installed WebLogic Server in the directory d:\weblogic . To get Service Pack 6 installed you have to do some things manually. This is described in the first readme file that comes with SP6. If WebLogic Server is not starting afterwards correctly, look if you changed both the JAVA_CLASSPATH and WEBLOGIC_CLASSPATH to the new JAR files that come with SP6. For the configuration of WebLogic Server you have to edit the weblogic.properties file. It is located in the weblogic root directory. If you 38 Migrating WebLogic Applications to WebSphere Advanced Edition need more information about the weblogic.properties file you should have a look at http://www.weblogic.com/docs51/admindocs/properties.html. More Information about WebLogic Server 5.1 is available at http:// www.weblogic.com/docs51/resources.html. 2. Database configuration To setup the database connection to DB2 you have to edit the WebLogic properties for setting the connection pool weblogic.jdbc.connectionPool.ITSOPool=\ url=jdbc:db2:ITSO,\ driver=COM.ibm.db2.jdbc.app.DB2Driver,\ initialCapacity=1,\ maxCapacity=2,\ capacityIncrement=1,\ props=user=administrator;password=password;server=localhost and the DataSource: weblogic.jdbc.DataSource.jdbc.ITSODB=ITSOPool To add an ACL for the connection pool: weblogic.allow.reserve.weblogic.jdbc.connectionPool.ITSOPool=everyon e To enable WebLogic Server finding all the necessary classes and resources for accessing DB2 you have to append the following directories to the JAVA_CLASSPATH and the WEBLOGIC_CLASSPATH in startWebLogic.cmd (we installed the DB2 Sqllib in d:\program files\sqllib): d:\program files\sqllib\Java\db2java.zip;d:\program files\sqllib\Java\sqlj.zip;d:\program files\sqllib\java\runtime.zip 3. JSP servlet configuration To enable WebLogic to serve JSPs configure a JSP servlet in the weblogic.properties file. Change the compileCommand to that directory where you installed the JDK (we assume D:\jdk1.2.2) and set the workingDir, it’s the directory where the compiled classes are put into. weblogic.httpd.register.*.jsp=\ weblogic.servlet.JSPServlet weblogic.httpd.initArgs.*.jsp=\ pageCheckSeconds=1,\ compileCommand=D:/jdk1.2.2/bin/javac.exe,\ workingDir=d:/weblogic/myserver/classfiles,\ verbose=true,\ keepgenerated=true 4. Start WebLogic Server. Chapter 3. Configuration 39 That is all you have to do to get our default WebLogic Server configuredn. You can now start WebLogic Server with the command d:\weblogic\startWebLogic.cmd. After a few seconds you should see a window similar to the one shown in Figure 9. Figure 9. Starting WebLogic Server The last line is important. Fri Nov 10 16:03:24 EST 2000:<I> <WebLogicServer> WebLogic Server started 5. Test WebLogic Server. Now you can open a browser and try the URL http://localhost:7001/ index.html. WebLogic Server uses 7001 as default HTTP port. Every HTTP request that uses port 7001 is directed to WebLogic Server. The browser should now show the WebLogic Server documentation and consult it for further information about WebLogic Server. 3.2.4 Install WebSphere In order to get an easy installation of WebSphere make sure, that DB2 is installed properly. For the installation follow these steps: 1. Base installation: a. Start installation. 40 Migrating WebLogic Applications to WebSphere Advanced Edition b. Choose Full Installation as shown in Figure 10. This includes the IBM HTTP Server, JDK1.2.2 and DB2-Configuration. Choosing Quick Installation would install InstantDB and that will not work properly with the samples we provide. Figure 10. WebSphere installation options c. In the Database Options Dialog, as shown in Figure 11, insert the correct DB2 user ID and password; otherwise WebSphere will not start. If you want to alter this information later you can edit <websphere>\appserver\bin\admin.config and change the dbUser and dbPassword fields. Chapter 3. Configuration 41 Figure 11. Setting up WebSphere data options Before rebooting the system as prompted, you can save time when you install PTF2 at this time. 2. Install PTF2. Note that the prompted WebSphere installation path is <websphere>\appserver and the WebServer's doc root is <IBM HTTP Server>\htdocs. Confirm all suggested upgrades. 3. Reboot the machine. The DB install script <websphere>\appserver\bin\createdb2.bat creates automatically the WAS Database in DB2 after rebooting. If this fails you can run the script manual. The wasdb2.log file shows the results. Now the installation of WebSphere is complete. 4. Test the installation. To test the installation start the Admin Server by clicking Programs -> IBM WebSphere -> Application Server V3.5 -> Start Admin Server or by clicking Control Panel -> Services. Set the Service Startup Type to Automatic if you don’t like to start it manually after rebooting. Now it is possible to start the WebSphere Administrative Console by clicking Programs -> IBM WebSphere -> Application Server V3.5 -> Start Administrators Console. This is shown in Figure 12. 42 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 12. WebSphere Administrative Console By expanding the Administrative Domain, you will find your machine name. This node includes the Default Server, as shown in Figure 13. If it is not started, you can start it through the context menu or the Start icon. Chapter 3. Configuration 43 Figure 13. Starting default host Now you can start a browser and try one of the example applications: http://localhost/WebSphereSamples/BeanScripting/BeanScripting_java.jsp If your installation was successful there should be the output shown in Figure 14. 44 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 14. Output of the Beanscripting JSP 3.2.5 WebSphere configuration 1. Create an application server We created the new application server ITSO Server with the following steps: a. From the administrative console select View->Topology. b. Expand the WebSphere Administrative Domain. c. Select your Node (your computer’s name). d. Select Create->Application Server from the context menu. e. Type ITSO Server as the Application Server Name and d:\itso as the working directory. See Figure 15 for an example. Chapter 3. Configuration 45 Figure 15. Create Application Server 2. Create an EJB container Next we added an EJB container to our new application server. Figure 16 shows the Create EJBContainer window. a. Select the ITSO Server. b. Click Create->EJBContainer from the context menu. c. As EJBContainer Name, type ITSO Container and click OK to create the new EJB Container. 46 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 16. Create EJB container 3. Create a servlet engine Next we created a servlet engine with values as shown in Figure 17. a. Select the ITSO Server. b. Click Create->Servlet Engine from the context menu. c. Type ITSO Servlet Engine as Servlet Engine Name. d. Select Servlet 2.2/JSP 1.1 Full Compliance Mode. e. Click OK to create the new servlet engine. Chapter 3. Configuration 47 Figure 17. Creating a servlet engine 4. Create a Web application In WebSphere terms, a Web application consists of JSPs and servlets. These components can be managed as a group. You can disable and enable them together, and assign security permission to the whole Web application or only parts of it. On the file level Web applications are separated from each other by setting a specific document root and classpath for every Web application. To create a Web application: a. Select Console->Tasks->Create a Web Application. See Figure 18 for an example. b. Type ITSO Web Application as the Web Application Name. c. Check Serve Servlets by Classname. d. Select Enable JSP 1.1. 48 Migrating WebLogic Applications to WebSphere Advanced Edition e. Click Next. Figure 18. Create Web application f. Select ITSO Servlet Engine as the parent servlet engine as shown in Figure 19. Chapter 3. Configuration 49 Figure 19. Choosing the servlet engine g. Click Next. h. Enter /itso as Web Application Web Path. i. Click Finish to create the Web application. See Figure 20 for an example. 50 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 20. Setting Web application Web path j. At this time you have to create subdirectories under the directory D:\WebSphere\AppServer\hosts\default_host\. Create a subdirectory \ITSO Web Application and in this subdirectory the two subdirectories \servlets and \web. 3.2.6 Database configuration 1. Introducing a new JDBC driver in the WebSphere runtime There are many different ways to configure new JDBC drivers and DataSources in WebSphere. You can use the the Java-based WebSphere Administrative Console, the browser-based XML Web Administration tool, or the XMLConfig utility. Instructions and information about how each of these tools can be used to fulfill these tasks can be found in the WebSphere InfoCenter. For the sake of demonstration we describe how we introduced the Cloudscape driver in the WebSphere runtime environment via the Java-based administrative console. a. Select the Type View and click the resource description JDBC Drivers. b. Click Create from the pop-up menu. c. Complete the Create a JDBC Driver window, as shown in Figure 21. Chapter 3. Configuration 51 Figure 21. Create a JDBC driver d. Enter any name in the Name entry field. We suggest that you use a name that indicates the database product you are using. For example, we used Cloudscape JDBC Driver. e. In the combobox Class Name enter or select the full package name of the Java class that implements the driver. Here we entered COM.cloudscape.core.JDBCDriver. f. In the URL prefix field, do not enter the whole URL to the required database as done in the WebSphere Test Environment. The URL prefix consists only of the protocol and the subprotocol, separated by a colon (“:”), such as jdbc:db2 or in our case jdbc:cloudscape. You have to use the subprotocol name that has been defined by the vendor of your JDBC driver (refer to the vendor documentation). To get the full URL, WebSphere automatically appends the database name of the DataSource, which will be configured in the next steps. g. The JTA Enabled combobox corresponds to the database type in the WebSphere Test Environment setup. If you want to perform distributed transactions (two-phase commit) via the driver, select True. Specify 52 Migrating WebLogic Applications to WebSphere Advanced Edition False if you don’t want to use the Java transaction services or the driver does not support them. h. After you have completed the fields, click OK. i. Now change to the Topology view and select the just created JDBC driver. Click the right mouse button and select Install. j. In the Install Driver panel select your server node, enter the JAR file containing your JDBC driver (or find it via Browse). When entered click Install. This will install the driver and add the location to the classpath. You do not have to set it on your own. 2. Creating a DataSource a. Next we have to configure the DataSource. Change back to the Type view and select the DataSources resource from the tree. b. Click the right mouse button and select Create from the pop-up menu. c. Complete the Create a DataSource panel: 1. The DataSource name is the logical name for the DataSource (“jdbc/” will be prepended automatically). 2. The database name is the name of the database or the DataSource. This name will be appended to the URL prefix configured with the JDBC driver. Be aware that the DataSource name and sometimes also the database name (on AIX,and Solaris) are case-sensitive. In both fields we used the name petStoreDB for our cloudscape test application. 3. From the driver combobox select the JDBC driver you want to use. We selected the Cloudscape JDBC driver we have just configured before. d. On completion click OK to create the DataSource. Now you should be able to use the new JDBC driver in the runtime WebSphere Application Server. In our case, the console messages displayed the following warnings: 10/31/00 5:40 PM : WARNING [m23caatk/Default Server]: CONM0002W: Unrecognized database or driver "COM.cloudscape.core.JDBCDriver"; using generic settings 10/31/00 5:40 PM : WARNING [m23caatk/Default Server]: CONM0002W: Unrecognized database or driver "DBMS:cloudscape"; using generic settings Despite these warnings we were able to successfully use the Cloudscape DataSource, but it is possible that other drivers will not be able to run the way you would like, with just the generic settings. Sometimes a driver Chapter 3. Configuration 53 vendor allows users to supply the properties in the database connection URL; other rare drivers require the attributes to be set only in the Properties object passed to the DriverManager.getConnection(url, prop) method. For instance the Weblogic JDBC/RMI driver, which is a Type 3 driver, needs such driver-specific properties on connection creation. 3. Configuring a JTA-enabled driver Next we installed the JTA enabled driver for IBM Universal Database Enterprise Edition 7.1. In order for this to work, UDB must first be configured to use JDBC 2.0. The steps to do this are: a. Stop the IBM WebSphere Application Server administrative service b. Stop any other processes that use db2java.zip c. Stop all DB2 services d. Run the batch file <db2home>/sqllib/java12/usejdbc2.bat e. Start the DB2 services again f. Configure DB2 to use the JTS as the TP monitor: • Start the Control Center. • Select the DB2 Instance that contains the database being enabled for JTA. • Right-click and choose Multisite Update -> Configure from the context menu item. • In the Configure Multisite Update Wizard activate the Use the TP monitor named below radio button and select JTS as the TP monitor from the combobox. • Click the Finish button. • Bind the necessary packages to the database. • Start the DB2 Command Line Processor window. • Enter the following commands, replacing <db2home> with the home directory, where you installed DB2 (for example, D:\Program Files) and replacing mydb2jta with the database name that you wish to enable for JTA: db2 db2 db2 db2 => => => => connect to mydb2jta bind <db2home>\bnd\@db2cli.lst bind <db2home>\bnd\@db2ubind.lst disconnect mydb2jta g. To configure the JDBC driver in WebSphere, follow step 1. on page 51 and specify the following settings: 54 Migrating WebLogic Applications to WebSphere Advanced Edition • Class name = COM.ibm.db2.jdbc.app.DB2Driver • URL prefix = jdbc:db2 • JTA enabled = True 3.2.7 Configuring IBM HTTP Server The installation of IBM HTTP Server is part of the WebSphere full installation. No special configuration was required for our migration environment. For more information about IBM HTTP Server, look at the documentation and visit the IBM HTTP Server site: http://www.ibm.com/software/webservers/httpservers/ 3.2.8 IBM WebSphere Studio 3.5 We installed WebSphere Studio 3.5 with fix pack 1. We used the installation options shown in Figure 22. Figure 22. WebSphere Studio installation For more information about IBM WebSphere Studio, refer to 4.3, “WebSphere Studio and other JSP, HTML - Editors” on page 82 and visit the IBM WebSphere Studio site: http://www.ibm.com/software/webservers/studio/. Chapter 3. Configuration 55 3.2.9 IBM VisualAge for Java, Enterprise Edition Version 3.5 We installed VisualAge for Java with the full installation option. For the location of our repository we selected local. As workspace owner we took our normal NT account. After finishing the installation we started VisualAge for Java and and added the extra features needed for our migration environment. To add these features: 1. From the VisualAge for Java workbench, select File -> QuickStart . 2. From the Quick Start window shown in Figure 23, select Features ->Add Feature. Figure 23. VisualAge Quick Start 3. Select the features shown in Figure 24. 56 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 24. VisualAge adding features For more information about using IBM VisualAge for Java, Enterprise Edition, refer to 4.1, “IBM VisualAge for Java, Enterprise Edition” on page 59 and visit the IBM VAJava site at: http://www.ibm.com/software/ad/vajava/ 3.2.10 Tomcat 3.1 At the time we wrote this redbook, WebSphere Application Server, Advanced Edition V3.5 supported Java Servlets 2.2 and JavaServer Pages 1.1, but the WebSphere test environment that is part of VisualAge for Java had support for Java Servlets 2.1 and JavaServer Pages 1.0. To overcome this Chapter 3. Configuration 57 incompatibilty we installed the Tomcat 3.1 reference implementation of Java Servlets 2.2 and JavaServer Pages 1.1, from the Apache Software Foundation, into VisualAge for Java. This was an interim solution that allowed us to test servlets and JSP within VisualAge for Java, but still deploy to WebSphere. For a detailed description of the installation process refer to 4.1.6, “Apache Tomcat test environment” on page 78. 3.3 Setting up the WebLogic Server lab machine For a description of setting up the following products, refer to 3.2, “Setting up the development machine” on page 34: • Sun JDK 1.2.2 • IBM Universal Database Enterprise Edition 7.1 FP1 • BEA WebLogic Server 5.1 SP6 3.4 Setting up the WebSphere lab machine For a description of setting up the following products, refer to 3.2, “Setting up the development machine” on page 34 • IBM Universal Database Enterprise Edition 7.1 FP1 • IBM WebSphere Application Server 3.5, Advanced Edition PTF2 (we did notconfigure the cloudscape database here) • IBM WebSphere Studio 3.5 FP1 • IBM VisualAge for Java, Enterprise Edition Version 3.5 • Tomcat 3.1 58 Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 4. Development tools This chapter is about the tools we used to support the migration of a WebLogic Server application to WebSphere Application Server, Advanced Edition. This chapter is not intended as a detailed guide to these development tools and we do not cover all details for the installation, configuration and handling of the tools. We coveronly the topics that are relevant to our migration activities. 4.1 IBM VisualAge for Java, Enterprise Edition VisualAge for Java is a fully featured Integrated Development Environment (IDE) for development of professional Java code. Some of the general features of VisualAge for Java are: • The accomplished Visual Composition Editor (GUI builder) • Source code browsers and editors with coding tools (formatting, automatic code completion, fix errors on save) • A collaborative team development environment based on a shared repository • Incremental compilation • A scrapbook to experiment with Java code fragments • A powerful integrated debugger, with object inspectors and the ability to set regular or conditional breakpoints Features of VisualAge for Java that make it particularly useful for application migration projects aimed towards the WebSphere Application Server, Advanced Edition are: • WebSphere Test Environment • JSP/Servlet Development Environment • EJB Development Environment • Persistence Access Builder These environments offer smart wizards, development environments (browsers, tools), execution environments (servlet engine, EJB server, Persistent Naming server) and code generators (EJB, access beans), deployment tools and special execution monitors (JSPs). One feature that we appreciated very much is the ability to change code instantly while debugging, without having to restart the server. This is useful © Copyright IBM Corp. 2001 59 and increases productivity, because it avoids server startup times. Another advantage of VisualAge for Java is the ability to simulate multiple virtual machine instances. The disadvantages of VisualAge for Java in comparison with similar tools is the rigid association with a specific JDK version and that you are not able to use different versions of the same package simultaneously. An example is XML parser versions. If the installed application server uses a particular XML parser version, you can’t use an XML parser based on a newer specification level for your own server applications at the same time. Different versions of packages, such as “org.xml.sax”, “org.w3c.dom” or within the BEA integration kit “com.sun.xml.parser”, cannot be in the workspace at the same time. If you need this for your migration project, you might have problems importing the code. The VisualAge virtual machine is relatively slow when compared to other JVMs, but it is designed to provide development and debugging abilities, and should not be used to test production performance. For more information on VisualAge for Java, see the IBM VisualAge for Java online help and the product Web site: • Online help: http://localhost:49213/vajdoc/vahwebx.exe/en_US/vj32/ Extract/0/index.htm • Product home page: http://www.ibm.com/software/ad/vajava/ 4.1.1 Installation We installed VisualAge for Java, Enterprise Edition Version 3.5 with the complete setup option, which installs all features to the repository. It was not necessary for our redbook team to centralize Java code development, so we installed VisualAge for Java with each team member using an individual local repository on their workstation. In a professional development project we recommend that you use the VisualAge team development environment and install the EMSRV repository server on that shared server. The steps to complete the configuration of VisualAge for Java are: 1. After finishing installation and rebooting the machine, start VisualAge for Java. 2. Enter your normal Windows NT logon as the network name of the Administrator, who will be the workspace owner. 3. At the Welcome window choose Go to the workbench. 60 Migrating WebLogic Applications to WebSphere Advanced Edition 4. A recommended practice is to exit from VisualAge for Java again and make a copy of your initial workspace file, which is the <VAJavaHome>\ide\program\ide.icx file. You may need it if you want to work with a different feature setup. For example, if you would like to work with other products or such features as the BEA WebLogic Server Integration Kit for VisualAge for Java, you may have to start with a fresh workspace file. If you keep a copy of your initial workspace file, you won’t need to run the whole installation process again. After you copied the file, you can start VisualAge for Java once more. To load the necessary features used for our project, we performed these steps: 1. Open the Quick Start panel either by pressing F2 or clicking File -> Quick Start. 2. Select Feature in the left pane and double-click the Add Feature command in the right pane. 3. Select the following features from the listto add them to the workspace (other dependent features will be loaded automatically): - IBM EJB Development Environment - IBM WebSphere Test Environment - Persistence Access Builder Now the setup is done and you should be ready to work with VisualAge for Java. At the time this book was written, IBM already offered fix pack 2, which enabled Java Servlets 2.2 and JSP 1.1 support for the WebSphere Application Server, Advanced Edition runtime. Since WebLogic also supports that implementation level, we installed the fix pack for WebSphere. Unfortunately the fix pack for the WebSphere Test Environment was not available at that time, so we could not test Java Servlets 2.2 and JSP 1.1based applications with the WebSphere Test Environment. We decided to use the already available Apache Tomcat test environment as our Java Servlets and JSP container. For more details about that interim solution refer to 4.1.6, “Apache Tomcat test environment” on page 78. An alternative used by our team was to import the new <WebSphereAppServer-home>\lib\servlet.jar file into VisualAge for Java. This file came with fix pack 2 for the WebSphere runtime and replaces the packages in the Servlet API Classes project within VisualAge for Java. A general instruction for importing JAR files can be found in the following section. Chapter 4. Development tools 61 4.1.2 Overview of useful VisualAge for Java features If you have installed the complete VisualAge for Java, Enterprise Edition V3.5 product you can see that VisualAge for Java offers a number of different features. Many are connectors to access data on a back-end system or to create beans that can access data from other applications or components (for example CORBA-IDE, C++, etc.). Figure 25 shows the features that are relevant to our migration project. These are the major components you will encounter when using VisualAge for Java to migrate or create J2EE-based applications. Weblogic_development VisualAge for Java Debugger Import Workbench Console Browsers/Editors sources.jar sources.jar classes classes.jar Webapp jsp html Export Copy WebSphere WebSphere Test Environment EJB Development Environment EJB Tools Persistency Tools JSP Execution Monitor Persistent Name Server Data Source Configuration Web Application EJB Server(s) Servlet Servlet EJBs Servlet Engine Servlet Access Servlet Beans Servlet Servlet Servlet DB2 ... Servlets IBMVJava ide project_res. ... myProject WTE hosts default_host default_app myWebApp servlets package Servlet Object Servlet Models Repository JSP JSP AppServer JSP Compiler CICS MQ web jsp html Other Figure 25. Overview of features in VisualAge for Java The main window in VisualAge for Java is the Workbench window. Here you can browse and edit all loaded projects, packages, resources, classes, and interfaces. You can also open a separate window to browse one project, one 62 Migrating WebLogic Applications to WebSphere Advanced Edition package, or one type (class or interface). New pages may be inserted into the Workbench notebook; for example when you load the EJB Development Environment, an EJB page will be added. The Managing page is used by the owner of packages or projects to work with the versioning tools provided by VisualAge. The All Problems page shows all current errors and warnings in the code. When you set a breakpoint in your source code, the Debugger window will appear as soon as the line of code is about to be executed. The Console displays standard output. The WebSphere Test Environment enables testing of J2EE-based server applications for the WebSphere Application Server, Advanced Edition. • A servlet engine runs the Java Servlets. • A JSP compiler compiles JSPs to Java Servlets and a JSP Execution Monitor supports debugging of JSPs. • The persistent name server is a JNDI naming server to bind the EJB home interfaces, DataSources, the UserTransaction object, etc. • The DataSource configuration is used to create connection pools to particular DataSources. The EJB Development Environment is used to create EJBs and map the entity beans to a persistent data store. EJBs can be grouped together and assigned to EJB servers, which would mimic the EJB container of WebSphere and run the EJB components. The Persistence Builder feature can be used to create finer grained object models, which could be used by the EJBs. VisualAge for Java provides features to access enterprise resources, such as related databases (via JDBC), CICS, MQSeries, IMS, SAP, and others. This is done with a Connector framework and DataSources. All the code is stored in a local (stand-alone) or central (team-development) repository and all editions are seamlessly saved and can be restored down to the method level. The editions can be versioned. VisualAge for Java interacts with the file system in that you can import and export source, class and resource files from and to the file system. In our case we would import files from a WebLogic development directory or JAR file, and export them to a WebSphere-related directory. Chapter 4. Development tools 63 In order to import the packages and files from a WebLogic application, you must create a project in VisualAge for Java, as follows: 1. Select the Projects page in the Workbench notebook. 2. Either use the tool bar button with the folder sign or choose Selected -> Add -> Project. 3. Enter an arbitrary name for your project and confirm by clicking Finish. To import the files from your WebLogic application: 1. Ensure that the project is selected in the All Projects tree. 2. Right-click to open the context menu, and select Import from the menu. 3. Choose whether you want to import your WebLogic application from a directory or from a JAR file. Click Next. 4. In the next panel you enter the name of the directory or JAR file and you choose which file types you want to import. Whenever you have *.java source files, import them; otherwise you can also import *.class files only. Resources will be copied into the <VAJava-home>\ide\project_resources directory under your specific project. If you enter a new project, it will be created for you. Click the Finish button to begin the import. We did this for the Java Pet Store V1.0.1 example that we downloaded from Sun’s Java site at: http:/java.sun.com/j2ee/download.html. A very good feature of VisualAge for Java is that you can immediately see how many code incompatibilities or errors you will have to fix to get the application running under the WebSphere Application Server, Advanced Edition. 1. Double-click your imported project (in our example: PetStore) in the All Projects container. 2. A new window opens, containing just the packages of your project. Now click the Problems tab and you will see all errors and warnings VisualAge for Java has encountered that will need to be resolved to get everything running in the WebSphere Test Environment. For example Figure 26 shows all the problems resulting from importing the Java Pet Store sample into VisualAge. 64 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 26. Problems overview of the PetStore project in VisualAge for Java 4.1.3 WebSphere Test Environment The WebSphere Test Environment (WTE) is a smooth integration of the WebSphere Application Server, Advanced Edition with the VisualAge for Java IDE. It provides support for developing, testing and debugging of Java Servlets, JavaServer Pages, Enterprise JavaBeans and other server components and classes. Unit tested components that run successfully in the WTE will also run successfully in a WebSphere Application Server, Advanced Edition production environment. Note, however, that the WTE does not contain the entire WebSphere Advanced runtime. The Differences page in the IBM VisualAge for Java online help lists all the differences between WebSphere Test Environment and WebSphere Application Server. Here is the URL: Chapter 4. Development tools 65 http://localhost:49213/vajdoc/vahwebx.exe/en_US/vj32/Extract/0/wte/ concepts/c5xdiffs.htm To test whether your server application will run on the WebSphere Application Server, Advanced Edition, we recommend using the WTE to track down any code problems. This will be faster and more efficient than only deploying code straight into the WebSphere runtime. To start the WTE in VisualAge for Java choose Workspace -> Tools -> WebSphere Test Environment. This will launch the WebSphere Test Environment Control Center window which allows you to start two servers, the servlet engine and the persistent name server. The Control Center also provides a way to configure the JSP monitor options and DataSources. Figure 27 shows the Control Center. Figure 27. WebSphere Test Environment Control Center with servlet engine configuration pane 4.1.3.1 Servlet engine and JSP Execution Monitor The WTE provides you with a servlet engine and a JSP Execution Monitor and allows you to use all available Java APIs, JavaBeans or EJBs. As already mentioned, the WTE does not support the same JSP and Java Servlets standard as the WebSphere runtime. That is why we didn’t use the Servlet and JSP features of the WTE, but rather we used an interim solution with the 66 Migrating WebLogic Applications to WebSphere Advanced Edition Apache Tomcat test environment described in 4.1.6, “Apache Tomcat test environment” on page 78. The features of the WebSphere Test Environment include: 1. Servlet engine If you are going to use the servlet engine feature launch the WebSphere servlet engine by invoking the servlet engine from the WebSphere Test Environment Control Center. More information about the servlet engine can be found in VisualAge for Java online help. 2. JSP Execution Monitor The JSP Execution Monitor is an efficient tool to simultaneously monitor the JSP source, the JSP-generated Java Servlets source, and the dynamically generated HTML content. You can see the mapping between the JSP and the associated Java source code, and it allows you to set breakpoints. Figure 28 shows an example of the JSP Execution Monitor in use. Figure 28. JSP Execution Monitor Chapter 4. Development tools 67 More information about the setup and the handling of this tool can be found in the VisualAge for Java online help at: http://localhost:49213/vajdoc/vahwebx.exe/en_US/vj32/Extract/0/jsp/ concepts/c5qjspem.htm Further details about using VisualAge for Java to write Java Servlets and JavaServer Pages can be found in the redbook Servlet and JSP Programming with IBM WebSphere Studio and VisualAge for Java, SG245755. 4.1.3.2 Persistent name server The persistent name server is the JNDI naming service in the WTE. The name server keeps the references to bound EJB home interfaces, registered DataSources, the UserTransaction interface implementation and any other objects bound to the name space. As the name implies the entries in the name space are persistent, so you do not have to add the DataSources at every server startup. The configuration from the last server shutdown is made persistent. The settings for the database of the configuration repository can be set in the WTE Control Center. Click Servers -> Persistent Name Server in the left pane and enter a database driver, database URL, database ID and password in the right pane (see Figure 29). Confirm the settings by clicking Apply. Figure 29. Persistent name server configuration in the WTE Control Center 68 Migrating WebLogic Applications to WebSphere Advanced Edition If you want to have the WebSphere Application Server, Advanced Edition runtime and the WTE persistent name server running at the same time, you will need to change the Bootstrap port. This can be done in the WTE Control Center, too. Both servers have port 900 as default. We changed the port in the development environment to 902. If you do this, then you need to change the PROVIDER_URL when creating the InitialContext. While the code is tested inside VisualAge for Java, you take iiop://localhost:902 and when the code runs outside in the real Application server, you have to take iiop://localhost:900. Starting and stopping of the persistent name server should be done via the WTE Control Center. Click Start Name Server or Stop Name Server on the right pane to do this. The server must be started before you start any EJB servers and before you configure or use any DataSources. 4.1.3.3 DataSource configuration A detailed discussion of DataSources can be found in 8.2.1, “DataSource” on page 157. To create or configure your DataSources In VisualAge for Java, use the WTE Control Center. Follow these steps to introduce a new DataSource: 1. Ensure that the persistent name server is started. 1. In the WebSphere Test Environment Control Center select the tree node DataSource Configuration from the tree on the left-hand side. 2. Click Add. 3. Complete the Add DataSource panel as shown in Figure 30. Chapter 4. Development tools 69 Figure 30. Adding a DataSource The DataSource name is the logical name for the DataSource (“jdbc/” will be prepended automatically). Select the driver from the list. If you want to introduce a new driver, refer to 8.2.3.1, “Introducing a JDBC driver in VisualAge for Java” on page 165. The syntax for the URL in the Database URL entry field is specific to the vendor of the JDBC driver (refer to their documentation). It is used to specify the location and name of the database in the database server. With the Database type combobox you can select whether the driver can handle Java-based two-phase commit transactions. If you are not performing distributed transactions select JDBC; if the driver can handle it, select JTA. The other fields are not relevant to our discussion. 4. Click OK to add the DataSource, but not until you check that everything was entered correctly (especially the DataSource name, which is casedependent, and the database URL). If you made a mistake, the system won’t allow you to update your confirmed DataSource settings at a later time. You will only be able to remove your settings and add a new DataSource. 70 Migrating WebLogic Applications to WebSphere Advanced Edition Before you can run and test your Java Servlets, JSPs or EJBs with the DataSource, you shouldn’t forget to add the external JAR file containing the JDBC driver to the classpath. As you may access the database from several processes (servlet engine, EJB servers, Tomcat server) the best practice is to modify the Workspace class path instead of modifying the class path of each server program. 1. In the Workbench select Window -> Options... 2. In the Options dialog, select Resources from the left tree view. 3. Insert the JAR file or the directory containing the JDBC driver class in the Workspace class path entry field either by typing or by clicking the Edit push button and the further navigation and selection aids. For our DB2 driver we added: D:\Program Files\sqllib\java\db2java.zip. Now you should be able to use the DataSource. 4.1.4 EJB Development Environment The EJB Development Environment is a specialized environment to develop and test EJBs that conform to the EJB component architecture 1.0 defined by Sun Microsystems. It supports some additions to the 1.0 standard which cover part of the functionality defined in the EJB 1.1 standard, and provides IBM enhancements to the EJB programming model (inheritance and associations), which foreshadow functions that will be introduced in the EJB 2.0 Specification. All EJB Development Environment tools are accessible from the EJB page in the Workbench. Figure 31 shows this page. Chapter 4. Development tools 71 Figure 31. EJB Development Environment in VisualAge for Java From here you are able to write and edit your business logic or import Enterprise JavaBeans from a JAR file. You can develop session beans, container-managed persistence (CMP) entity beans, and bean-managed persistence (BMP) entity beans. A SmartGuide (see Figure 32 on page 75) will automatically create the EJB home and remote interfaces and the bean class. You don’t need that for migration projects, since these classes will be taken over, but the same SmartGuide aids you in creating the deployment descriptor for WebSphere. In addition you can generate access beans that serve as JavaBean wrappers for communicating with EJBs. Access beans hide the home and remote interfaces of Enterprise JavaBeans and introduce advanced local caching of Enterprise JavaBeans attributes. Then there are tools for building data persistence into Enterprise JavaBeans. Entity beans can be mapped to back-end data stores, such as relational databases. You can create EJB groups from existing database schemas or from Persistence Builder models, or vice versa. You can create or edit an association between two CMP entity beans. This is currently IBM-proprietary 72 Migrating WebLogic Applications to WebSphere Advanced Edition functionality, but similar functions will be mandated by the EJB 2.0 Specification. You can use internal deployment tools to automatically generate the implementation classes for your Enterprise JavaBeans that will run in the WebSphere server. These tools provide a means to set the deployment descriptor for your Enterprise JavaBeans. There is an integrated feature that checks and verifies that your Enterprise JavaBeans code is consistent and conforms to the rules defined by the Sun Microsystems Enterprise JavaBeans specification. Finally you can test and debug your Enterprise JavaBeans in the WebSphere Test Environment before exporting them for installation on a remote production server. Simply start the persistent name server, set up the DataSources and configure and start the EJB servers. Now you should be able to set breakpoints and debug your EJB code. You can automatically generate and run a test client program for each enterprise bean that is running in the EJB server. The EJB source code and the generated code can be versioned and you can create individual editions of each EJB. For more detailed information, refer to the following redbooks: • Developing Enterprise JavaBeans with VisualAge for Java, SG24-5429 • Design and Implement Servlets, JSPs, and EJBs for IBM WebSphere Application Server, SG24-5754 There is also a lot of information in the IBM VisualAge for Java online help: • Overview of the EJB Development: http://localhost:49213/vajdoc/ vahwebx.exe/en_US/vj32/Extract/0/ejb/concepts/c5rover.htm • Using the EJB Development Environment overview: http:// localhost:49213/vajdoc/vahwebx.exe/en_US/vj32/Extract/0/ejb/tasks/ t5rusing.htm In the next sections you will find the major EJB development steps you will face when migrating EJBs. However, if you need more details, refer to the URLs listed above. 4.1.4.1 Creating Enterprise JavaBeans For migration projects you won’t use the EJB page to develop Enterprise JavaBeans from scratch, but you will rather take the existing bean class and the home and remote interface and just generate the deployed code for the Chapter 4. Development tools 73 WebSphere server and adapt the deployment descriptor. Unfortunately WebSphere still uses the old (EJB 1.0) deployment descriptor approach, with the uneditable serialized object stored in a file (.ser). There are two ways to migrate XML descriptors, which were introduced with EJB 1.1: • You can retype the information • You use an automated tool VisualAge for Java has SmartGuides for the manual process: 1. After you have imported your application code and resolved all encountered errors and major warnings, switch to the EJB page in the Workbench window. 2. Create a new EJB group by selecting EJB -> Add -> EJB Group from the menu bar. To be faster you can also use the context menu of the Enterprise Beans pane. 3. Select the project for which you want to create the EJBs. VisualAge for Java will create an EJB reserved package in that project. Leave the option Create a new EJB group named selected and enter an arbitrary name for the EJB group. Add the new groupby clicking Finish. 4. Right-click the new group and select Add -> Enterprise Bean. Create a new enterprise bean by using the SmartGuide displayed in Figure 32: 74 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 32. SmartGuide for creating an Enterprise Bean in VisualAge for Java Enter the Bean name and the Bean type. Because we already have a bean, which we only need to migrate, select Use an existing bean class. Identify the bean by specifying the project, package and class name of the bean class. After you have done that, click Next. 5. On the second page select the existing full package type name of the home and the remote interface. Depending on the bean type, you will have to fill in other information, such as the key type for entity beans. Start the automatic creation by clicking Finish. 6. Now you are able to see all types and their members for the particular bean in the EJB page. Right-click the bean and select Properties. Enter the JNDI name, the transaction and security attributes and any necessary environment entries. Confirm your data input with OK. 7. This completes the creation of the bean in VisualAge for Java. Now you are able to generate the deployed code and to create the JAR file for deployment into WebSphere, which will contain the generated deployment descriptor. Chapter 4. Development tools 75 4.1.4.2 Importing Enterprise JavaBeans If you want to bypass the manual creation and the retyping of the deployment descriptor information, there is a way to do it automatically by converting the information you already have and then importing it to VisualAge for Java. For that you will need the jetace tool, which is described in 4.2, “jetace” on page 81. These are the steps to bypass the manual creation of Enterprise JavaBeans: 1. After you have imported your application code and resolved all encountered errors and major warnings, export the JAR file(s) containing the enterprise beans classes (bean classes, home and remote interfaces). You also have to export the dependent classes, so you either include it in the same JAR file or make a separate one. 2. Use the jetace tool according to the instructions in 4.2, “jetace” on page 81. 3. To import the jetace output JAR file back into VisualAge for Java, you should not do it with the ordinary Import in the Workbench, but since you want to import only the beans, switch to the EJB page. 4. Create a new EJB group by selecting EJB -> Add -> EJB Group from the menu bar. To be faster you can also use the context menu of the Enterprise Beans pane. 5. Select the project for which you want to create the EJBs. VisualAge for Java will create an EJB reserved package in that project. Leave the option Create a new EJB group named selected and enter an arbitrary name for the EJB group. Add the new group by clicking Finish. 6. Right-click the new group and select Import Enterprise Beans. 7. In the SmartGuide you select the output JAR file using jetace and check the beans check box. When you click Details, you should see all beans that will be imported. Deselect the .class, .java and resource check boxes, since jetace didn’t make any changes there. Unfortunately you have to import at least one .class, .java or resource file, so you must select one check box. Choosing a resource file might be best; otherwise the Finish button would stay disabled. Click Finish and all beans with their deployment descriptors will be imported. 4.1.4.3 Generating deployed code Normally you can generate the deployed code within VisualAge for Java. To do that make sure that there are no problems (errors, warnings) with your EJBs. In the EJB page there should be no superscript red X on any of the items for which you want to generate deployed code. To be on the safe side 76 Migrating WebLogic Applications to WebSphere Advanced Edition verify the beans before you start the generation process. Select the EJB group(s) or the individual beans and click the right mouse button. The context menu for the selection should have a Verify option, which you should select to verify enterprise bean consistency. If you get a message No problems found, then you are ready to generate the deployed code for WebSphere. Right-click again and select Generate Deployed Code. VisualAge will generate the server classes, the stubs and the ties into the same package where the bean class is. Unfortunately we had a major problem when we tried that. The progress indicator in VisualAge for Java 3.5 suddenly disappeared and VisualAge hung. There was no way to continue other than to kill and restart VisualAge. A document in the VisualAge Developer Domain (VADD) assured us that this was a known bug and that it should be fixed with Patch 2, which was not available by the time we were writing this book. As soon as the problem is solved, you will be able to run and debug the deployed EJBs within the WebSphere Test Environment in VisualAge. VisualAge for Java also offers utilities to generate special JAR files. If you select the EJB group(s) or bean(s) and right-click the mouse button, you will find more options under the menu item Export. You can generate an EJB JAR file, a Deployed JAR file and a Client JAR file. The other way to generate the deployed code is to use the WebSphere runtime directly. This step is described in the WebSphere InfoCenter and also in our Pet Store migration example in 9.4, “Java Pet Store deployment” on page 208. 4.1.4.4 Configuring an EJB server To test the generated beans within VisualAge for Java you have to set up an EJB server. 1. Select the EJB group(s) you want to run in your EJB server, open the popup menu by clicking the right mouse button, and select Add To -> Server Configuration. 2. The EJB server configuration window opens. Right-click on the EJB server container containing your EJB group(s) and select Properties. 3. In the properties for EJB server dialogbox, you can set a DataSource for your CMP entity beans. When you use use a DataSource, it must be added to the persistent name server. Enter the logical name of the DataSource (“jdbc/” will be prepended automatically) and select <DataSource> in the combobox. Chapter 4. Development tools 77 As an alternative to using a DataSource you can enter a database URL and the JDBC driver name. Notice that this combobox allows you to enter any JDBC driver class name and does not force you to select one from the list. WebSphere officially supports DB2, Oracle, and Sybase for EJB CMP, so while you can type a driver from another vendor here, there is no guarantee that it will work. 4. Click the OK button to complete the EJB server properties dialog. 5. Before you start the server you should start the persistent name server and configure the DataSources in the WebSphere Test Environment Control Center (see 4.1.3, “WebSphere Test Environment” on page 65). 6. To start the EJB server right-click the server and select Start Server. In the VisualAge Console window you should see the message Server open for business when the EJB server has started. 4.1.5 Persistence access builder The persistence access builder is not part of the J2EE architecture. It is an IBM proprietary tool and framework for building robust, scalable persistence support for object models. Entity beans are not suitable for fine-grained object models. This is also considered in the new EJB 2.0 Specification (see 8.5, “Business objects - persistence frameworks” on page 176). The specification guides the future of entity beans, which will be combined with finer grained dependent objects. Both will be served by a common persistence manager. For now, VisualAge for Java already offers a framework to build complex persistence mapping (including inheritance and associations) for fine-grained object models that are not entity beans. This is done with the Persistence Builder. More information about this feature and manuals on how to use it can be found in the IBM VisualAge for Java online help documentation: http://localhost:49213/vajdoc/vahwebx.exe/en_US/vj32/Extract/0/vap/html/ c5ejieta.htm 4.1.6 Apache Tomcat test environment We had to use the Apache Tomcat test environment in VisualAge, because the currently available WebSphere Test Environment did not support Java Servlets 2.2 and JSP 1.1, whereas with the fix pack PTF2 the WebSphere runtime does support the Java Servlets 2.2 and JSP 1.1 implementation levels. 78 Migrating WebLogic Applications to WebSphere Advanced Edition The Apache Tomcat test environment is an open source reference implementation of Java Servlets 2.2 and JSP 1.1. The integration with VisualAge for Java has been offered as a free download at the VisualAge Developer Domain (VADD) home page: http://www.software.ibm.com/vadd From this site we followed the hyperlinks Download -> VisualAge for Java, Version 3.5 -> Apache Tomcat Test Environment 3.1 and downloaded the ZIP file Tomcat3_1.zip. To install Tomcat in VisualAge, follow these steps: 1. Extract Tomcat3_1.zip to a temporary directory and start the extracted Setup.exe. 2. Follow the straightforward installation by doing what the Setup wizard tells you to do. 3. Start or restart VisualAge for Java. 4. If you have previously loaded the WebSphere Test Environment into VisualAge you will have to remove the existing Servlet API Classes from VisualAge before loading the new feature Apache Tomcat Test Environment. To do this VisualAge click F2 (File -> Quick Start), select Features on the left side and double click on Delete Feature in the right list. Select Sun Servlet API 2.1 to remove this feature. This will generate many code errors, but these will all be resolved in the next steps. 5. To load the new feature press F2 (or click File -> Quick Start), select Features on the left pane and double-click Add Feature in the right pane. Now select Apache Tomcat Test Environment 1.0 to add this feature. At this point trying to run the WebSphere servlet engine will fail because the API is not compatible, but you will be able to start Tomcat instead. We recommend that you read the article “Apache Tomcat 3.1 Final Release Servlet and JSP Development with VisualAge for Java”, which is available at the VADD site under http://www7.software.ibm.com/vad.nsf/Data/ Document2390?OpenDocument&p=1 for details on how to work with Tomcat and VisualAge for Java. Now instead of using the servlet engine in the WebSphere Test Environment you can use Tomcat, but still continue to use all the other functions of the WebSphere Test Environment such as the persistent name server, EJB servers, access beans, and EJB test clients because running these servers is independent from the running of a servlet container. Chapter 4. Development tools 79 You will have to add any projects and external libraries you might need to the classpath for the Tomcat Runner (for example your servlet code, your Java server classes, and your access beans). 4.1.7 BEA WebLogic Server Integration Kit BEA offers a VisualAge Integration Kit for WebLogic Server 5.1 (in beta and for VisualAge for Java V3.02 only), which enables the development and debugging of WebLogic Server applications within VisualAge for Java. This also strengthens the position of VisualAge for Java to be the development environment of choice for the development of portable J2EE applications. Inside VisualAge for Java you can test your application with both major servers in the market, WebLogic and WebSphere. The Integration Kit is offered for VisualAge for Java 3.02 and is a beta release only, but it is fairly stable and we were able to run it also under VisualAge for Java, Enterprise Edition V3.5. There were some conflicts with the javax.rmi.* and javax.transaction.* packages of the Java class libraries in VisualAge for Java, so we had to load the WebLogic projects from the repository by hand and not with the Add feature command in the Quick Start panel. For the classes that clashed with the ones in the Java class libraries project, we took the ones provided by the Integration Kit. You can obtain the download and all other installation instructions from BEA at: http://commerce.bea.com/downloads/weblogic_server.jsp#wls After downloading the package follow these steps to install the Integration Kit into VisualAge for Java v3.5: 1. Read the BEA document Installing the Integration Kit for VisualAge (found in the downloaded package under install_va.html). Carry out step 1 to step 4 of that document. 2. Open the Repository Explorer in VisualAge for Java by clicking Window -> Repository Explorer. In the opened window select the Projects tab of the notebook. 3. Scroll down to the WebLogic projects and select WebLogic Server. Rightclick the latest edition in the Editions list and select Add to Workspace from the context menu. Do the same for the projects WebLogic Server Classes, WebLogic Java 2 Classes, and WebLogic Support Libraries. 4. Switch to the Workbench Window, select the Projects page of the notebook and add a project by clicking Selected -> Add -> Project. In the dialog select Create a new project named and enter the case-sensitive 80 Migrating WebLogic Applications to WebSphere Advanced Edition name WebLogic Java Enterprise Libraries. If you entered the name correctly, a message will warn you that the project already exists and asks whether you want to create a new edition. Since we want to do that, click on OK. 5. Go back to the Repository Explorer, select the project WebLogic Java Enterprise Libraries, and click the uppermost edition and select all packages in the Packages list. Right-click over the entire selection and choose Add to Workspace. Now the packages are loaded into the WebLogic Java Enterprise Libraries project; only javax.rmi and javax.transaction will be loaded into the project Java class libraries. After you have done that, you should version the open edition of WebLogic Java Enterprise Libraries and the scratch edition of Java class libraries. 6. Continue with the remaining steps after step 9 in the BEA document Installing the Integration Kit for VisualAge. 7. Read the document Using the Integration Kit for VisualAge (either in the downloaded package or online at http://www.weblogic.com/docs51/ classdocs/visualAge.html). There is a subheading called Installing service packs. Install the latest service pack according to the instructions there. We installed service pack 6. 4.2 jetace jetace is a tool shipped with the WebSphere Application Server, Advanced Edition and is used to set up the deployment descriptor for Enterprise JavaBeans and to create a deployable EJB JAR file. Detailed information about the use of jetace can be found in the redbook WebSphere V3.5 Handbook, SG24-6161. What is not described there but particularly useful in the context of migrating a large number of EJBs is the XML feature. Instead of capturing the deployment descriptor for each individual EJB manually in different dialogs, you can create an XML file automatically or in an editor and read the XML file in jetace (by clicking File -> Read XML). You can write a job that converts EJB 1.1 deployment descriptors into the XML data format, which is expected by the jetace tool. The WebSphere InfoCenter has an appendix where the tags of the XML file are described. You can either look in your local InfoCenter copy or online at: http://www-4.ibm.com/software/webservers/appserv/doc/v35/ae/infocenter/ was/atswpgax.htm Chapter 4. Development tools 81 These are the suggested steps: 1. Import your application into VisualAge for Java and resolve all encountered problems (error and warnings). 2. Export all EJB-related classes, that is bean class(es), home and remote interface(s) to one or more JAR files. It is recommended that you keep the EJBs separate and make one or more JAR files for all the dependent classes. 3. Before starting jetace make sure that the dependent classes are included in the classpath. 4. Start <WebSphere-AppServer-home>\bin\jetace.bat. 5. Load the JAR file containing your EJB classes (bean class, home and remote interfaces) by clicking File -> Load and specifying the JAR file name in the Load From File dialog. 6. If the file was loaded without errors (no message box appears, just a line saying Finished reading the input file <filename>), you should get your converted XML file. Read it by clicking File -> Read XML. In the Read XML file dialog select your XML file, but you should change the Files of type selection to All files (*.*) in order to list the .xml files. 7. jetace will read the XML file and automatically create the serialized deployment descriptor. You can click a created enterprise bean and verify by clicking the Edit button if everything is allright and you can still do any changes you want. 8. When you are finished, you should create an EJB JAR file by clicking File -> Save As (we recommend that you use a filename different from the input-file). The output file contains the necessary deployment descriptors and is ready for the generation of the server-specific deployed code. You can either import the beans back to VisualAge for Java and generate the deployed code there (see 4.1.4.3, “Generating deployed code” on page 76) or use the tool in the WebSphere admin console. If it doesn’t pay to write an automated job for creating the jetace XML file, you can use jetace to capture the deployment descriptor information as described in the WebSphere V3.5 Handbook and save it into the XML file (by clicking File -> Write XML). If you want to recreate the EJB JAR file at a later time, you can read the XML file again. 4.3 WebSphere Studio and other JSP, HTML - Editors There are tools that can assist with the development of dynamic Web pages, but for our migration project we did not use any of these tools, since we took 82 Migrating WebLogic Applications to WebSphere Advanced Edition existing JSP files and used plain editors to make minor changes for the migration. To write portable JSP files you are free to use any tool that supports JSP 1.0 or 1.1. WebSphere Studio is highly integrated with VisualAge for Java and is a powerful solution for managing team-based development. At the time we wrote this redbook, WebSphere Studio supported JSP Versions 0.91 and 1.0, but not version 1.1. For more detailed information about WebSphere Studio, please read the redbook Servlet and JSP Programming with IBM WebSphere Studio and VisualAge for Java, SG24-5755. WebLogic JSP applications will probably be developed with WebGain Studio, which contains Macromedia Dreamweaver for the editing of HTML and JavaServer Pages. Dreamweaver UltraDev and Allaire HomeSite are two often-used HTML editors with JSP support and you can use them to produce Web applications that will run on WebLogic and WebSphere. 4.4 Other tools and products 4.4.1 J2EE Reference Implementation server Both WebLogic Server and WebSphere Application Server, Advanced Edition are committed to implement the J2EE standards. They both also offer specific products and technologies you can use to develop your applications. In order to check whether your developed application is still J2EE compliant, you could use the J2EE Reference Implementation server from Sun Microsystems, which is available for free. The J2EE Reference Implementation server is not designed to be used in production environments. 4.4.2 Converter and migration tools You may obtain converter and migration tools that automate some of the changes you have to do when migrating applications from WebLogic to WebSphere. While writing this book we developed some tools on our own or we have tried some that we got from other developers, such as a tool to convert XML-based deployment descriptors from the EJB 1.1 standard to jetace XML. Chapter 4. Development tools 83 In Chapter 9, “Migration example: The Java Pet Store” on page 181 you will find some utilities which we developed when writing this book. The utilities may be downloaded as additional material. See Appendix A.2, “Using the Web material” on page 235 for instructions on how to obtain this code. . 4.4.3 Persistence mapping tools In the currently available J2EE standards, business object modeling is not covered in detail. The Enterprise JavaBeans v2.0 and the Java Data Objects (JDO) V0.8 Specifications attempt to address this issue, but we have to wait a while to see the first implementations. The current J2EE based frameworks rely on third-party tools. Some of the well-known tools are WebGains TOPLink (bought from The Object People), Thought Inc.’s CocoBase, and Versant Corporation’s Versant Object Container. These and other vendors offer specific integrations in both WebLogic Server and the WebSphere Application Server, Advanced Edition. Applications developed with their development tools should be easily portable, but we have not tried any of these during the work for our book. 84 Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 5. JavaServer Pages This chapter describes how to migrate JavaServer Pages from WebLogic Server to WebSphere Application Server, Advanced Edition. It starts with a short overview of JavaServer Pages. Then we discuss the different levels of JavaServer Pages. After that we talk about tag libraries and JSP deployment. Finally we describe how we migrated a few JSP samples. 5.1 Introduction JavaServer Pages is the Java platform technology that supports dynamic content within Web pages. It is based on HTML and enables a Web designer to include dynamic content through JavaScript or Java. The separation of HTML presentation and the dynamic content is a big advantage. It reduces the complexibility of Web pages and enables the common work of a Web page designer and a software developer on a single Web page. This would be much more complicated when using servlets that produce HTML. JSP is Java-based, so unlike other possibilities for dynamic output it is supported by nearly every Web application server. JSPs are compiled into servlets and produce plain HTML output. Therefore any browser can be used for viewing JSPs. JSPs consist of the following: • HTML tags • Scriplets • Directives • Expressions • Actions • Declarations Custom tags (since JSP Level 1.1) For more information about JSPs see: • The Sun web site http://java.sun.com/products/jsp/ • The redbook Design and Implement Servlets, JSPs, and EJBs for IBM WebSphere Application Server, SG24-5754 • The redbook Servlet and JSP Programming with IBM WebSphere Studio and VisualAge for Java , SG24-5755 © Copyright IBM Corp. 2001 85 5.2 Developing JSPs The current specification level of JSP is 1.1. At the time of writing the JSP 1.2 Specification was available as the proposed final draft at http://java.sun.com/ products/jsp/. The specifications levels most relevant to this book are 1.0 and 1.1, because almost all JSPs used by WebLogic Server applications should meet one of the above-named specifications. The main difference between 1.0 and 1.1 is that JSP 1.1 includes a standard mechanism for the creation of tag libraries. Tag libraries reduce the use of embedded Java code in JSP pages. Tag libraries are designed to be portable between JSP 1.1 compliant servers. If you want to use JSP 1.1 pages with WebSphere then make sure you are using PTF2. Figure 4 shows the different JSP levels supported by WebSphere 3.5 and WebSphere 3.5.2: Table 4. JSP level s within WebSphere 3.5 JSP Level WebSphere 3.5 WebSphere 3.5 PTF2 1.0 full support full support 1.1 not supported: - portable tag extension mechanism - Servlet 2.2 - Few APIs - tag changes - parameters used full support WebLogic Server 4.5 came with JSP 1.0, and WebLogic Server 5.1 meets JSP 1.1 Specifications. There should be no major problems migrating JSPs between WebLogic and WebSphere. The commonly used JSP levels 1.0 and 1.1 are fully supported by WebSphere 3.5.2. As described in step 3. on page 47, you should use Servlet 2.2/JSP 1.1 Full Compliance Mode and add the JSP 1.1 Processor to your Web application. It is not possible to use a 1.0 JSP engine and a 1.1 JSP engine in one Web application. If you have JSP 1.0 and JSP 1.1, then you should use the JSP 1.1 engine. There will be only minor changes necessary, if any. The JSP specification has only four changes from JSP 1.0 to JSP 1.1 and some additions to JSP 1.0. Changes from JSP 1.0 to JSP 1.1 include: 86 Migrating WebLogic Applications to WebSphere Advanced Edition • Use of Servlet 2.2 instead of Servlet 2.1, including distributable JSP pages (for more information about servlets refer to Chapter 6, “Java Servlets” on page 109). • jsp:plugin can no longer be implemented by just sending the contents of jsp:fallback to the client. • XML equivalents for tags. • Reserved all request parameters starting with jsp. Note on XML tag format The XML tag format for JSP is not a required feature of the JSP 1.1 Specification. It becomes mandatory with JSP 1.2. The JavaServer Pages Specification Version 1.1, found at http://java.sun.com/ products/jsp/download.html says that “The JSP page to XML document mapping is not visible to JSP 1.1 containers; it will receive substantial emphasis in the next releases of the JSP specification. Since the mapping has not received great usage, we particularly encourage feedback in this area.” 5.2.1 Tag libraries Tag libraries are designed to be portable. The goal is to make it easier to separate presentation from logic, allowing JSP developers to access complex Java logic from the presentation layer by using the simple custom taqs. WebSphere comes with some tag extensions for database access and supports the implementation of custom tags. WebLogic Server 5.1 provides a custom tag library as part of Service Pack 5 (SP5). We investigated whether this could be ported to WebSphere. The WebLogic Server tag library comes with Version 5.1 SP5 and SP6. We used the tag library from Service Pack 6. Although the documentation names the file weblogic-tags-server.JAR it is shipped as lib/weblogic-tags-510.jar. If you want to use it with WebLogic Server you must have this file in the WEBLOGIC_CLASSPATH. This tag library adds three additional tags: 1. cache The cache tag caches the statements between the <wl:cache> and the </ wl:cache> tag. The output is only updated when the cache time-out is reached. Chapter 5. JavaServer Pages 87 2. repeat The repeat tag enables you to iterate over Enumerations, Iterators, Collections, Arrays of Objects, Vectors, ResultSets, ResultSetMetaData, keys of a Hashtable or simply a count attribute. 3. process The process tag allows you to selectively execute code by querying parameters. More information about how to use these tags can be found at http:// www.weblogic.com/docs51/classdocs/API_jsp.html. We developed the following small sample JSP (testbeatags.jsp) to use these three tags: <!doctype html public "-//w3c/dtd/HTML 4.0//en"> <html> <!-- no Copyright --> <head> <title>Use of BEA Tags Example</title> <%@ page import="java.util.Date" %> </head> <%@ taglib uri="/taglib.tld" prefix="wl" %> <body bgcolor=#ffffff> <font color=#DB1260> <h1>CACHE TAG</h1> <h2> The current date is <%= new Date() %>. <h3> <wl:cache timeout ="5s"> The 5 seconds cached date is <%= new Date() %>. </wl:cache> <wl:cache timeout ="10s"> <p> The 10 seconds cached date is <%= new Date() %>. </wl:cache> <h1>REPEAT TAG</h1> <% Vector v = new Vector(5); for (int i = 0; i < 5; i++) v.addElement(new Integer(i));%> <wl:repeat id="item" set="<%= v.elements() %>"> <p> Repeat NR. <%=item%> </wl:repeat> </h3> <h1>PROCESS TAG</h1> <wl:process notname="1"> 88 Migrating WebLogic Applications to WebSphere Advanced Edition <wl:process notname="2"> <form action="<%= request.getRequestURI() %>"> <input type="submit" name=" 1 " value="1"/> <input type="submit" name=" 2 " value="2"/> </form> </wl:process> </wl:process> <wl:process name=" 1 "> <p> you selected 1 </wl:process> <wl:process name=" 2 "> <p> you selected 2 </wl:process> </h2> <p> <a href="./testbeatags.jsp">Click Here</a> to start again! </BODY> </HTML> This file is included in the additional materials for our redbook. For instructions on obtaining these materials refer to Appendix A, “Using the additional material” on page 235. The deployment of the tag library to WebSphere was quite easy: 1. We put the tag library descriptor taglib.tld from the lib/weblogic-tags510.jar file (included in weblogic510sp6.zip) into the ITSO Web application directory (D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\web). 2. Then we put all the class files from the lib/weblogic-tags-510.jar file into the Web applications servlet directory. Ensure that the class files are extracted to a subdirectory called weblogicx/jsp/tags as in the JAR, so that all the class files are in the directory D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\servlets\weblogicx\jsp\tags\. 3. We put our JSP file testbeatags.jsp to D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\web When we started our sample JSP in a browser with http://localhost/itso/ testbeatags.jsp, we expected it would run without problems. But we got several errors from the JIT-Compiler, because the WebLogic Server tag library uses additional class files from the WebLogic Server standard lib path. We had to copy these files into the Web applications servlet directory. They Chapter 5. JavaServer Pages 89 were the weblogic\cluster\groupmessage.class and the weblogic\common\WLSerializable.class. You can find these files in the classes directory of the WebLogic Server root directory. Make sure to use the correct subdirectories. So we now have the following files: D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\servlets\weblogic\cluster\GroupMessage.class D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\servlets\weblogic\common\WLSerializable.class As we started our samples again the compiler told us that the process Tag Attribute notname was not recognized as an attribute of the process bean. So we had a look at the process class and noticed that the tag attributes notname and notvalue are specified as notName and notValue. With WebLogic Server and the Sun JDK this error was tolerated. For WebSphere, we had to correct this in our testbeatags.jsp. When we reloaded the test JSP, we were told that notName was not included in the tag library descriptor taglib.tld. So we corrected the two entries for notname and notvalue to notName and notValue in the taglib.tld and the sample JSP produced the same output on WebSphere as on WebLogic Server. In the first third of the output our sample shows the work of the cache tag. If you reload the page the first date line is reloaded every time, the second date every 5 seconds and the third line every 10 seconds. In the second third of the output there is a simple repeat. In the last third of the output you can test the process tag. You can click the buttons 1 or 2 to decide which lines are executed by the process tag: the JSP displays either you selected 1 or the line you selected 2. So it is possible to use the WebLogic Server tag library with WebSphere. We had a few problems with the classes behind the JSP, but not with the JSP itself. Nevertheless we would not recommend you use the WebLogic Server tag library with WebSphere for several reasons. First we had to use additional class files from WebLogic Server. There is no source code supplied with the tag libraries nor with the additional WebLogic Server class files. We made some minor errors when using the additional tags and using the supplied documentation it was quite hard to find the bugs. Also it is not clear that the use of the BEA code in WebSphere is license free or supported by BEA. Should you require similar tags in WebSphere we recommend that you develop your own tag libraries or use open software taglibs. For examples of the open source tag libraries that are available, see http://java.sun.com/ products/jsp/taglibraries.html or http://jsptags.com/tags. Migrating JSPs from WebLogic Server to WebSphere should not cause major problems. We expect that it will involve minor activities such as importing additional class libraries or replacing XML syntax with short-hand tags. Some 90 Migrating WebLogic Applications to WebSphere Advanced Edition more examples of this can be found in 5.4, “Migrating JSP examples” on page 100. 5.3 Deploying JSPs Now let’s have a look at the differences between WebLogic Server and WebSphere concerning deploying JSPs. 5.3.1 Deploying JSPs in WebLogic Server For WebLogic Server there are two possibilities: 1. Deploy as a Web application: To configure Web applications, you have to insert a line of the following format into the weblogic.properties file: weblogic.httpd.webApp.<ContextName>=<location> The Web application can be specified as an expanded directory hierarchy, for example: weblogic.httpd.webApp.estore=d:/weblogic/petStore/petStoreServer/ estore Or as an archived format (.war file): weblogic.httpd.webApp.estore=d:/weblogic/petStore/petStoreServer/ estore.war For more information about Web applications refer to Chapter 6, “Java Servlets” on page 109. 2. Deploy as single JSPs into the document directory: The following line from the weblogic.properties file shows the default document root directory: weblogic.httpd.documentRoot=public_html/ You can simply copy your JSPs to the directory: D:/weblogic/myserver/public_html If you use tag libraries you should put them into the web-inf subdirectory. In order to handle JSPs properly you have to configure the JSP servlet first. It is configured in weblogic.properties. The syntax is: weblogic.httpd.register.*.jsp=\ weblogic.servlet.JSPServlet weblogic.httpd.initArgs.*.jsp=\ pageCheckSeconds=<seconds>,\ Chapter 5. JavaServer Pages 91 compileCommand=<path to javac>,\ workingDir=<path to output directory>,\ verbose=<boolean>,\ keepgenerated=<boolean> The concrete property settings for our default configuration are listed in step 3. on page 39. For detailed information about these properties refer to the WebLogic Server documentation. 5.3.2 Deploying JSPs in WebSphere To set up JSPs from WebLogic Server in WebSphere follow these steps: 1. Set up a Web application as described in step 4. on page 48. 2. Add a JSP enabler with the needed JSP level as described in 3.4, “Setting up the WebSphere lab machine” on page 58. 3. Transfer the JSPServlet settings from WebLogic Server to WebSphere. 5.3.3 Parameter settings for JavaServer Pages This section details the differences between the WebLogic JSP servlet settings and the parameters understood by the WebSphere JSP processors. 5.3.3.1 Choosing the JSP processing servlet The WebLogic settings weblogic.httpd.register.*.jsp=\ and weblogic.servlet.JSPServlet can be set as the Servlet Web Path List of the JSP servlet for a Web application using the WebSphere Administrative Console as shown in Figure 33. 92 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 33. JSP servlet settings in a WebSphere application 5.3.3.2 The pageCheckSeconds parameter The parameter pageCheckSeconds describes how often the WebLogic Server will look for revised JSP files that need to be recompiled. To get better performance you can set the amount of time between checks. It ls also possible to set the parameter so that the server never checks for revised JSPfiles. If you do this you must ensure that the class file for the JSP is already available before the server executes the JSP. pageCheckSeconds=<seconds> has the following possible values: 0 Every request -1 Never <seconds> Amount of time in seconds before next check Chapter 5. JavaServer Pages 93 The WebSphere Version 3.5.2 documentation says that you can set similar properties for a Web application to control how often the server checks for the presence of a class file when a JSP is executed. The parameter checkjspfiles can be set to: true The check is made each time the JSP is called or at the reloadinterval below. firsttime Check only when the JSP is called for the first time. false The check is never done. The parameter reloadinterval can be set to the amount of time in milliseconds before the next check. This works only when you have selected true as the value for checkjspfiles. When testing this feature we found that it did not work when the checkjspfiles parameter was specified as a Web application attribute. We found that regardless of the setting used, WebSphere always checked for the presence of a class file every time a JSP was called, and the class file was compiled if the JSP source had changed. However, we were able to get this to work as documented when checkjspfiles was specified as an init parameter to the JSP 1.0 servlet. This did not work with the JSP 0.91 servlet or the JSP 1.1 servlet. 5.3.3.3 The compileCommand parameter The WebLogic parameter compileCommand has no equivalent in WebSphere. 5.3.3.4 The workingDir parameter The parameter workingDir has no equivalent in WebSphere. WebSphere puts the .java and the .class files created when a JSP is accessed in a temporary directory. This location varies according to the JSP processor that is being used. The locations used are shown in Table 5. Table 5. WebSphere JSP processor output locations JSP processor Servlet name Location of Java and class files produced JSP 1.1 JspServlet <was-root>\temp\<servlet-host-name>\<app-name> JSP 1.0 JspServlet <was-root>\temp\<servlet-host-name>\<app-name> JSP 0.91 PageCompileServlet <app-document-root>\pagecompile 94 Migrating WebLogic Applications to WebSphere Advanced Edition 5.3.3.5 The verbose property The verbose property decides whether a detailed error message is sent to the browser by WebLogic. For example if you try to import a Java class to a JSP and the class is not in the class path, then if the property is true you get information about which class could not be loaded and in which line of the JSP code the error occurs. If the property is set to false you received only an Error 500--Internal Server Error. In WebSphere there is no equivalent of the verbose parameter. Detailed JSP error information is written to the stdout log of the Web application. 5.3.3.6 The keepgenerated property With the keepgenerated property you control whether the generated Java files were kept. In WebSphere you can set keepgenerated as an init parameter to the JSP servlet. This applies to the JSP servlet for JSP 1.0. This servlet will keep generated Java code only if it is supplied with the keepgenerated init parameter set to a value of true. However, the JSP 0.91 and 1.1 servlets have a different behavior: generated code is always kept and a keepgenerated init parameter is not accepted. 5.3.4 Deploying JSPs in WebSphere In WebSphere there are different ways to deploy JSPs: 1. If you have a Web application archive you can import the WAR file into WebSphere. The import of Web applications is described in 6.7, “Migrating a J2EE Web application” on page 118. Note that security information from the web.xml file is not yet used, so you have to set up security separately. 2. If you have your JSPs as single files you can copy them from the WebLogic Servers document root to your WebSphere Web applications document root or a subdirectory of it. 3. As an alternative to option 2 you can use the Add a JSP File or Web Resource task of the WebSphere Administrative Console. The steps to follow are: a. In the first window, select Yes to copy a Web Resource to a predefined Web application. This is shown in Figure 34. Chapter 5. JavaServer Pages 95 Figure 34. Adding a JSP b. In the next window, Figure 35, you have to select the Web application. For our example, it is the ITSO Web Application. 96 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 35. Selecting a Web application c. Then you are asked to specify a JSP file as shown in Figure 36. You can only add one JSP at a time. Additionally you can add a relative path structure (relative to the Web application’s document root directory). With our sample path JSPExamples, the JSP testbeatags would be copied to the path D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\web\JSPExamples. Chapter 5. JavaServer Pages 97 Figure 36. Selecting a JSP file d. After clicking Finish your selected JSP file will be added. This will copy the JSP file and add a Web resource to the default host. If you plan to set security for a JSP it must be added as a Web resource. 5.3.5 Using tag libraries If you use tag libraries, deployment is automatic if you import from a Web application archive. If you copy the individual JSP files to WebSphere or use the WebSphere Administrative Console JSP wizard, you must take additional steps to deploy the tag libraries. You must copy the .tld files to your Web application’s document directory or subdirectory and the necessary class files into the Web application’s classes directory. In your JSP you can refer to the .tld file directly, relative to the root of the Web application, or preferably use an indirection by setting the tag library property of the Web application. This property consists of two parts: • URI - Tag library name for use in the Web application • Location - Where to find the tag library description file for the tag library, identified relative to the root of the Web application 98 Migrating WebLogic Applications to WebSphere Advanced Edition This makes the TLD configurable at deployment time. Figure 37 shows how to set the tag libraries property: Figure 37. Tag library property 5.3.6 Securing JSPs In WebSphere please note that servlets, JSP files, and Web pages are not represented directly, but can be selected according to their Web resource configurations. Web resources specify Web paths to these resources. If configuring resource security for a servlet, JSP file, or Web page, select the appropriate Web resource. The WebSphere documentation for adding a JSP URI to a Web application suggests using the Add JSP or Web resource task from the WebSphere Administrative Console. This task adds the JSP URI but does not add the JSP to the Web application. This can cause problems when using WebSphere security to protect the JSP Web paths (URIs). The Web paths (URIs) are treated as Web server resources because they are not part of a Web application. Therefore, security doesn't work as intended. Chapter 5. JavaServer Pages 99 Do not use the Add a JSP or Web resource task to introduce new JSP Web paths (URIs) and to associate with Web applications. If you have already done so, first remove all the Web paths (URIs) and then follow these steps in the WebSphere Administrative Console: 1. Select the Topology View 2. Expand Node->App Server->Servlet Engine to view the Web application 3. Select the JSP file processor servlet in that application 4. In the configuration panel for that JSP file, there is a list of Web paths; it should contain /default_host/<:webapp-path>/*.jsp 5. Click Add (to add to the Web path list) 6. Enter the Web paths (URIs) you want to protect (for example, / default_host/<:webap-path>/toBeProtected.jsp) 7. Repeat step 6 for all the JSP files you want to protect 8. Apply and complete this task 9. Follow standard security configuration steps to protect these newly added JSP files 10.Restart the application server 5.4 Migrating JSP examples We migrated some of the WebLogic Server JSP examples to WebSphere. If you want to try the examples make sure that you did the WebSphere configuration as described in Chapter 3, “Configuration” on page 33. 1. Create a subdirectory \JSPExamples in the ITSO Web Application Web Path (D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\web\). 2. Copy all the files from D:\weblogic\examples\jsp\ to the JSPExamples directory. 3. Create a directory D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\web\images 4. Copy the files from the directory D:\weblogic\examples\images to D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\web\images 5. Now open a browser and try the following URL http://localhost/itso/ JSPExamples/index.html 6. Select HelloWorld.jsp and choose the run link 100 Migrating WebLogic Applications to WebSphere Advanced Edition You now should see the output from the simple HelloWorld JSP. We also tried some of the other examples: • Showdate.jsp This sample works without modification. • ErrorPage.jsp and ThrowException.jsp You have to import the Java class java.io.PrintStream in ErrorPage.jsp. Do so by changing the line: <%@ page isErrorPage="true" %> to: <%@ page isErrorPage="true" import="java.io.PrintStream" %>. Then the sample works. Start it with the URL http://localhost/itso/ JSPExamples/ThrowException.jsp • SnoopServlet.jsp After you add the line <%@ import="java.util.Enumeration" %> in the file SnoopServlet.jsp and remove the following block (because of using weblogic.security.X509 classes), the sample works fine: <h3>Certificate Information</h3> <pre> . . . </pre> Start the sample with the URL http://localhost/itso/JSPExamples/SnoopServlet.jsp • SessionServlet Add the line <%@ import="java.util.Enumeration" %> to the file. The URL to start the sample is: http://localhost/itso/JSPExamples/SessionServlet.jsp. Finally we migrated three Tag Extension Examples: • Counter Example: a. Open a command window and change the directory to D:\weblogic b. Start the command setenv.cmd c. Change directory to D:\weblogic\examples\jsp\tagext\counter d. Compile the Java files in the directory with the command javac *.java Chapter 5. JavaServer Pages 101 e. Create a new directory: D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\servlets\weblogic\taglib\counter f. Copy all the class files from the directory: D:\weblogic\examples\jsp\tagext\counter to the new directory D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\servlets\weblogic\taglib\counter g. Copy pagehits.jsp from D:\weblogic\examples\jsp\tagext\counter to D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\web\JSPexamples h. Copy counter.tld from D:\weblogic\examples\jsp\tagext\counter to D:\WebSphere\AppServer\hosts\default_host\ITSO Web Application\web i. Run the example from your browser with the URL http://localhost/ itso/jspexamples/pagehits.jsp • Quote Sample: a. In the file D:\weblogic\examples\jsp\tagext\quote\WEB-INF\web.xml change the first line from: <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 1.2//EN" "http://java.sun.com/j2ee/dtds/webapp_2_2.dtd"> to: <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/webapp_2_2.dtd"> This is because only Servlet 2.2-compliant web.xml files can be imported into WebSphere. b. Change to the directory D:\weblogic\examples\jsp\tagext\quote. c. Create a new directory classes. d. Compile the Java file CodeTag.java with the command: javac -d ./classes CodeTag.java e. Create a WAR file: jar cf quote.war *. f. Import the WAR file into WebSphere at the administrative console with Console ->Tasks->Convert a War File. g. Select ITSO Servlet Engine as shown in Figure 38. 102 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 38. import quote.war - select Servlet Engine h. Select default Host. as shown in Figure 39. Figure 39. import quote.war - select Virtual Host i. Select the quote war file as shown in Figure 40. Chapter 5. JavaServer Pages 103 Figure 40. import quote.war - select WAR file Select the destination directory C:\WebSphere\AppServer\hosts\default_host as shown in Figure 41. Figure 41. Import quote.war - select Destination Directory j. Enter /quote as the Web Application Web Path and quote as the Web Application Name as shown in Figure 42. 104 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 42. import quote.war - enter Web Application path and name k. Stop and Start the ITSO Server at the administrative console. l. Copy the file D:\WebSphere\AppServer\hosts\default_host\quote\web\CodeTag.java to D:\WebSphere\AppServer\hosts\default_host\quote\web\CodeTag2.jav a. m. In the file D:\WebSphere\AppServer\hosts\default_host\quote\web\showcode.jsp change the first appearance of: <%@ include file="CodeTag.java" %> to: <%@ include file="CodeTag2.java" %> This is because the include of the CodeTag.java file is twice in showcode.jsp and this is intended. The WebLogic JSP Compiler has no problem with this. But when we wrote this book the WebSphere JSP 1.1 Compiler had a bug so that it assumed a loop had occurred when it encountered multiple includes in a JSP file, so a compile error was produced. To work around this problem, we duplicated the include file and changed one of the includes. n. Run the example http://localhost/quote/showcode.jsp. Chapter 5. JavaServer Pages 105 • Session Sample a. In the file D:\weblogic\examples\jsp\tagext\session\WEB-INF\web.xml change the first line from: <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 1.2//EN" "http://java.sun.com/j2ee/dtds/webapp_2_2.dtd"> to: <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/webapp_2_2.dtd"> b. Change to the directory D:\weblogic\examples\jsp\tagext\session\webinf. c. Create new directory classes. d. Compile the Java files in this directory with the command javac -d ./ classes *. e. Create a WAR file: jar cf session.war *. f. Import the WAR file into WebSphere similar to the import of the quote example mentioned before. Use session as the Web application name and /session as the Web applications document root. g. Run the example http://localhost/session/SessionList.jsp. • UseXMLSyntax This example uses XML syntax instead of short-hand tags. We did not get this example to work in WebSphere, but we do not regard this as a major migration issue. As we discussed on page 87, XML format is not required in JSP 1.1 and we do not believe it has been widely used in current WebLogic applications. Also it is likely that any XML-formatted JSPs written for WebLogic V5.1 will still have to be migrated to the JSP 1.2 level because the current WebLogic support does not enforce key parts of the JSP 1.2 Specification. <!doctype html public "-//w3c/dtd/HTML 4.0//en"> <html> <head> <title>JSP DATE EXAMPLE</title> <jsp:directive.page import="java.util.Date" /> </head> <body bgcolor=#ffffff> <font color=#DB1260> 106 Migrating WebLogic Applications to WebSphere Advanced Edition <h1>JSP DATE</h1> <h2> The date is <jsp:expression> new Date() </jsp:expression>. </h2> </BODY> </HTML> Chapter 5. JavaServer Pages 107 108 Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 6. Java Servlets This chapter discusses the issues you may encounter when migrating Java Servlets from BEA WebLogic Server to WebSphere Application Server, Advanced Edition. 6.1 Technology overview Java Servlets were developed by Sun Microsystems as a replacement technology for Common Gateway Interface (CGI) scripts and applications. Both CGI and Java Servlets address the same problem; they provide a means for dynamically responding to HTTP requests, allowing for dynamically generated content to be returned to the HTTP client (usually a Web browser), and permitting server-side actions to be taken in response to HTTP requests. The problems with CGI include: • CGI applications are launched in response to a single HTTP request, and then terminated when the request was handled. Because launching an application is an expensive operation, this is a very inefficient means of responding to requests. • CGI applications do not have a readily usable abstraction layer for handling HTTP requests. Developing CGI applications (especially those that need to provide statefulness) requires a great deal of detailed knowledge about the (stateless) HTTP protocol. • CGI applications are native applications. They represent a large migration problem if the hardware platform changes, which can be a common occurrence when Web sites are scaled up to deal with increased load (a problem compounded by the heavyweight nature of the CGI applications). • Depending on the language used to develop CGI applications (the most common language for developing CGI applications is C), memory leaks are quite common. This in turn is compounded by the fact that many CGI applications are written by relatively inexperienced developers. By contrast, Java Servlets, running inside a Java servlet engine (a type of HTTP server), solves these problems. • Java Servlets run as a lightweight thread within the Java servlet engine. This dramatically reduces the overhead cost of handling an HTTP request. • The Java Servlets API provides a rich and useful abstraction layer for examining HTTP requests and generating responses. Many common problems, such as dealing with session state and handling the differences © Copyright IBM Corp. 2001 109 in parameters from HTTP GET and POST operations, are solved easily within the Java Servlets API. In addition to the servlet API, the developer gets full access to the rest of the Java APIs. • Java Servlets are written in Java. Because of this, they can be readily moved from one hardware platform to another, as long as the servlet engine is also available on that platform. Indeed, due to the standardization of the API, it is usually very easy to migrate from one servlet engine to another. • Java’s memory protection and garbage collection prevents most common forms of memory leaks. The most significant problem with Java Servlets is that they do not provide for a clean separation of code from the HTML content that they are intended to generate. To solve this problem, Sun Microsystems introduced the JavaServer Pages (JSP) API. JSP is a technology built on top of Java Servlets, and allows for a content-focused means of generating dynamic content. This allows for a cleaner separation of the decision-making dynamic data generation from the task of generating dynamic content to present that data. JavaServer Pages are covered in Chapter 5, “JavaServer Pages” on page 85. 6.2 Web application design The increasingly more common method of designing Web-based applications is based on the Model 2 architecture, as illustrated in Figure 43 on page 110. Client Server HTTP Web Browser Command Servlet HTML JSP ResultBean Business Logic Bean Web Browser, Java Applet Command Client (Proxy) RMI over IIOP Command Server Bean Figure 43. Model 2 architecture 110 Migrating WebLogic Applications to WebSphere Advanced Edition In this architecture, HTTP requests (usually generated by a Web browser) are submitted to a controlling servlet. This servlet examines the parameters submitted with the request to determine what actions need to be performed. The servlet will then call methods on one or more Java classes (the Business Logic Bean(s) in the diagram, which would include normal Java classes and Enterprise JavaBeans), and the results will be stored in other Java classes (the Result Beans). After this, the servlet will forward the request to a JSP, which will examine the Result Beans in order to generate the content that is returned to the client. Those readers familiar with object-oriented design patterns will recognize that the Model 2 architecture is analogous to the more common Model-ViewController (MVC) architecture. In this architecture, the role of the servlet is as a traffic cop. The values of parameters coming into the servlet via the HTTP request determine the actions to be taken, and the servlet directs the flow-of-control during the request processing. A common means of doing this is to implement a statemachine, and use the HTTP request parameters to identify the current state and the triggered event. This approach is illustrated in Sun Microsystems’ sample application, the Java Pet Store. Other suitable uses of servlets would include any situation where there is significant code and business logic to be processed in response to an HTTP request. This code and business logic would ideally be encapsulated in a Java class of its own, leaving the servlet as a wrapper (with a URL) that accepts the HTTP request and passes the parameters to the Java class. Writing extensive code into a servlet, while certainly possible, is not normally a good idea. Thus, servlets are best used as a facade to another Java class, where it is necessary to respond to an HTTP request, and where finer control over the HTTP request and response is needed than provided by JavaServer Pages. 6.3 The importance of being a servlet Because servlets serve as the entry point for Web clients into your application, they play a very prominent role in a migration project. Along with JSPs and static HTML pages, servlets are the visible part of the application, and thus provide the area where you can hide the effects of the migration as long as possible. Chapter 6. Java Servlets 111 6.4 Migration examples For the purposes of this project, we migrated several of the example servlets that are provided with WebLogic Server 5.1. Some were not attempted; for example, we did not migrate the PageEvent servlet since WebLogic Events are not supported in WebSphere. We also did not migrate the servlets that used the htmlKona extensions, for reasons discussed later in 6.10, “Migrating htmlKona” on page 125. The example servlets we migrated are: • • • • • • • examples.servlets.CookieCounter examples.servlets.HelloWorldServet examples.servlets.HelloWorld2 examples.servlets.HelloWorld3 examples.servlets.SessionServlet examples.servlets.SimpleServlet examples.servlets.SnoopServlet These examples were migrated with no code changes. The examples that were not migrated are: • • • • • • • examples.servlets.AppletServlet examples.servlets.ErrorServlet examples.servlets.HelloKonaServlet examples.servlets.PageEvent examples.servlets.PhoneServlet examples.servlets.SimpleFormServlet examples.servlets.SurveyServlet As mentioned earlier, the PageEvent servlet was not migrated due to lack of support for WebLogic Events. The other servlets were not migrated due to the use of htmlKona. In all of those cases, however, migration would have consisted of replacing the htmlKona code with some other means of preparing the HTML output. The steps taken to migrate the HelloWorldServlet are listed in 6.6, “Deploying an unpackaged servlet In WebSphere” on page 113. The other servlets all followed the same procedure, and so are not discussed specifically. In addition to these examples, we migrated the example Web application that is shipped with WebLogic Server 5.1. This is documented in 6.7, “Migrating a J2EE Web application” on page 118. 112 Migrating WebLogic Applications to WebSphere Advanced Edition Finally, as discussed in Chapter 9, “Migration example: The Java Pet Store” on page 181, we migrated the Java Pet Store, including the Web application component. The lessons learned during these migrations are documented within this chapter. 6.5 Differences in implementation WebLogic Server 5.1 is a fully compliant implementation of the Java Servlets 2.2 Specification from Sun Microsystems. As such, standard Java Servlets 2.2 code will work correctly. WebSphere Application Server, Advanced Edition 3.5, with fix pack 2 installed, has partial support for the Java Servlets 2.2 Specification. Support is provided for all of the Java Servlet 2.2 Specification, with the exception of the J2EE extensions. In particular, the security support remains at the servlet 2.1 level, and there is no support for J2EE references that would normally be defined in the web.xml file associated with the Web application. There is also no direct support for Web application, but support is provided to convert a Web application archive, or WAR file, subject to the API restrictions described above. For further information on the servlet 2.2 limitations in WebSphere, see the release notes for fix pack 2 to WebSphere Application Server, Advanced Edition. We address the major issues outlined in the fix pack later on in this chapter. 6.6 Deploying an unpackaged servlet In WebSphere An unpackaged servlet is the term we have decided to use to describe a Java servlet that is not part of a Web application archive. It may be available in a directory or a JAR file, or available as part of the classpath for WebSphere in some other mechanism. Unpackaged servlets are deployed individually, whereas packaged servlets are deployed en masse, as part of a Web application archive. In order to deploy a servlet, you need to have several things available. • You need to have access to the class file of the servlet, as well as any supporting classes. Note that WebSphere has available to it the standard Java classes, as well as the Java Servlets API. • You need to determine what URLs the servlet will be mapped to. Chapter 6. Java Servlets 113 • You need to determine the initialization parameters that the servlet will use. The last two items can be determined by examining your weblogic.properties file. Consider the following entry: weblogic.httpd.register.itso/ helloWorld=examples.servlets.HelloWorldServlet weblogic.httpd.initArgs.helloWorld=\ message=Hello World! This entry registers the servlet, examples.servlets.HelloWorldServlet, to a URI of itso/helloWorld (relative to the base URL of the WebLogic Server). If WebLogic Server was running on http://localhost:7001/, then the above servlet would be accessible at http://localhost:7001/itso/helloWorld. In addition, the entry above specifies that the servlet will be passed one initialization parameter, with the name of message and the value of Hello World!. The servlet does not actually use these initialization parameters; they are included for demonstration only. For the purposes of this example, we shall assume that the classpath required to locate the examples.servlets.HelloWorldServlet is D:\WeblogicExamples. We are also assuming that, at this point, no code changes need to be made to the servlet. This is a likely scenario, assuming that no WebLogic-specific code has been used, since unpackaged servlets cannot take advantage of the J2EE extensions that WebSphere does not support. The steps to deploy this unpackaged servlet are straightforward. 1. In the WebSphere Administrative Console select the Web application to deploy the servlet into. This will display the properties for the Web application. Creating a Web application is covered in step 4. on page 48. 2. Add the classpath for the servlet to the classpath of the Web application. This is illustrated in Figure 44 on page 115. If there is a need to use any third-party classes, ensure that the classpath entries include them. 114 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 44. Setting the classpath for a Web application 3. Right-click on the Web application, and select Create ->Servlet from the resulting pop-up menu. 4. On the Create Servlet dialog, enter in the information to configure the servlet. An example of this can be seen in Figure 45 on page 116. There are some important items to note about the dialog: - The servlet name is used by WebSphere to identify the servlet. It is not related to the URL used to access the servlet. - The servlet Web path list is used to assign the URL(s) used to access the servlet. It is automatically prefixed by the WebSphere host and Web application, as shown in Figure 46 on page 116. This is mapped to a URL depending on the host settings. For example, if the host is mapped to http://localhost/, then the URL for the servlet would be http://localhost/itso/helloWorld. - The initialization parameters are on the Advanced tab of the Create Servlet dialog. Chapter 6. Java Servlets 115 Figure 45. The Create Servlet dialog Figure 46. The Add Web Path to Servlet dialog 5. Finally, start the Web application. The servlet should now be accessible. If there is a problem accessing the servlet, verify that the classname of the servlet is entered correctly, that the classpath of the Web application is correctly entered (including any supporting classes used by the servlet), that the URL is correct, and that the Web application is running. 6.6.1 Problems converting servlets This section details some of the issues we found when converting servlets. 116 Migrating WebLogic Applications to WebSphere Advanced Edition 6.6.1.1 Case-insensitive data treated sensitively The most significant problem we had in converting unpackaged servlets was with retrieving header names from an HttpServletRequest. We had a servlet that displayed the HTTP headers. Rather than using HttpServletRequest.getHeader(String name) to retrieve the HTTP header it was seeking, it retrieved an enumeration of the header names (via HttpServletRequest.getHeaderNames()), and examined them individually. According to the Java Servlet 2.2 JavaDoc, the HTTP headers are caseinsensitive. However, the code examining the headers was not. WebLogic returned the header names in a mixed-case format, whereas WebSphere returned them all as lowercase. The service() method of the servlet was like this: protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, java.io.IOException { java.io.PrintWriter out = resp.getWriter(); java.util.Enumeration headers = req.getHeaderNames(); while (headers.hasMoreElements()) { String name = (String)headers.nextElement(); String value = req.getHeader(name); out.println(“Header name “ + name + “ has value “ + value); } } The output from WebLogic was: Header name Connection has value Keep-Alive Header name User-Agent has value Mozilla/4.76 [en] (WinNT; U) Header name Host has value localhost:7001 Header name Accept has value image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */* Header name Accept-Encoding has value gzip Header name Accept-Language has value en Header name Accept-Charset has value iso-8859-1,*,utf-8 The output from WebSphere was: Header name accept has value image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */* Header name accept-charset has value iso-8859-1,*,utf-8 Header name accept-encoding has value gzip Header name accept-language has value en Header name connection has value Keep-Alive Header name host has value localhost Header name user-agent has value Mozilla/4.76 [en] (WinNT; U) Chapter 6. Java Servlets 117 As can been seen, the case of the header names has changed, but the header values have not. Code that relies on the case of the header names would not migrate unchanged from WebLogic to WebSphere. It is worth noting that the HttpServletRequest.getHeader(String name) method is case-insensitive as well. 6.6.1.2 Using third-party classes In order to enable the use of third-party classes in WebSphere, the classpath of the Web application needs to be modified. WebSphere Application Server, Advanced Edition 3.5.2 supports third-party classes written to conform to the Java 1.2.2 Specification (or earlier). It does not support Java 1.3 classes at this time. 6.7 Migrating a J2EE Web application WebSphere Application Server, Advanced Edition lacks direct support for J2EE Web applications, but a tool is provided, within the WebSphere Administrative Console, to convert WAR files. This tool is accessible by selecting Console ->Tasks ->Convert A War File from the main menu. This will take you through a series of steps. For this example, we built the example J2EE Web application that is delivered with WebLogic Server into a WAR file, which we placed at D:\WeblogicExamples\cookie.war. 1. First, you select the servlet engine to deploy the J2EE Web application into. 2. You then select the host to deploy into. 3. Next, you select the WAR file to be deployed. 4. You then select the directory that the J2EE Web application will be unpacked into. This will be used as the root for the WebSphere-style Web application. 5. As the final step, you have to enter the name of the Web application and the path to the root of the Web application (from the root of the host). This is a defect in the WebSphere implementation, because it should be able to read this information from the web.xml file that is part of the WAR file. 118 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 47. Applying the Web Name and Path to the converted Web application You should then be able to access the root page of the Web application according to the settings of the host you selected and the path you entered in the final step. For our example, this was http://localhost/itso-webapp. 6.7.1 Problems With converting Web applications 6.7.1.1 Strict servlet-mappings One problem that is worth noting is that WebSphere is strict about having the servlet-mapping section of the web.xml file conform to the Java Servlets 2.2 Specification (Section 10.2). In particular, it requires that the servlet-mapping begin with a ‘/’ character. The sample web.xml file provided with WebLogic Server does not conform to this rule. This prevents the servlets from being deployed, but is a simple problem to correct (if not to diagnose). An example of a bad servlet-mapping would be: <servlet> <servlet-name>CookieCounter</servlet-name> <servlet-class>servlets.CookieCounter</servlet-class> </servlet> <servlet-mapping> <servlet-name>CookieCounter</servlet-name> <url-pattern>monster</url-pattern> </servlet-mapping> Chapter 6. Java Servlets 119 The correct servlet-mapping would be: <servlet> <servlet-name>CookieCounter</servlet-name> <servlet-class>servlets.CookieCounter</servlet-class> </servlet> <servlet-mapping> <servlet-name>CookieCounter</servlet-name> <url-pattern>/monster</url-pattern> </servlet-mapping> 6.7.1.2 Problems binding JSPs into servlets J2EE-style Web applications allow a servlet to be deployed either as a compiled Java class, or as a JSP file. An example of this would be: <servlet> <servlet-name>CookieCounter</servlet-name> <jsp-file>cookie.jsp</servlet-class> </servlet> <servlet-mapping> <servlet-name>CookieCounter</servlet-name> <url-pattern>monster</url-pattern> </servlet-mapping> WebSphere only allows compiled Java classes to be deployed as servlets. In order to migrate applications that use JSPs as servlets, we recommend that the JSP be implemented as a servlet. 6.8 Converting J2EE references The deployment descriptor in J2EE Web applications allows for various references to be defined. The purpose of these references is to allow the developer to be able to access various environment-dependent values (such as EJB homes and DataSources), in such a way that does not impact the deployer. These values are then able to be retrieved within the JNDI name space of “java:comp/env”. The deployment descriptor provides a mapping of these JNDI entries to the values correct for the deployed environment. For a more complete description of J2EE References, as they exist in Web applications, see Section 9.9 of the Java Servlets 2.2 Specification, and Chapter 5 of the Java 2 Platform, Enterprise Edition 1.2 Specification. 120 Migrating WebLogic Applications to WebSphere Advanced Edition Unfortunately, WebSphere Application Server, Advanced Edition 3.5.2 does not support this functionality (Web applications and related features are an optional component of the Java Servlets 2.2 Specification), whereas WebLogic Server 5.1 does support it. The only solution is a manual conversion of the JNDI lookups. J2EE References fall into three categories. These are: • Environment entries (env-entry) • Enterprise Java Bean references (ejb-ref) • Resource references, such as JDBC data sources (resource-ref) Converting EJB and resource references is covered extensively in 7.4, “JNDI lookups expanded” on page 134. However, the solution for environment entries for EJBs will not work for servlets. Under WebSphere, the most appropriate means of providing similar functionality is to pass in the environment variables either as initialization parameters to the servlet, or as attributes on the servlet engine. Values passed in via the initialization parameters are available via the getInitParameter() method on the ServletConfig (available via Servlet.getServletConfig()). Values passed in as attributes on the servlet engine are available via the getAttribute() method on the servlet Context (available via ServletConfig.getServletContext()). To retain complete functionality, you would define the value as an attribute on the servlet engine, and then pass the name of that attribute in as an initialization parameter to the servlet. Thus, a line of code like this: String value = (String)(new InitialContext().lookup(“java:comp/env/Name”)); would become: String value = getServletConfig().getServletContext().getAttribute(getServletConfig().get InitParamter(“Name”)); However, for many applications, this form of double-indirection, while retaining deployment flexibility, is probably overkill. It would normally be acceptable to provide the value either as an initialization parameter, or as an attribute of the servlet engine, and use either the ServletConfig or ServletContext to retrieve the value. Chapter 6. Java Servlets 121 6.9 Converting J2EE security In this section we discuss the issues associated with security migration. 6.9.1 Migrating the user database This section does not describe how to migrate user settings from WebLogic Server to WebSphere Application Server, Advanced Edition. Both products have sophisticated user management tools, including the ability to delegate user authentication to the operating system or a directory service. For this reason, the actual migration of the user database is beyond the scope of this section, and, indeed, this book. WebSphere Application Server, Advanced Edition can be configured to authenticate users either against the local operating system, or, using Lightweight Third Party Authentication, against an LDAP-based directory service. 6.9.1.1 Authenticating against the operating system In order to configure WebSphere to use the operating system for authentication, you need to start up the WebSphere Administrative Console. Once started, select Console ->Tasks ->Configure Global Security Settings. Figure 48. Selecting the authentication mechanism 122 Migrating WebLogic Applications to WebSphere Advanced Edition Once the Set Global Security Wizard dialog is displayed, you should switch to the Authentication Mechanism tab. From this tab, you can select the local operating system as the authentication mechanism. For further information on how to configure WebSphere Application Server, Advanced Edition authentication settings, especially for authenticating against an LDAP directory, consult the WebSphere documentation. 6.9.2 Changes required for security migration WebSphere Application Server, Advanced Edition support for Java Servlets includes the full API for security. Therefore, no code changes should need to be made in order to migrate security-related aspects of Java Servlets. However, as WebSphere Application Server, Advanced Edition has no support for J2EE Web applications, it is not possible to declaratively secure parts of the Web application. Instead, it is necessary to use the WebSphere Administration Console to secure the Web application. For information on how to do this, consult the WebSphere documentation. In addition, if the Web application being migrated uses form-based authentication, it is necessary to create a Custom Login Form for WebSphere. The Java Servlets 2.2 Specification discusses two types of authentication mechanisms. These are HTTP-based authentication mechanisms (HTTP Basic, HTTP Digest, and HTTPS client), and form-based authentication. For more details on the types of authentication mechanisms, consult Section 11.5 of the Java Servlets 2.2 Specification. 6.9.2.1 Configuring WebSphere to use HTTP-based authentication In order to use HTTP-based authentication, you need to open the WebSphere Administrative Console, and select Console ->Tasks ->Configure Global Security Settings. Once the Set Global Security Wizard is displayed, select the Application Defaults tab. Chapter 6. Java Servlets 123 Figure 49. Setting the challenge type Selecting a challenge type of Basic (User ID and Password) will configure WebSphere to use HTTP-based authentication. 6.9.2.2 Configuring WebSphere to use form-based authentication WebSphere can be configured to use form-based authentication. To do this, follow the steps outlined in 6.9.2.1, “Configuring WebSphere to use HTTPbased authentication” on page 123, but select Custom as the challenge type. You will also be required to specify the URL to use for authentication. Two fields are available, providing a URL for login, and another for relogin. However, these are required to be the same in the current version of WebSphere Application Server, Advanced Edition. The URL provided may be a static HTML page, or it may be a servlet. Ultimately, however, the user should submit user information, such as a user ID and password, to a servlet, which can then use the IBM Security APIs to authenticate the user. For an example of such a servlet, see the CustomLoginServlet provided with WebSphere. The servlet should be available at %WAS_HOME%\servlets\CustomLoginServlet.java. 124 Migrating WebLogic Applications to WebSphere Advanced Edition 6.10 Migrating htmlKona htmlKona is an API available with WebLogic Server, expressly for creating and manipulating HTML programmatically. WebSphere does not have such a set of APIs distributed with it. The recommended approach is to replace the use of htmlKona with JavaServer Pages, which allow for more convenient development and maintenance of the HTML. If there is a strong need to manipulate HTML programatically, we suggest that you instead manipulate XHTML, a version of HTML 4.0 that is XMLcompatible. This will permit you to use the powerful IBM XML parser tools. In any event, migrating servlets that make extensive use of the htmlKona APIs will require extensive rewriting of code. Chapter 6. Java Servlets 125 126 Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 7. Enterprise JavaBeans This chapter presents a comprehensive set of EJB migration issues and recommendations. It is based primarily on an analysis of the EJB 1.0 and EJB 1.1 Specifications. 7.1 Introduction Enterprise JavaBeans (EJBs) are the core of the J2EE enterprise Java component technology. EJBs are remotely accessible, distributed objects. They implement the business logic of an enterprise system and provide clients with Java interfaces for remote access. As enterprise components, EJBs extend the write once run anywhere feature of Java to enterprise transactional servers, such as WebSphere and WebLogic. In theory, an EJB can be redeployed in any J2EE server without recompilation. All that is required is a redeployment, optionally modifying deployment parameters to conform with the new operational environment. Figure 50 on page 128 depicts the EJB architecture. The basic idea is that EJBs live inside containers provided by J2EE vendors. The container is responsible for resource services such as persistence, transactions, security, and resource management, while the EJBs implement the business logic. Other Java classes can live in the same container for use by EJBs, in particular for access to legacy systems. Clients create and access EJBs through Java interfaces. Although the interfaces declare the EJB business methods, interface calls are intercepted by the container. EJBs only get control indirectly through container-managed method calls. The container delegates interface calls to its contained EJBs only after performing necessary system services. An EJB is parameterized to enhance its portability. It can reference environment properties, other resources such as DataSources, and other EJBs, but only through indirect named references. The names are compiled into the EJBs, and their values are provided by deployment descriptors. Transaction management, security management, and container-managed persistence (CMP) are also specified by declarative deployment parameters. A deployment descriptor is constructed for the EJBs as part of an assembly process. A deployment descriptor tool simplifies this process and packages the result as an ejb-jar file. This file contains the original EJB classes and interfaces along with the completed deployment descriptor. The next step is to deploy the ejb-jar into the container. Code is generated during this step. Stubs and ties are generated for RMI-IIOP remote access to © Copyright IBM Corp. 2001 127 client (servlet, application) remote home lookup resource stub stub access, update create, find ejb-ref lookup resource 1.0 environment container CMP & transactions 1.1 resource-ref env-entry deployment descriptors ties JNDI server EJB other Java classes Figure 50. EJB architecture the EJB objects. Vendor-specific code is also generated. This code includes the vendor’s implementation of the deployment parameters. Vendors may extend deployment descriptors with vendor-specific features. Additional code may be generated to support these features. The container provides a JNDI server for runtime access to the values of deployment parameters. These values are loaded into the server when an EJB is started. At that point, the EJB is available to all clients for access through the JNDI server. Clients can include servlets, Java applications, and other EJBs. Environment properties are also made available, but only to the EJBs with which they were deployed. One of the major changes between the EJB 1.0 and the EJB 1.1 Specifications affects the programmatic interface for access to environment properties. EJB 1.0 uses a Properties object, while EJB 1.1 uses the JNDI server. 128 Migrating WebLogic Applications to WebSphere Advanced Edition At runtime, a client locates an EJB’s home through the appropriate JNDI server. For a servlet in a Web server, this is normally the container’s default JNDI server. A public JNDI server is needed for remote access directly from an application. The EJB’s home object implements the Home interface and is used to create or find EJB instances. EJB instances are referenced by the resulting stubs. The stubs implement the EJB’s Remote interface. The Remote interface supports all of the business logic methods, providing access and manipulation of the remote EJB instances. 7.2 Major migration issues The WebLogic 5.1 container and deployment tools follow the EJB 1.1 Specification. The WebSphere 3.5 container and deployment tools follow the EJB 1.0 Specification. Thus, migrating EJBs from WebLogic 5.1 to WebSphere 3.5 requires that we migrate the EJBs from the EJB 1.1 to the EJB 1.0 Specification. The bulk of this chapter identifies and discusses the required modifications. In most cases, no source code changes are required because the EJBs are compliant with both specifications. For the cases that require changes, we outline the available alternatives. When source code changes are required, we encourage minimal changes so that the code can easily revert back to the EJB 1.1 Specification in the future. We used the EJB specifications themselves as the major source of information for this chapter. Appendix C, “Revision History” of the EJB 1.1 Specification is a complete list of changes to the EJB specifications. Over 100 changes are documented there. We discovered that only eight of these changes actually affect the reverse migration from EJB 1.1 to EJB 1.0. They are described in the following sections of this chapter. There are about 20 other changes to the specifications that have no impact on migration. For completeness, these are documented in 7.12, “Non-issues” on page 150. Most of the remaining changes are improvements and corrections to the document itself, and do not constitute substantive changes to the EJB specifications. The title of each of the following sections describes the specification change that led to a migration issue. We provide a detailed background on each of these specification changes along with our recommendations for the resulting migration issues. As appropriate, migration issues are documented with before and after source code examples. We validated most of the recommendations in this chapter by means of the Java Pet Store migration documented in Chapter 9, “Migration example: The Java Pet Store” on page 181. We also tell you which recommendations we did not test. Chapter 7. Enterprise JavaBeans 129 7.2.1 Summary of recommendations Here is a list of recommendation for the major EJB migration issues covered in this chapter. • Replace EJBException with RemoteException. • Use EJBContext Properties in place of JNDI for environment properties. • Deploy EJBs with full java:comp/env/ejb names. • Rely on VisualAge for Java to construct deployment descriptors. • Use Enumeration in place of Collection for Finder methods. • Use JNDI names in place of HomeHandles. • Revert to EJB 1.0 CMP ejbCreate specification. • Use javax.jts for transaction package. • Use transaction attribute NotSupported in place of Never. • Replace Principal with Identity. • Use read-only method attribute in place of the WebLogic isModified method. 7.3 EJBException replaces RemoteException in EJBs An EJB reports unexpected errors to its container by throwing an EJBException or a RemoteException, depending on the EJB release level. EJBException is used in EJB 1.1 while RemoteException is used in EJB 1.0. Examples of unexpected errors include database errors and RemoteExceptions thrown from dependent EJBs. Clients only see RemoteExceptions. All EJBExceptions are wrapped by the container in a RemoteException. The client can use getMessage to determine if the RemoteException was a communication error or caused by an EJBException. If your EJBs use EJBException, they will have to be modified to compile and run properly with the EJB 1.0 Specification supported by WebSphere. This change only affects exceptions thrown by EJBs to their containers. It does not affect EJB Remote and Home interfaces — they continue to use RemoteException. An application that uses the 1.1 EJBException will fail to compile in an EJB 1.0 environment. Although both releases provide an EJBException class, the 1.0 EJBException is a checked exception (extending java.lang.Exception) while the 1.1 EJBException is an unchecked exception (extending java.lang.RuntimeException). The WebSphere JDK will report errors when 130 Migrating WebLogic Applications to WebSphere Advanced Edition you compile unchecked 1.1 EJBExceptions. The compiler complains that EJBException should be caught or added to the EJB method’s throws clause. This, however, is not the correct solution to the problem. On further examination of the EJB specifications we found that the EJB 1.0 EJBException is actually an anomaly. It is in the javax.ejb package, but it is not in the EJB 1.0 Specification. The EJBException was removed late in the drafting of the EJB 1.0 Specification, but unfortunately, it was left in the class library. (See “C.2 Changes since Release 0.9” in the Enterprise JavaBeans 1.0 Specification.) The correct way to report unexpected errors to the EJB 1.0 container is by using the RemoteException. Although deprecated in EJB 1.1, EJBs that throw RemoteException must still be supported in EJB 1.1 containers. If your EJBs use RemoteException for this purpose, then you are not affected by this migration issue and should just plan to move to EJBExceptions after a future upgrade to an EJB 1.1compliant platform. Table 6 on page 131 provides a summary of how EJB 1.0 and EJB 1.1 containers deal with exceptions thrown from their contained EJBs. The basic rule is that the container wraps unchecked exceptions in a RemoteException, but passes checked exceptions (including all application exceptions) through to its clients. Source code changes are required to convert EJBs from the 1.1 to the 1.0 Specification. Client code and EJB Home and Remote interfaces are not affected. Indeed, if you have the option to procrastinate and stick with the deprecated 1.0 RemoteException behavior, no changes are required to your EJBs either. Table 6. Container behavior for EJB exceptions exception EJB 1.1 EJB 1.0 Application exception (checked) [note 1] Container throws same application exception. Any client transaction is not marked for rollback. Container throws same application exception. Any client transaction is not marked for rollback. RemoteException (checked) Deprecated but supported. Behavior same as for EJBException. Container throws RemoteException [note 3]. Any client transaction is not marked for rollback. Chapter 7. Enterprise JavaBeans 131 exception EJB 1.1 EJB 1.0 EJBException [note 2] Container throws RemoteException [note 3]. Any client transaction is marked for rollback. Not defined [note 4]. Other unchecked exception Container throws RemoteException [note 3]. Any client transaction is marked for rollback. Notes 1) Application exceptions are always checked exceptions and should not extend RuntimeException and RemoteException. 2) EJBException is unchecked in EJB 1.1, and checked in EJB 1.0 (see note 4). 3) Container throws TransactionRolledbackException instead, if it rolls back a transaction. TransactionRolledbackException is a subclass of RemoteException. 4) EJB 1.0 EJBException class exists, but was removed from the specification. 5) Good practice recommends that an unchecked exception be documented by an @throws javadoc tag instead of a throws clause. The following is a typical example of the use of the EJB 1.1 EJBException. Both newly discovered errors, and errors propagated from other EJBs, are reported to the EJB container by throwing an EJBException. public Account getAccount() { try { AccountHome acctHome = EJBUtil.getAccountHome(); return acctHome.findByPrimaryKey(userId); } catch (FinderException fe) { throw new EJBException(fe); } catch (RemoteException re) { throw new EJBException(re); } } There are two approaches to converting this code back to the EJB 1.0 Specification. You can return to using RemoteException, or you can create a new unchecked exception that acts like the 1.1 EJBException. 7.3.1 Revert to RemoteException The following code is a modification to the above example. It shows the standard EJB 1.0 use of RemoteException to report errors to the container. public Account getAccount() throws RemoteException { try { AccountHome acctHome = EJBUtil.getAccountHome(); 132 Migrating WebLogic Applications to WebSphere Advanced Edition return acctHome.findByPrimaryKey(userId); } catch (FinderException fe) { throw new RemoteException(fe); } } Since RemoteException is a checked exception, it must be added to the method’s throws clause. RemoteExceptions thrown from other EJBs need not be caught; they just propagate up to their container. Also, as a checked exception, RemoteException does not roll back client transactions. In rare cases you may need to add a call to the setRollbackOnly method on the EJBContext object to duplicate the precise client transactioning semantics of the unchecked 1.1 EJBException. 7.3.2 Use unchecked EJBExceptionMigrate An alternative solution uses an unchecked exception in place of the RemoteException. We used this approach in the Java Pet Store example in 9.3.4, “EJBException changes” on page 205, and recommend its use generally. Not only are its semantics identical to the 1.1 EJBException (see Table 6 on page 131), but the changes are trivial and obvious to the reader. In the following code, the new unchecked EJBExceptionMigrate replaces the 1.1 EJBException in our original example. public Account getAccount() { try { AccountHome acctHome = EJBUtil.getAccountHome(); return acctHome.findByPrimaryKey(userId); } catch (FinderException fe) { throw new EJBExceptionMigrate(fe); } catch (RemoteException re) { throw new EJBExceptionMigrate(re); } } where: public class EJBExceptionMigrate extends RuntimeException { public EJBExceptionMigrate () { super(); } public EJBExceptionMigrate (Exception ex) { super(ex.toString()); } public EJBExceptionMigrate (String mess) { super(mess); } } Chapter 7. Enterprise JavaBeans 133 7.3.3 EJBException subclasses The 1.1 EJBException can have subclasses. NoSuchEntityException extends EJBException, and was added with the EJB 1.1 Specification. It means that the requested entity was removed from the database. Users can also extend the EJBException. These subclasses must be converted to work with the 1.0 EJBs of WebSphere. To this end, it is possible to add appropriate subclasses to RemoteException, but we think that extending the EJBExceptionMigrate offers a cleaner solution. For example, the replacement class NoSuchEntityExceptionMigrate is defined as follows: public class NoSuchEntityExceptionMigrate extends EJBExceptionMigrate { public NoSuchEntityExceptionMigrate () { super(); } public NoSuchEntityExceptionMigrate (Exception ex) { super(ex.toString()); } public NoSuchEntityExceptionMigrate (String mess) { super(mess); } } With this approach, the names of user-defined exceptions remain unchanged — only their parent class name needs to change. For example, convert: public class GeneralFailureException extends EJBException { ... } to: public class GeneralFailureException extends EJBExceptionMigrate { ... } 7.4 JNDI lookups expanded EJBs can access several kinds of dependent objects at runtime by means of named references. The values bound to these names can be changed without recompiling the EJB code. A primary function of EJB deployment is to customize EJBs by defining these name/value pairs. Major changes were made in this area of the EJB specification between Releases 1.0 and 1.1. In theory, this impacts all EJBs that migrate from the EJB 1.1 Specification supported by WebLogic to the EJB 1.0 Specification supported by WebSphere. In practice, however, much of the impact can be minimized or avoided as described below. Table 7 on page 135 identifies the different types of objects that can be looked up at runtime. It shows the different API and naming conventions used for the EJB 1.1 and EJB 1.0 Specifications. The object types are identified by their EJB 1.1 deployment descriptor names: env-entry, ejb-ref, and resource- 134 Migrating WebLogic Applications to WebSphere Advanced Edition ref. This table details the following important differences between EJB 1.1 and EJB 1.0 for the type, scope, and naming syntax of these references. • env-entry lookups use different APIs — JNDI lookup for EJB 1.1, and EJBContext environment properties for EJB 1.0. • ejb-entry supports different object types — several Java primitive wrapper types for EJB 1.1, but only java.lang.String for EJB 1.0. • env-entry name scope — both global and local for EJB 1.1 (although global scope is not normally supported by deployment tools), but only local scope for EJB 1.0. • ejb-ref and resource-ref name scope — both global and local for EJB 1.1, but only global scope for EJB 1.0. • JNDI names follow different conventions — EJB 1.1 recommends specific context names such as ejb and jdbc, while EJB 1.0 context names are less constrained. In summary, the EJB 1.1 Specification introduced three important improvements that cause migration problems: 1. It integrated the env-entry with JNDI-based deployment parameters by deprecating the EJBContext environment properties and requiring JNDI lookup instead. 2. It expanded support for env-entry object types to include Integer, Boolean, Double, Byte, Short, Long, and Float, in addition to String. 3. It added a JNDI environment naming context (ENC) to the EJB container with the name java:comp/env. With this, JNDI supports both local and global (with respect to the JNDI server) lookups for all object types. Table 7. Deployment parameter lookup APIs and conventions object type EJB 1.1 EJB 1.0 env-entry type: Integer, Boolean, Double, Byte, Short, Long, Float, String. local scope: JNDI lookup by java:comp/env/name. global scope: JNDI lookup by otherContext/name (possible, but not currently specified). type: String. local scope: EJBContext environment properties getProperty(“name”). global scope: not supported. Chapter 7. Enterprise JavaBeans 135 object type EJB 1.1 EJB 1.0 ejb-ref type: EJBHome. local scope: JNDI lookup by java:comp/env/ejb/name. global scope: JNDI lookup by otherContext/ejb/name. type: EJBHome. local scope: not supported. global scope: JNDI lookup by anyContext/ejbName. resource-ref (only JDBC DataSource resource shown) type: DataSource. local scope: JNDI lookup by java:comp/env/jdbc/name. global scope: JNDI lookup by otherContext/jdbc/name. type: DataSource. local scope: not supported. global scope: JNDI lookup by anyContext/jdbc/name. 7.4.1 env-entry lookups The following code is an example of an EJB 1.1 env-entry lookup. It reads a local Boolean env-entry parameter named sendMail. InitialContext ic = new InitialContext(); Boolean send = (Boolean)ic.lookup(“java:comp/env/sendMail”); if (send.booleanValue()) { ... } In an EJB 1.0 container, the corresponding lookup uses the EJBContext environment properties. Properties env = ejbContext.getEnvironment(); String boolString = env.getProperty(“sendMail”); Boolean send = new Boolean(boolString); if (send.booleanValue()) { ... } By comparing these two examples, the required changes are: • Use the EJBContext environment properties instead of the InitialContext and JNDI. • Use the name sendMail instead of java:comp/env/sendMail for lookup. • Convert the retrieved Properties String value to a Boolean object. Making these changes by hand is error prone. Doing them mechanically is moderately complicated, especially when variations on this example are considered. Therefore, we developed a simpler and more reliable way to implement these modifications. We replaced the InitialContext with a wrapper, called InitialContextMigrate, that has access to the EJBContext environment properties. The lookup method of this helper class retrieves the appropriately named deployment 136 Migrating WebLogic Applications to WebSphere Advanced Edition parameter from the environment properties, and converts it to the correct type. The migrated code looks almost identical to the original EJB 1.1 code. InitialContextMigrate ic = new InitialContextMigrate(ejbContext); Boolean send = (Boolean)ic.lookup(“java:comp/env/sendMail”); if (send.booleanValue()) { ... } The type of the deployment parameter is specified as the first token on the deployment String. For our example, you would specify the following in the deployment tool: parameter name: parameter value: sendMail Boolean false For more information on the InitialContextMigrate helper class, see 9.3.3, “JNDI ENC changes” on page 200. 7.4.2 ejb-ref and resource-ref lookups EJB 1.1 introduced the JNDI environment naming context (ENC) with the default context name java:comp/env. Entries in this naming context are scoped locally to the EJB. Different EJBs can use the same name to deploy completely unrelated parameter values. This scoping is the same as that of the EJB 1.0 environment properties. Indeed, the solution to env-entry lookups, described in 7.4.1, “env-entry lookups” on page 136, exploits this fact. An env-entry with the JNDI name java:comp/env/sendMail is looked up in the local EJB 1.0 environment properties under the name sendMail. In effect, the EJB 1.0 environment properties implement the JNDI ENC for enventry objects. So our only remaining JNDI problem is to simulate its ENC for ejb-ref and resource-ref objects in an EJB 1.0 container. We consider several alternatives: • Manually manage the global JNDI name space to avoid conflicts. • Provide indirection using the EJB 1.0 environment properties. • Deploy with full ENC names. 7.4.2.1 Manage the global JNDI name space One approach to avoiding name conflicts is to employ an application-oriented unique naming convention for ejb-ref and resource-ref objects across all applications. This is not a new idea. Indeed, this is the default policy for an EJB 1.0 environment. For example, assume two unrelated applications both use the JNDI name java:comp/env/jdbc/myDB to refer to different databases. You simply modify Chapter 7. Enterprise JavaBeans 137 the code for at least one of them to use a different JNDI name. More generally, you partition your JNDI name space by application names, for example java:comp/env/applName/resourceName, and modify all applications to use this convention. The downside to this alternative is that you must modify precisely that source code that deployment descriptors are supposed to make portable without source code modifications. 7.4.2.2 Indirection via environment properties This alternative simulates the JNDI ENC by using the EJB 1.0 environment properties to avoid conflicts for ejb-ref and resource-ref objects. Instead of changing the JNDI names already in the code, use additional env-entry deployment parameters to provide unique aliases for these names. The code for the myDB example above would look like the following: Properties env = ejbContext.getEnvironment(); String alias = env.getProperty(“java:comp/env/jdbc/myDB”); InitialContext ic = new InitialContext(); DataSource db = (DataSource)ic.lookup(alias); Two deployment parameters are required for this approach:. env-entry resource-ref java:comp/env/jdbc/myDB jdbc/AccountDB jdbc/AccountDB someDataSource At first glance, this looks like a bigger coding change than just changing the names directly. However, by encapsulating the required alias lookup code in the InitialContextMigrate class, a simpler solution results. This solution uses the original JNDI names, and supports future name changes without recompilation. InitialContextMigrate ic = new InitialContextMigrate(ejbContext); DataSource db = ( DataSource)ic.lookup(“java:comp/env/jdbc/myDB”); See 9.3.3, “JNDI ENC changes” on page 200 for additional details on the InitialContextMigrate helper class. 7.4.2.3 Deploy with full ENC names After doing the above analysis, we had the bright idea of simply using the full JNDI ENC names for deployment. To our surprise, these names worked unchanged in WebSphere. This is indeed the simplest approach, requiring no source code changes at all! Assuming that an EJB 1.1 has the following code: 138 Migrating WebLogic Applications to WebSphere Advanced Edition InitialContext ic = new InitialContext(); Object objref = ic.lookup(“java:comp/env/ejb/account“); AccountHome acct = (AccountHome) PortableRemoteObject.narrow(objref, AccountHome.class); You would use a deployment parameter such as the following in an EJB 1.1 container:. ejb-ref ejb/account estore.account.ejb.AccountHome The name used for deployment does not include the ENC of java:comp/env. In effect, the ENC gets added for you by the deployment tool. But what happens if you deploy the same code into a WebSphere EJB 1.0 container using the following deployment parameter for the referenced AccountEJB? ejbHome java:comp/env/ejb/account estore.account.ejb.AccountHome The answer is that it works! We did not investigate the details of the actual JNDI contexts, but presume that java:comp is the top level context, followed by env and ejb. Of course, this JNDI name is actually a global name and must be managed for potential conflicts. For many migration projects, this may be the most expedient solution. The InitialContextMigrate class also allows you to strip the ENC prefix from JNDI lookup names. This is useful for converting ENC resource-ref names into global DataSource names. We used this approach with the Java Pet Store in 9.4.1.3, “Create EJB deployment descriptors” on page 212. 7.5 Deployment descriptors replaced EJBs are deployed into their containers in accordance with deployment descriptors. Deployment descriptors are specified after an EJB is compiled and before it is deployed. They bind the EJB to its operational environment, specifying the values of JNDI names and environment properties. Deployment descriptors underwent major revisions between the EJB 1.0 and EJB 1.1 Specifications. Their implementation, structure, and content changed. The EJB 1.0 deployment descriptors are deprecated and are not supported in EJB 1.1. • javax.ejb.deployment package replaced by XML-based descriptors EJB 1.0 deployment descriptors are serialized instances of classes in the javax.ejb.deployment package. These classes include EntityDescriptor, SessionDescriptor, ControlDescriptor (for method transaction attributes), and AccessControlEntry (for method security attributes). An EJB 1.0 deployment tool captures deployment parameters as instances of these Chapter 7. Enterprise JavaBeans 139 classes. It then serializes them and includes them in the ejb-jar file, ready for deployment. EJB 1.1 deployment descriptors are XML files that conform to the EJB 1.1 DTD. An EJB 1.1 deployment tool captures deployment parameters as XML elements. The XML elements form the content of an ejb.xml file that is added to the ejb-jar, ready for deployment. For our purposes, one important advantage of the XML-based deployment descriptors is that they can be read with an ordinary editor. • Content of descriptors expanded EJB 1.1 deployment descriptors include all of the EJB 1.0 deployment parameters in addition to some new ones. The common descriptors include: - Names, classes, and JNDI names for an EJB and its interfaces. - EJB type — entity or session. - Re-entrancy indication. - SessionBean’s state management and transaction demarcation. - EntityBean’s persistence management, primary key, and CMP fields. - Environment properties. - Transaction attributes for each method (expanded with Never attribute). - Security attributes for each method (these changed significantly). The new descriptors also include: - Resource manager Connection factory references (resource-ref). - EJB references (ejb-ref). • Vendor-customization standardized One of the problems with the EJB 1.0 deployment descriptor classes is that there is no standard way to extend them for vendor-specific deployment parameters. Subclasses do not work well because it is not possible to read a serialized object without the vendor-specific subclass definitions. The EJB 1.1 XML-based deployment descriptors solve this problem by allowing separate vendor-specific XML files to be added to the deployed JAR file. The standard XML DTD cannot be modified, making it completely portable. 140 Migrating WebLogic Applications to WebSphere Advanced Edition From the perspective of migrating EJBs from WebLogic to WebSphere, how best can we use EJB 1.1 deployment descriptors? Can they be used to construct the required EJB 1.0 deployment descriptors? We investigated three approaches.: 1. Automatically convert the EJB 1.1 XML descriptors into EJB 1.0 serialized descriptors. 2. Use the EJB 1.1 XML descriptors as a written specification for entering corresponding descriptors into an EJB 1.0 deployment descriptor tool. 3. Ignore the EJB 1.1 descriptors altogether, constructing EJB 1.0 deployment descriptors from scratch with an EJB 1.0 deployment descriptor tool. The first option is technically feasible. We did try an early version of one such tool. Time constraints kept us from pursuing this option further. One problem was that we did not discover a good way to import a serialized EJB 1.0 descriptor into a deployable JAR file, in particular into the VisualAge for Java environment. We settled on a combination of the last two options. We worked with several deployment descriptor tools including WebSphere, VisualAge for Java, and jetace. Each of these tools does a pretty good job of introspecting on EJB classes and interfaces. This gets you more than half way to a complete deployment descriptor. It helps that the EJB 1.0 descriptors are simpler. For example, they do not require explicit ejb-ref and resource-ref entries. The few remaining parameters, mostly env-entry parameters, can be obtained manually from the EJB 1.1 XML descriptor file. See 9.4.1.3, “Create EJB deployment descriptors” on page 212 for an example of this approach for the Java Pet Store. 7.6 Finders expanded to Collection If your application has a Finder method that returns the java.util.Collection type, you must modify it to use the Enumeration type before it will deploy properly under WebSphere 3.5. An EJBEntity Home must have one or more Finder methods. A Finder method may return a reference to a single EJB or a collection (with zero or more elements) of EJB references. The EJB references must be the same type as that of the Finder’s EJB. This is implemented in the ejbFinder method by returning a collection of the EJB’s primary keys. The container converts the collection of primary keys into a collection of EJBObjects that are returned to the client. Chapter 7. Enterprise JavaBeans 141 The EJB 1.0 Specification supports java.util.Enumeration as the only type for a collection-returning Finder method. The EJB 1.1 Specification added the Java 2 java.util.Collection type as a legal Finder return type. This means that the following EJB 1.1 Finder method requires modification to work with WebSphere 3.5. public Collection ejbFindOrders(String uid) throws FinderException { try{ dbConnection = getDBConnection(); ArrayList orderIdList = new ArrayList(); Statement stmt = dbConnection.createStatement(); ResultSet result = stmt.executeQuery(userOrderSelect(uid)); if ( !result.next() ) { stmt.close(); throw new SQLException ("No Orders found”); } else { do { orderIdList.add( new Integer(result.getInt(1)) ); } while (result.next()); return orderIdList; // list of Order primary keys } } catch (java.sql.SQLException se) { throw new FinderException ("SQL Exception in finding"); } finally { try { dbConnection.close(); } catch (SQLException se) { throw new FinderException ("SQL Exception in finding "); } } } The problem is that although the WebSphere JDK supports the Java 2 Collection type, the WebSphere container and deployment tools, in keeping with the EJB 1.0 Specification, do not support Collection-returning Finder methods. This means that the above code will compile under the WebSphere JDK, but will fail to deploy properly. Moreover, the error message issued during deployment is not very helpful for discovering the problem. 7.6.1 Convert Collection Finder to Enumeration Finder There is only one reasonable alternative to solving this migration problem. You should use Enumeration in place of Collection. Fortunately, this is easy to do, and only requires localized code changes. 142 Migrating WebLogic Applications to WebSphere Advanced Edition On the server side, you must convert the returned Collection to an Enumeration. On the client side, you must convert the Enumeration back to a Collection. The only option you have is in your choice of the Collection implementation type — we chose Vector in this example. Here are the conversions expressed as methods: public static Collection convertEnumeration(Enumeration enum) { Vector v = new Vector(); while (enum.hasMoreElements()) { v.add(enum.nextElement()); } return v; } public static Enumeration convertCollection(Collection col) { return new Vector(col).elements(); } Implementation of this modification affects the EJB implementation, its Home interface, and all clients that use the Finder method. An easy way to locate all client uses is to modify the Home interface and recompile. The compiler errors pinpoint the client changes. For the above example, we need to do the following: • Modify the EJB method to return an Enumeration. public Enumeration ejbFindOrders(String uid) throws FinderException { try{ ArrayList orderIdList = new ArrayList(); ... return convertCollection(orderIdList); // Order primary keys ... } • Modify the Home interface Finder method declaration to return an Enumeration. public Enumeration findOrders(String uid) throws FinderException, RemoteException; • Modify all client uses to convert back to a Collection. Collection orders = convertEnumeration(home.findOrders(“Bill”)); This technique was tested with the Java Pet Store application. See 9.3.6, “Collection finder changes” on page 207 for further details. Chapter 7. Enterprise JavaBeans 143 7.7 HomeHandle added A javax.ejb.Handle object provides a robust, long-lived, persistent reference to an EJB object. It is serializable, so it can be written to, and read from Streams. Its useful lifetime spans client sessions and server restarts, and possibly even server upgrades. Although not guaranteed to be deserializable from different systems, it may even work across systems. Both the EJB 1.0 and EJB 1.1 Specifications support Handle objects. EJB 1.1 introduced javax.ebj.HomeHandle with the same capabilities for EJB Homes. Since EJB 1.0 does not support HomeHandle, applications that use HomeHandle have a migration problem for WebSphere 3.5. There is no simple replacement for this capability in an EJB 1.0 system. Normally an EJBHome object is obtained by a JNDI lookup. A HomeHandle allows the same object to be obtained without knowing its JNDI name. In this example, a HomeHandle has previously been written to someStream: public AccountHome getAccountHome () throws RemoteException, IOException, ClassNotFoundException { HomeHandle homeRef = (HomeHandle)someStream.readObject(); AccountHome home = (AccountHome)ProtableRemoteObject.narrow (homeRef.getEJBHome(),AccountHome.class); return home; } Since HomeHandles can be obtained indirectly from EJBObjects, as in the following example, there are programs that use HomeHandles with no knowledge of the underlying JNDI name: public void saveAccountHome(EJBObject obj) throws RemoteException, IOException { AccountHome home = (AccountHome)ProtableRemoteObject.narrow (obj.getEJBHome(),AccountHome.class); HomeHandle homeRef = home.getHomeHandle(); someStream.writeObject(homeRef); } 7.7.1 Use JNDI names in place of HomeHandles If you plan to migrate a program with HomeHandles, it will require a redesign to preserve the JNDI name instead of the HomeHandle. One approach would be to add a business method to the EJB itself that returns the JNDI name for the EJB Home. This method could use an EJB environment property for the JNDI name to make the code portable. With this approach, the above example is converted without using a HomeHandle object. 144 Migrating WebLogic Applications to WebSphere Advanced Edition public interface AccountHome extends EJBHome { ... public String getJNDIName() throws RemoteException; } public void saveAccountHome(EJBObject obj) throws RemoteException, IOException { String jndiName = obj.getJNDIName(); someStream.writeObject(jndiName); } public AccountHome getAccountHome () throws RemoteException, IOException, ClassNotFoundException { String jndiName = (String)someStream.readObject(); InitialContext ctx = new InitialContext(); AccountHome home = (AccountHome)ProtableRemoteObject.narrow (ctx.lookup(jndiName),AccountHome.class); return home; } We did not test this solution. 7.8 CMP ejbCreate change In the EJB 1.0 Specification, the ejbCreate methods for EJBEntity objects follow two different rules, depending on whether they are for CMP or BMP entities: • A CMP ejbCreate must return void. public void ejbCreate() throws CreateException { ... } • A BMP ejbCreate must return the primary key type. As an example, assume an OrderEJB with an Integer primary key class. public Integer ejbCreate () throws CreateException { ... return new Integer(...); } The problem with this specification is that it makes it impossible to extend a CMP entity with a BMP entity or vice versa. You cannot change the return type on an overridden method, ejbCreate in this case. The EJB 1.1 Specification corrected this difficulty by requiring all EJBEntity ejbCreate methods to return the type of their primary key, even for CMP entities. CMP ejbCreate methods simply return null. For example: public interface CMPOrderHome extends EJBHome { ... } Chapter 7. Enterprise JavaBeans 145 public interface BMPOrderHome extends CMPOrderHome { ... } public class CMPOrderEJB implements EJBEntity { ... public Integer ejbCreate() throws CreateException { ... return null; } } public class BMPOrderEJB extends CMPOrderEJB { ... public Integer ejbCreate() throws CreateException { ... return new Integer(...); } } The above code will compile with the WebSphere JDK, but it will not deploy properly into the WebSphere container. You must identify all CMP entities in your application, and make the necessary modifications before deployment. Only the EJBs need to be changed. No changes are required to the Home interfaces or client code. We considered two different migration cases: 1. If there is no inheritance, the simplest solution is to revert to the EJB 1.0 convention for CMP ejbCreate methods. 2. If there is inheritance, as in the above example, you can preserve the original code (including its inheritance) as non-EJB implementation classes, and use inheritance to create simple replacement EJBEntity classes. The replacement EJBEntity classes inherit most of their code from the implementation classes, and provided the appropriate EJB 1.0 ejbCreate methods. We show examples for both cases. We did not test these examples. 7.8.1 Revert to the EJB 1.0 CMP ejbCreate rule For the above CMPOrderEJB example (without the inheritance), we have to make the following modifications. Change the Integer return type to void and remove the return value. public class CMPOrderEJB implements EJBEntity { ... public void ejbCreate() throws CreateException { 146 Migrating WebLogic Applications to WebSphere Advanced Edition ... return ; } } 7.8.2 Use inheritance from implementation objects For the above BMPOrderEJB example (with its inheritance), we make the following modifications. Convert the original BMPOrderEJB tree into a nonEJB implementation tree by removing its implements clause. The ejbCreate methods get new names so they do not conflict with the new EJBEntity classes. Replace the original BMPOrderEJB and CMPOrderEJB classes with simple EJBEntity classes that extend the appropriate level of the implementation tree. The new ejbCreate methods follow the EJB 1.0 return type rule, and they are the only new methods required. The original Home interfaces remain unchanged. public class CMPOrderImpl { ... public Integer ejbCreateImpl() throws CreateException { ... return null; } } public class BMPOrderImpl extends CMPOrderImpl { ... public Integer ejbCreateImpl() throws CreateException { ... return new Integer(...); } } public class CMPOrderEJB implements EJBEntity extends CMPOrderImpl { public void ejbCreate() throws CreateException { ejbCreateImpl(); return ; } } public class BMPOrderEJB implements EJBEntity extends BMPOrderImpl { public Integer ejbCreate() throws CreateException { return ejbCreateImpl(); } } Chapter 7. Enterprise JavaBeans 147 7.9 Transaction changes There are two minor changes to transaction support between EJB 1.0 and EJB 1.1 that affect our migration tasks: 1. The EJB 1.0 package name javax.jts was changed to the EJB 1.1 package name javax.transaction. This package is used primarily for the UserTransaction class. If you miss this modification, don’t worry because the compiler will catch it for you. 2. The Never transaction attribute was added to EJB 1.1. It requires that the container throw the RemoteException if a client calls the method with a user transaction context. Otherwise it works just like the NotSupported transaction attribute. The first of these changes is trivial. Just change the package name back to the EJB 1.0 standard of javax.jts and recompile. There is no EJB 1.0 transaction attribute that is equivalent to the new Never attribute. The NotSupported attribute is the closest alternative. It is weaker than Never, but is equivalent for all applications that follow the restriction that they have no client transaction context when calling the associated method. Use the NotSupported transaction attribute. 7.10 Authentication method changes The java.security.Identity class is deprecated in the Java 2 JDK. As a result, two methods on the EJBContext object changed between the EJB 1.0 and the EJB 1.1 Specifications: • The getCallerIdentity() method was deprecated in favor of the new getCallerPrincipal() method. • The isCallerInRole(Identity) method was deprecated in favor of the new isCallerInRole(String) method. If your application compiles without errors for these methods, then you do not have to worry about this problem. This means that either: 1. Your application uses neither the Principal nor the Identity authentication methods, or 2. Your application uses the Identity authentication methods. These methods are deprecated, but are still supported by WebLogic 5.1, so they are probably in existing WebLogic applications. 148 Migrating WebLogic Applications to WebSphere Advanced Edition In the first case, you are home free. In the second case, even though your application compiles, it may not run properly until you activate the WebSphere authentication features. See the redbook WebSphere V3.5 Handbook, SG24-6161 for information on activating WebSphere authentication. 7.10.1 Replace Principal with Identity The most common use of the getCallerPrincipal method is to obtain a group or user name for reporting purposes. String userId = ejbContext.getCallerPrincipal().getName(); This use migrates trivially to the EJB 1.0 standard by replacing Principal with Identity: String userId = ejbContext.getCallerIdentity().getName(); The isCallerInRole method is more problematic. The EJB 1.1 version of this method takes a String as an argument, while the EJB 1.0 version takes an Identity object. In both cases, the method checks to see if the current caller is in the group or role specified by the argument. An example of the Principalbase method follows: boolean member = ejbContext.isCallerInRole(“Manager”); When using the EJB 1.0 Identity version of the isCallerInRole method, it is unclear how to construct the required Identity argument. If you try the following obvious conversion, you get a compiler error: boolean member = ejbContext.isCallerInRole(new Identity(“Manager”)); The problem is that the Identity class is abstract. All of its methods are defined, but it is explicitly marked as abstract. This is because the Identity class is designed to be extended with additional identification fields, and to override the identityEquals method. The following alternative compiles: boolean member = ejbContext.isCallerInRole(new MyIdentity(“Manager”)); where, public class MyIdentity extends Identity { public MyIdentity (String role) { super(role); } } We did not get to test this thoroughly, but believe that with the appropriate activation of WebSphere authentication features, this code also executes as expected. For some additional comments on this approach, see http:// www.javaworld.com/javaworld/jw-01-2000/jw-01-ssj-ejb2.html. Chapter 7. Enterprise JavaBeans 149 7.11 Read-only EntityBeans Performance of the persistence support for EntityBeans can be improved significantly if the container is told about read-only operations. If an entity has not been updated, there is no need to write it back to the database. Interestingly, this important performance feature is not part of either the EJB 1.0 or the EJB 1.1 Specification. However, both WebLogic and WebSphere provide vendor-specific ways to specify this information. • WebLogic uses a runtime approach. Each EntityBean has an isModified method that returns Boolean. The WebLogic container calls this method to determine when to update the underlying database. • WebSphere uses a declarative approach, consistent with existing transaction attribute deployment parameters. The read-only attribute can be specified in the VisualAge for Java EJB deployment tool. It cannot, however, be specified in the jetace tool. The read-only attribute is specified at the method level for each method that does not change the EntityBean. 7.11.1 Use read-only method attributes The WebLogic isModified methods are ignored in the WebSphere container, so there is no need to change or remove them. To get the best performance from the WebSphere container, use the readonly method attribute. Unfortunately, deciding which methods are read-only and which are not may be nontrivial. Remember that the WebLogic isModified methods determine this dynamically at runtime, while the WebSphere readonly method approach is a static declarative determination. You will have to study how the existing isModified methods work. Depending on the design of your EJBs, this may or may not map cleanly to the statically specified readonly attributes. 7.12 Non-issues During the process of identifying EJB migration issues, we studied many specification changes that do not appear to cause migration issues. For completeness, and possibly to set your own mind at ease, we document them here. We separate them into two lists, tightenings and clarifications. A tightening is where something that is legal in EJB 1.0 is no longer legal in EJB 1.1. A clarification is something that did not actually work, or was never intended to work, but was not covered explicitly or clearly in the EJB 1.0 Specification. Assuming that your application is consistent with the EJB 1.1 150 Migrating WebLogic Applications to WebSphere Advanced Edition Specification, a clarification cannot give rise to a migration issue from WebLogic to WebSphere. Some of the tightenings were bad ideas in the first place, and are therefore not in common practice. In other cases, they represent real restrictions that required EJB modifications when moving from EJB 1.0 to EJB 1.1. In all cases, however, what is specified in the EJB 1.1 Specification should work in the WebSphere EJB 1.0 container. For that reason, they also cause no migration issues. 7.12.1 Tightenings • hashCode and equals methods required Primary keys require hashCode and equals methods. • FinderException required EJBEntity Finder methods must throw the FinderException. • Use of finalize method outlawed The finalize method must not be specified for any EJB. • Use of this variable tightened An EJB must not pass the this variable as an argument or a result. The EJBContext getEJBObject method should be used instead. • Use of == and equals tightened The == operator and the equals method are not defined for EJB references. • Use of PortableRemoteObject.narrow tightened PortableRemoteObject.narrow must be used for Handle.getEJBObject and for portable EJB clients. • Bean transactioning must be specified The bean provider must specify either bean-managed or containermanaged transactioning for SessionBeans. • Transaction management tightened Transaction management responsibilities have been tightened generally. • UserTransaction outlawed in EntityBean EntityBeans must not use UserTransaction and EntityBeans cannot specify TX_BEAN_MANAGED. Chapter 7. Enterprise JavaBeans 151 • SessionSynchronization tightening A SessionBean can use either SessionSynchronization or UserTransaction, but not both. That is, SessionSynchronization is disallowed for TX_BEAN_MANAGED. • Transaction isolation level restricted Only SessionBeans are allowed to manage transaction isolation level. • Use of setRollbackOnly and getRollbackOnly restricted The setRollbackOnly and getRollbackOnly methods are only legal with bean-managed transactioning. • IllegalException expanded The IllegalException is thrown for the getUserTransaction, setRollbackOnly, and getRollbackOnly methods when they are not allowed. • Use of UserTransaction tightened The container must provide UserTransaction interface in JNDI context java:comp/UserTransaction. • EJB runtime container rules tightened Container runtime rules have been tightened generally for JNDI, JTA, Java 2, and JDBC support. • SessionBean identity tightened SessionBean behaviors for primary key, remove, and isIdentical methods have been tightened. • Containers must support EntityBeans This is not a problem for WebSphere 3.5 because it supports EntityBeans with the EJB 1.0 Specification. 7.12.2 Clarifications • An EJB can have a superclass This is not a problem in WebSphere 3.5 because it already supports EJB subclassing. • Primary key can be java.lang.String This is not a problem in WebSphere because it already supports String primary keys. 152 Migrating WebLogic Applications to WebSphere Advanced Edition • Non-public, final, abstract, and static restricted Non-public, final, and abstract EJB classes and static ejbCreate methods are not allowed. • ejbCreate/ejbPostCreate pairs required The ejbCreate and ejbPostCreate methods must be specified as matched pairs. • Transient fields outlawed CMP fields cannot be transient. • EJB allowed to print We actually did not test this in WebSphere 3.5. • Non-remote references restricted Container must not pass non-remote objects by reference, even between containers in the same JVM. Chapter 7. Enterprise JavaBeans 153 154 Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 8. Database connectivity and persistence This chapter describes the different methods and technologies you could use in WebLogic to access persistent data in a database and how these should be migrated to WebSphere. It is beyond the scope of this book to cover all these technologies in detail. We focus on the JDBC API, which is a core part within the Java 2 Platform, Enterprise Edition. We will also look at persistence products from other vendors that you may encounter when migrating applications, and consider the future direction of persistence solutions as detailed in the Enterprise JavaBeans 2.0 Specification. 8.1 Introduction Object persistence is a major topic in every enterprise application and because persistence efforts always take a lot of time, you will find many products and tools that promise to raise the productivity and lower the maintenance costs. Many approaches can be used for persistent data access, but we expect that not all these approaches will be used in the future, as efforts to standardize functionality become more successful. See the EJB 2.0 and JDBC 3.0 Specifications from Sun Microsystems for more details of proposed future directions. The JDBC API has been established as the industry-standard interface for Java applications to access databases. Nearly all leading database and middleware vendors support JDBC technology. It is also a key technology in the J2EE architecture and thus supported by both WebLogic and WebSphere application servers. JDBC has been widely accepted by the developer community, so you find many applications based on the pure JDBC API. Both WebSphere as well as WebLogic support the JDBC 2.0 standard, while JDBC 1.0 drivers still can be used. These applications should not present any major migration difficulties. There are many high-level technologies and frameworks based on JDBC, mainly to provide a higher level of abstraction than JDBC does. The product dbKona/htmlKona, which is shipped and supported by WebLogic, is such a class library. It was provided with the intention to simplify JDBC programming, for instance by automatically generating SQL with the consideration of vendor-specific details. The new features of JDBC 2.0 have meant that most of the previous dbKona/htmlKona benefits, such as caching, shared query results, better support for displaying results in table views, are now supplied by the base JDBC API. We expect that most developers will use the core © Copyright IBM Corp. 2001 155 JDBC features, and that the role of proprietary extensions will become less significant. The market also offers many sophisticated persistence frameworks, which provide complex mapping from objects to data stores, mostly relational databases. Nearly all of them are built on top of the JDBC API, which guarantees a high degree of platform and database vendor independence. These type of products can be compared with what the Enterprise JavaBeans specification says about entity beans, particularly about entity beans with container-managed persistence (CMP). Entity beans support in EJBcompliant products has been demanded only since the EJB 1.1 Specification, so it is fairly new. The latest EJB 2.0 Specification has many improvements for the CMP bean type. Given the limitations of the early EJB support for CMP, there are a lot of tools available that offer persistency mapping for fine-grained objects. These tools are far more comprehensive and typically provide more features than can be supported with the current EJB 1.0/1.1 implementations. The Object People (recently acquired by WebGain) offers their product TOPLink for BEA WebLogic, which integrates the persistence product TOPLink into the WebLogic Server. It is likely that you will encounter TOPLink when migrating WebLogic applications, since it is a successful tool with wide acceptance. TOPLink is used not only for fine-grained objects and for entity beans with bean-managed persistence (BMP), but is also a sophisticated implementation for CMP entity beans, with features beyond the EJB 1.1 standard. WebSphere does not provide full compliance with the EJB 1.1 standard (see Chapter 7, “Enterprise JavaBeans” on page 127 for a discussion of these issues), but the WebSphere EJB 1.0+ implementation offers some functionality, which already goes towards the EJB 2.0 Specification. 8.2 JDBC JDBC is an API that provides a uniform programming interface to access different forms of tabular data such as databases, spreadsheets, flat files and so on. Because of the platform independence provided by Java, JDBC provides a platform-independent access to databases. JDBC makes use of the remote object features in Java (RMI) and thus enables database location transparency. You can also make use of techniques to make proprietary database issues transparent. Both application server products, WebSphere as well as WebLogic, support the JDBC 2.0 API standard. Therefore, you should not have to use any 156 Migrating WebLogic Applications to WebSphere Advanced Edition specific packages of the application server vendor anymore, but only the standard interfaces (java.sql.* and javax.sql.*). This makes code portable between the servers. Until quite recently both servers had their individual way of pooling database connections, to share them between applications and thus avoiding the need to wait until a new database connection is established, which is a fairly expensive task. With the introduction of DataSources and pooled DataSources, both products can use the JDBC 2.0 Optional Package API standard for doing this in a uniform way. There are some slight differences, which we describe in this chapter. Both products have partnerships with several database vendors and they ship and support their JDBC drivers. Nevertheless it should still be possible to use any JDBC 1.0/2.0-compliant driver from another vendor. We detail some potential problems in this chapter. Another field where the middleware has to cooperate with the JDBC API is in the support for distributed transactions. The JDBC 2.0 Optional Package API also defines standards here and provides for a two-phase commit (2PC) protocol. We tested that 2PC worked correctly and in the same way in both servers. 8.2.1 DataSource The DataSource specification and interfaces are part of the JDBC 2.0 Optional Package API. A DataSource can be seen as a representation of a particular DBMS or some other data source, such as a file. A DataSource is simply a factory for JDBC connections. The previous means (JDBC 1.0) to get a connection to the database was via the JDBC DriverManager or in WebSphere also with the IBM Connection Manager (for connection pooling). With that approach the particular driver and database had to be hardcoded. At least some developers used properties files and a generic way to introduce new JDBC drivers. But now with the specification of DataSources, developers have a standard abstract way of obtaining database connections by using just a logical name. The physical settings for the JDBC driver are set and updated by an administrator. This makes code more portable and uniform, and eases maintenance and deployment of JDBC applications. Figure 51 on page 158 illustrates the uses of a DataSource to connect to a database. Chapter 8. Database connectivity and persistence 157 JNDI Naming Service lookup( ) Application jdbc/example DS Na me ame Data Source eN r Se rve JDBC Driver ber Descr um ion ipt Port N getConnection( ) as Datab Database Figure 51. Connecting to a DataSource WebSphere and WebLogic both offer support for generic JDBC 2.0 compliant DataSources. Through their administration tools it is possible to set up DataSources and bind them to the JNDI naming service of the server. In both servers it is still possible to run applications using the old approach via the JDBC DriverManager, and the Connection Manager is still supported in WebSphere. But the preferred way of getting database connections is now a DataSource. You are encouraged to use DataSources, since the DriverManager and the ConnectionManager interfaces will be deprecated in the future. According to the specification of the JDBC 2.0 Optional Package API, implementations of javax.sql.DataSource may be provided by JDBC driver vendors as part of their JDBC 2.0 products. WebLogic does not provide any assistance in incorporating DataSource implementations from other vendors and for binding them into the name space. WebSphere provides specific DataSource implementations from supported database vendors, including DB2, Oracle, and Sybase. For other database vendors, WebSphere uses a generic DataSource implementation similar to that used by WebLogic. Generic DataSource implementations offer a way to utilize JDBC classes from other vendors still at the Driver class level. This means that the 158 Migrating WebLogic Applications to WebSphere Advanced Edition application administrator either has to integrate a foreign DataSource or needs to get a foreign driver working with the generic DataSource. The application developer is not impacted by the implemention of the DataSource and is able to write highly portable code. There are slight nuances in the implementations provided by WebLogic and WebSphere, which could force you to change the code when migrating from one vendor to the other. 8.2.1.1 Binding a DataSource to a naming service To create a DataSource object within WebLogic, you define it in the weblogic.properties file. DataSources always point to a connection pool, which is also defined in the properties file. For example a DataSource named jdbc/EstoreDB would be defined by adding the following line to the weblogic.properties file: weblogic.jdbc.DataSource.weblogic.jdbc.EstoreDB=EstorePool If your DataSource has to support Java Transaction Services (JTS), then you must use a connection pool with a JDBC driver supporting JTS. The following line would add a JTS enabled DataSource (TXDataSource) with the logical name jdbc/EstoreDB_TX. weblogic.jdbc.TXDataSource.weblogic.jdbc.EstoreDB_TX=EstorePool Regarding the naming of DataSources, the JDBC 2.0 Optional Package API Specification from Sun Microsystems states the following: “The JDBC 2.0 API specifies a simple policy for assigning JNDI names to data sources. All JDBC data sources should be registered in the JDBC naming subcontext of a JNDI name space, or in one of its child subcontexts. The parent of the JDBC subcontext is the root naming context.” The WebSphere Admin tools, also in the VisualAge WebSphere Test Environment, take the usage of the jdbc naming subcontext as a rule. A WebSphere administrator shouldn’t use the jdbc or jdbc/ subcontext in the DataSource name, as WebSphere already implicitly prepends this subcontext. The data entry validation of the WebSphere Administrative Console recognizes when jdbc/ is entered and will not duplicate it, but in the WebSphere Test Environment you cannot enter jdbc/, but VisualAge always adds jdbc/ to the front of every DataSource name. For example, if in your WebLogic application you used a DataSource name of myJtsDataSource or myNonJtsDataSource, you will have to change this Chapter 8. Database connectivity and persistence 159 logical name when porting to WebSphere, because WebSphere forces you to use the jdbc subcontext. So you would have to use jdbc.myJtsDataSource or jdbc.myNonJtsDataSource in WebLogic to have a portable name. WebSphere does not support the usage of further child subcontexts under jdbc. The JDBC specification states that this should be possible, since the JNDI name space is hierarchical. When you use a logical DataSource name with two subcontexts, for instance jdbc/xa/EstoreDB, in WebLogic you would simply add the line in the weblogic.properties file: weblogic.jdbc.TXDataSource.weblogic.jdbc.xa.EstoreDB=EstorePool WebLogic takes the dot (“.”) as an indication for a new subcontext. However, if you try to use the name xa/EstoreDB in one of the WebSphere administration tools, you will get a NamingException saying that the jdbc/xa/ context was not found. So WebSphere does not automatically create a subcontext under jdbc /. If you use xa.EstoreDB, WebSphere will accept the name, but the dot (“.”) is not recognized as an indicator for a subcontext, but as part of the name. You won’t be able to look up the DataSource using the name jdbc/xa/EstoreDB, but you will have to use jdbc/xa.EstoreDB. So if you want to develop an application portable between WebLogic and WebSphere you should always use a logical DataSource name beginning with the subcontext jdbc/ followed by a simple name without a further subcontext (no dots or following slashes). This applies to the current WebSphere Application Server, Advanced Edition, Version 3.5. However, in a later stage, a J2EE-compliant application should not be affected by the JNDI binding name for the DataSource, since all application code should be doing lookup() calls using the “java:comp/env/jdbc/<...>” resource-ref naming conventions. If coded this way, the application will never be affected by the real JNDI name space location of the DataSource. It becomes the problem of the Application Assembler or Deployer. The J2EE application code will not have to be modified since it should not go directly to the name space for the DataSource, but rather use the indirect resource-ref mechanism. This is already supported in the currently available WebLogic Server, Version 5.1 but not in WebSphere Application Server, Advanced Edition, Version 3.5. 8.2.1.2 Connecting to a DataSource The code sample in this chapter provides a short demonstration of code that will run in WebLogic as well as in WebSphere. 160 Migrating WebLogic Applications to WebSphere Advanced Edition In the class where you want to obtain the DataSource, import the following packages: import javax.sql.*; import javax.naming.*; To obtain a DataSource from the JNDI naming service, you first have to get the root naming context as the initial context. In WebLogic this is done with the following code snippet: { Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "weblogic.jndi.WLInitialContextFactory"); env.put(Context.PROVIDER_URL, "t3://myserver:7001"); try { Context ctx = new InitialContext(env); } catch (NamingException e) { // handle exception } } And for WebSphere it would look like this: { Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.ibm.ejs.ns.jndi.CNInitialContextFactory"); env.put(Context.PROVIDER_URL, "iiop://myserver:900"); try { Context ctx = new InitialContext(env); } catch (NamingException e) { // handle exception } } Chapter 8. Database connectivity and persistence 161 As you can see, both products use different initial context factories. The URLs are less product specific than configuration specific (in WebLogic you can still use their t3 protocol, but now they support IIOP as well). The best practice is to not hardcode those parameters, but get them from an external configurable resource (an environment, a properties-file or another LDAP naming server). If your code runs on the application server (Java Servlets, JSPs, EJBs), you don’t have to pass any environment properties to obtain the right initial context (see next code snippet). After you have the initial context, you can look up the required DataSource. If you bear in mind our recommendation about naming, then you could use the following code snippet in both servers: try { Context ctx = new InitialContext(); DataSource ds = (DataSource) ctx.lookup("jdbc/EstoreDB"); Connection conn = ds.getConnection(); // execute query // process results } catch { // } catch { // } (NamingException e) handle exception (SQLException e) handle exception WebSphere forces you to start the logical DataSource name with jdbc/. In WebLogic you could also use a dot (“.”) instead of the slash (“/”), but this code then would not be portable. The same applies if you would use another child subcontext under jdbc/; then it would not be portable either. Also for the name we recommend not to use hardcoded strings, but rather get it from the environment or another configuration resource. As soon as possible, you shouldn’t use the name of the DataSource directly, but the resource-ref indirection in the deployment descriptor of your component. 162 Migrating WebLogic Applications to WebSphere Advanced Edition 8.2.2 Connection pools Connection pools provide a significant performance gain, since there is an overhead in the process of permanently opening and releasing database connections. With the introduction of the DataSource interface, connection pooling has been abstracted,since there is no difference in the code, whether the DataSource object has just opened a single connection or whether an existing connection has been assigned from a PooledDataSource. The pooling of DataSource connections is driver-independent. You shouldn’t need any server-specific classes or packages any longer to access DataSource connections from a pool. One thing you have to take care of in the code: Always call a close() on the connection you obtain from DataSource.getConnection(), as soon as the connection will not be needed any longer. In this way you do not really close the connection, but rather return it to the pool and make it available for other applications. This is shown in the next code fragment: Connection conn = null; try { DataSource ds = (DataSource) ctx.lookup("jdbc/EstoreDB"); Connection conn = ds.getConnection(); // execute query // process results } catch (NamingException e) { // handle exception } catch (SQLException e) { // handle exception } finally { if (conn != null) conn.close(); } From the developer’s point of view, connection pools work the same way on both servers, but for the administrator there are some differences that need to Chapter 8. Database connectivity and persistence 163 be taken into account. WebSphere and WebLogic offer different tools to create and configure connection pools. WebLogic has slightly more to offer in regards to maintenance. There are more configurable properties, such as capacityIncrement, to set how many connections are added to the pool if the current connections are all reserved. WebLogic thus has more scope for performance tuning in this area. It also has a finer grained system for security in administrative tasks (access control list support). WebLogic also offers a so-called multi-tier driver, or WebLogic JDBC/RMI driver. It is what is called a JDBC type 3 driver, which uses a network server to relay or proxy the JDBC requests onto the database. Only the network server is directly connected to the database with another database-specific driver. The clients don’t have to use native code, but only use the slim pureJava driver. With the WebLogic JDBC/RMI driver the client remains completely independent of the driver that is used on the server. WebSphere doesn’t offer such a generic driver, but it is possible for applets and application clients to get database connections from the server if you use the DB2net-driver. DB2 in its package includes the net-driver, which is basically a type 3 driver (COM.ibm.db2.jdbc.net.DB2Driver). We had problems trying to use the WebLogic JDBC/RMI driver in WebSphere, because the WebLogic driver needs specific property settings, which can’t be set using WebSphere. 8.2.3 Available drivers WebSphere Application Server, Advanced Edition V3.5 supports the following database systems: • DB2 • InstantDB • Oracle 8i • Sybase InstantDB is supplied as a solution for users who do not have database software available for use as a configuration repository. It is not recommended for application usage and does not support EJB CMP, or JTA. Periodically new drivers may be added to the supported list. Please refer to the online product documentation to see the most recent list. For WebSphere Application Server software prerequisites, go to : http://www-4.ibm.com/software/webservers/appserv/doc/v35/a_as.htm 164 Migrating WebLogic Applications to WebSphere Advanced Edition This does not mean that you cannot use any JDBC 1.0/2.0-compliant drivers supplied by other database vendors for use in Java Servlets or EJB BMP, but you will have to evaluate and confirm the suitability of those drivers. For instance we tried to use the Cloudscape JDBC driver, which is shipped with the WebLogic Server. 8.2.3.1 Introducing a JDBC driver in VisualAge for Java In the WebSphere Test Environment Control Center only a few preconfigured JDBC drivers are available in a drop-down combobox list, when you try to configure a DataSource. The combobox is not editable, so it is not possible to introduce a new JDBC driver via the user interface. You have to edit the file <VAJava_root>\ide\tools\com-ibm-ivj-uiwebcontrolcenter\com\ibm\ivj\control\dbdrivers.properties and append the class name of the new JDBC driver with its full package name. The drivers are separated by a semicolon. For our example with Cloudscape, we added COM.cloudscape.core.JDBCDriver. Restart the WebSphere Test Environment and the new driver will be available for selection in the combobox. The procedure for configuring a DataSource is described in 4.1.3.3, “DataSource configuration” on page 69. For our Cloudscape driver we selected COM.cloudscape.core.JDBCDriver from the combobox. We entered jdbc:cloudscape:petStoreDB as the URL and selected JDBC as the database type. We had to add: D:\weblogic\eval\cloudscape\lib\cloudscape.jar; to the Workspace classpath in VisualAge for Java. For an EJB developer there is an alternative way to set the JDBC driver within the WebSphere Test Environment. When the entire database access of your application is done via entity beans with container-managed persistence (CMP), then you may also use a panel in the EJB Server Configuration to set your JDBC driver, but WebSphere does not support any driver different from the approved ones (DB2, Oracle, Sybase) for EJB CMP. 8.2.3.2 Introducing a new JDBC driver in the WebSphere runtime The configuration procedure for JDBC drivers and DataSources in the runtime WebSphere Application Server, Advanced Edition completely differs from that used in the WebSphere Test Environment. Chapter 8. Database connectivity and persistence 165 See step 1. on page 51 to see a detailed step-by-step example of how to introduce a new driver to the WebSphere runtime system. As said in that section, some drivers will not be able to run the way you would like with just the generic settings. Sometimes you will have or want to set driver-specific properties to operate the database in a specific mode. 8.2.3.3 JDBC driver-specific properties in WebLogic Server WebLogic Server offers a way to go beyond generic settings. With their JDBC driver configuration you can also set driver-specific properties, which are used to create the connection pool. For example, the following shows the configuration of a Cloudscape connection pool in weblogic.properties: weblogic.jdbc.connectionPool.EstorePool=\ url=jdbc:cloudscape:petStoreDB,\ driver=COM.cloudscape.core.JDBCDriver,\ initialCapacity=1,\ maxCapacity=2,\ capacityIncrement=1,\ props=user=none;password=none;server=none The first line specifies the logical name for the connection pool, which in our case is EstorePool. In the url= line, you can specify the full JDBC vendor-specific database URL. In WebSphere, this URL will be composed with the URL prefix of the JDBC driver (<protocol>:<subprotocol>, fir example, jdbc:cloudscape), a colon (“:”) and the database name (petStoreDB). WebLogic doesn’t make up the URL programmatically, but just takes what you set as the full URL. In WebSphere if you specify a URL prefix for the JDBC driver, it will automatically insert a colon between the URL prefix and what you entered under the database name. The URL syntax is vendor specific and does not necessarily prescribe this colon preceding the location and name of the database. However, most of the well-known driver vendors do use the same format. But if the URL specified by your driver vendor is different, then for WebSphere you should leave the URL prefix for the JDBC driver blank and enter the full URL in the database name field of the DataSource configuration. The driver= line defines the full package class name of the JDBC driver. There are more optional keys for configuring connection pools (not only initialCapacity, maxCapacity, capacityIncrement), which often don’t have a counterpart in WebSphere, but they are not crucial to get the JDBC driver or 166 Migrating WebLogic Applications to WebSphere Advanced Edition DataSource runable on both systems. They are mainly for performance tuning. The props key is a slight benefit for WebLogic in regards to openness for integration of new JDBC drivers. In our Cloudscape example, this was not an issue, since we didn’t have the need to specify any database-specific properties. But in some applications, you have to specify environment properties for the database to set a specific mode. They are passed in the getConnection(url, props) method when the server creates the pool of connections. In the JDBC driver configuration in WebLogic, you can set these key/value pairs under props. In WebSphere, these specific settings can’t be done, unless the JDBC driver vendor provides an alternative way of configuring those properties (for example, incorporated in the URL). WebSphere has implemented an interim solution to provide Sybase-specific properties, where you can specify the properties in a datasources.xml file located in the <AppServerhome>\properties directory. This is a temporary solution, which cannot be reliably used for drivers or DataSources other than those from Sybase. In the dataSources.xml file, you can set attributes in form of key/value pairs for a DataSource, but this support is currently only being used for Sybase properties and to pick up the prepared statement cache size for the connection pool. 8.2.3.4 Migration issues when changing JDBC drivers or databases The JDBC API provides a common programming interface for accessing different databases, it can also be used to use vendor-specific features (stored procedures, utilizing metadata, specific data types, SQL dialects, and so on). In this case changing the database or the driver would not be easy. Driver support for advanced JDBC 2.0 scenarios such as batch updates, CLOB/BLOB support, scrollable ResultSets, programmatic changes through ResultSet, distributed transactions, etc. also varies from vendor to vendor. The JDBC specification discourages use of the DriverManager in favor of DataSources saying that the DriverManager, Driver, and DriverPropertyInfo are legacy features of JDBC and that they may be deprecated in the future. In previous versions of JDBC the DriverManager's getConnection(url, property) was the standard method of obtaining a connection, so developers are familiar with this and often expect the same behavior from DataSource implementations. Changing a JDBC driver and using its functionality shouldn’t have any particular dependency on the application server but, because WebSphere doesn’t have support the setting of driver-specific properties where the driver Chapter 8. Database connectivity and persistence 167 is not compliant, and that only certain drivers are allowed for Entity CMP, this could mean that a driver used in a WebLogic application can’t be used in WebSphere. So if the driver you use in WebLogic cannot work with generic settings and thus cannot be integrated into the WebSphere environment, you may have to check whether your database code will be a major migration issue. Should you encounter this situation during your migration, we recommend that you give careful consideration to your options before migrating to a different driver or database. It is possible that the driver-specific properties used in your WebLogic application are not crucial to the application functionality and that using the generic driver support provided in WebSphere may perform acceptably. However, it is possible that you will have to use a different JDBC driver or consider migrating to a different database system. We expect this issue to decline in importance over time, as JDBC driver vendors move over time towards providing the standard way to get and set properties. The JDBC 2.0 Standard Extensions Specification says that the only property that is required on a DataSource is the description. The specification defines other standard properties that must use to the defined names. All standard and vendorspecific properties must provide get and set methods and the use of getter and setter methods is the standard way of handling properties for DataSources. Once JDBC driver vendors move to this standard, we expect that migration between vendors will become an easier task. 8.2.4 Distributed transactions Since the JDBC 2.0 Optional Package API there is support for distributed transactions within JDBC. Distributed transactions are commands that are sent to multiple database servers. Either all of them are completed (commit) or none (rollback). The extended functionality allows a JDBC driver to support the two-phase commit protocol (2PC) used by the Java Transaction API. The Java Transaction API (JTA) and the Java Transaction Service (JTS) specify the Java interfaces between a transaction manager, the application, the resource manager, and the application server. The transaction part of the JDBC 2.0 Optional Package API is mainly intended to be used for transactions in a component-based architecture, where a server handles transaction declarations and controls distributed transaction boundaries. In the case of EJBs, the EJB server will take care of transactions. 168 Migrating WebLogic Applications to WebSphere Advanced Edition In special situations if you want to demarcate the boundaries of a transaction explicitly, for instance in Java Servlets, JSPs, EJB session beans with transaction attribute TX_BEAN_MANAGED or even in stand-alone programs, JTA provides the javax.transaction.UserTransaction interface. Developers can use a UserTransaction to begin, commit, or roll back transactions. Working with distributed transactions should not have a significant impact on the application code, since the JDBC, JTA and EJB implementations offer standardized interfaces. Nevertheless there are again some coding differences and restrictions. Before you start testing, you have to install a JTA enabled driver into WebSphere. Refer to step 3. on page 54 to find out how to do this. 8.2.4.1 Migrating a WebLogic JTA example to WebSphere On the WebLogic home page, you can find an example of using a JTS driver. JTA is the high-level interface for the developer and JTS is the lower-level interface that is used by the container to operate with the JDBC driver. The example can be found at the URL: http://www.weblogic.com/docs51/classdocs/ jts_driver.html. This is the source code of the example: import javax.transaction.UserTransaction; import java.sql.*; import javax.naming.*; import java.util.*; import weblogic.jndi.*;. . . { Connection conn = null; UserTransaction tx = null; try { Context ctx = null; Hashtable env = new Hashtable(); env.put( Context.INITIAL_CONTEXT_FACTORY, "weblogic.jndi.WLInitialContextFactory"); // Parameters for the WebLogic Server. // Substitute the correct hostname, port number // user name, and password for your environment: Chapter 8. Database connectivity and persistence 169 env.put(Context.PROVIDER_URL, "t3://localhost:7001"); env.put(Context.SECURITY_PRINCIPAL, "Fred"); env.put(Context.SECURITY_CREDENTIALS, "secret"); ctx = new InitialContext(env); tx = (UserTransaction) ctx.lookup("javax.transaction.UserTransaction"); // Start a transaction on the current thread: tx.begin(); // Load the JTS driver Driver myDriver = (Driver) Class.forName("weblogic.jdbc.jts.Driver").newInstance(); // Get a connection from the connection pool. Properties props = new Properties(); props.put("connectionPoolID", "myConnectionPool"); conn = myDriver.connect("jdbc:weblogic:jts", props); // Execute your database operations. // Close your connection objects. // Note that closing the connections does not commit the transaction // nor return the connection to the pool: conn.close(); // Execute any other database operations. // // // // Complete the transaction by either committing the transaction or rolling it back. The JTS driver will commit all the transactions on all connection objects in the current thread and return the connection to the pool. tx.commit(); // or: tx.rollback(); } catch (Exception e) { 170 Migrating WebLogic Applications to WebSphere Advanced Edition try { if (conn != null) conn.close(); if (tx != null) tx.rollback(); } catch (Exception e2) { } // handle Exception } } This code could run in a servlet, a JSP, an EJB session bean with TX_BEAN_MANAGED, or an application. We decided to test this example in a servlet within WebSphere. In order to have the example run in WebSphere, remove the unnecessary import statement: import weblogic.jndi.*; The WebLogic example does not use the recommended DataSource interface. While we are migrating from WebLogic to WebSphere, we are also going to use the recommended and portable approach via DataSource. This allows a 2PC protocol to be supported, through the use of XADataSource and XAConnections. Therefore, insert the following import statement: import javax.sql.*; In the method, the first action is getting the initial context. We have already described that you have to change weblogic.jndi.WLInitialContextFactory to com.ibm.ejs.ns.jndi.CNInitialContextFactory as the provider URL to the server and port of the WebSphere naming service using the IIOP protocol (for example, iiop://myserver:900). The security settings are optional, but if you set it you must set a known user who has read access to the naming service. After you obtained the initial context, you can look up the UserTransaction object. WebLogic binds this object under the JNDI name javax.transaction.UserTransaction, while you can get the WebSphere counterpart at jta/usertransaction. As a best practice, again we recommend that you get the name from an external resource (environment, property file, a Chapter 8. Database connectivity and persistence 171 common logical name in JNDI,...) instead of hardcoding it. So in WebSphere you get the UserTransaction object with the following context lookup: // Get JNDI name for UserTransaction from system environment // and take the WebSphere name as default String utxName = System.getProperty("jta.UserTransaction"); if (utxName == null) utxName = "jta/usertransaction"; tx = (UserTransaction) ctx.lookup(utxName); Notice that the client does a simple type cast of the lookup result, rather than invoking a narrow method as required with other JNDI lookups. We decided to use the DataSource interface to get the transaction-enabled connection to the database. In WebSphere we configured a DataSource called jdbc/exampleTX, which is based on a JTA-enabled JDBC driver. To get the connection via the DataSource you can type: // Get JNDI name for the example TXDataSource from system environment // and take jdbc/exampleTX as default String dsName = System.getProperty("example.TXDataSource"); if (dsName == null) dsName = "jdbc/exampleTX"; DataSource ds = (DataSource) ctx.lookup(dsName); System.out.println("Datasource lookup - OK"); Connection conn = ds.getConnection(); All other methods including the transaction code (tx.begin(), tx.commit(), tx.rollback()), the executed database commands on the connection and the closing of the connections can pretty much stay the same in both servers. With JTA enabled driver connections obtained from a DataSource, the autoCommit attribute is turned off by default. You also should not call conn.commit() or conn.rollback(), but let the transaction manager do that for you (tx.commit() or tx.rollback()). When working with transactions, you will observe that the current WebLogic implementation of JTA/JTS is very limited. Read what is said in their example: “If these [database] operations use the JTS driver to access the same connection pool as the transaction begun, they will participate in that transaction. If the additional database operations using the JTS driver use a different connection pool from the one specified in step 5 (myDriver.connect()), an exception will be thrown when you try to commit or roll back the transaction.” 172 Migrating WebLogic Applications to WebSphere Advanced Edition In their JTA/JTS implementation, only one connection pool (DataSource) can participate within a single transaction. Within this transaction every lookup() to the DataSource will return the same connection instance and thus guarantee transactional integrity. This is a poor implementation in comparison with the WebSphere solution, in which you can use many different DataSources within a distributed transaction. They are committed using the standard two-phase commit (2PC) protocol. We successfully tested our Java Servlets transaction example in the WebSphere runtime environment, but we could not run it in the WebSphere Test Environment of VisualAge for Java, because the servlet was based on the 2.2 Specification. While this book was written the WebSphere Test Environment only supported Java Servlets 2.1. The Tomcat test environment in VisualAge supports Java Servlets 2.2 but couldn’t handle WebSphere distributed transactions. 8.2.5 Summary: Writing portable JDBC applications To sum it up it can be said that for JDBC applications to be portable from one application server to the other, you have to consider the following points: • Use the DataSource interface to: a. Get the connection to the data source b. Get a connection from a connection pool c. Get a connection that supports distributed transactions • Don’t hardcode the JNDI Name of your DataSource or the UserTransaction object, but get it from the environment or a configuration file • Use a portable JNDI name, for example jdbc/yourDataSourceName (WebSphere has a limitation here: only a single subcontext starting with jdbc/ is allowed) • When you look up the DataSource from the JNDI context, use a slash for the subcontext not a dot (use jdbc/yourDataSourceName and not jdbc.yourDataSourceName) • Use the JTA interface for distributed transactions, just WebLogic Server is not there yet • The JDBC driver being used could be a problem, since you might have difficulties integrating it in the application server. Therefore avoid database-specific and JDBC vendor-specific coding in case you will have to use a different database or JDBC driver. Sources of differences between databases and JDBC drivers are: Chapter 8. Database connectivity and persistence 173 - The actual data types offered. - The details of the SQL commands, syntax, and operations. - The availability of DBMS-related services such as batch processing. - DababaseMetaData and ResultSetMetaData: avoid dependencies on vendor-specific information except where your code also supports a completely portable solution. - Stored procedure support and syntax are generally vendor-specific; if used, process ResultSets before OUT parameters. - Multiple ResultSets and vendor-specific batch support -- avoid use. - SQLException and SQLWarning attributes are generally vendorspecific -- only use data for presentation. - Transaction isolation level -- don't be dependent on a particular vendorsupplied default and avoid user control of same with setTransactionIsolation(). - Support for scrollable ResultSet is optional; use a RowSet bean. - Support for updatable ResultSet is optional (CONCUR_UPDATABLE). Although this avoids the explicit SQL problem, it is still vendor-specific. RowSet is a more portable solution. - Support for JDBC 2.0 batch update feature (addBatch(), executeBatch()) is optional. This is better than a vendor-specific batch processing language, but it may still be non-portable. - RowSet may have optional URL and database name parameters. Use DataSource options instead. 8.3 jDriver (jdbcKona) jDriver (formerly jdbcKona) is a collection of native JDBC drivers for Oracle, Sybase, Informix and Microsoft SQL Server. These drivers provide a number of extensions to the vendor’s original JDBC driver. For example, the jdbcKona/Oracle driver provides an extension for creating and using Oracle sequences. jdbcKona seems to be part of WebLogic Server Version 4.5 and has been replaced by jDriver, a collection of WebLogic JDBC drivers, in 5.1. jDriver-drivers are two-tier and multi-tier drivers that depend on client-side middleware to function. WebLogic has no single packaged JAR-file for their drivers, which could then be taken over to a different application server. You would need to filter out all class and interface types from the WebLogic core 174 Migrating WebLogic Applications to WebSphere Advanced Edition classes which are needed by the driver and package it on your own. But it is doubtful whether this is a good and valid solution. A discussion about available drivers for WebSphere can be found in 8.2.3, “Available drivers” on page 164. For more information on the BEA WebLogic jDriver Family see: http:// www.beasys.com/products/weblogic/drivers.shtml For details of using the jdbcKona family of JDBC drivers: http:// www.weblogic.com/docs/classdocs/API_joci.html 8.4 dbKona dbKona is a WebLogic tool that provides a higher-level mechanism for accessing JDBC databases. Much as with htmlKona, applications developed using dbKona will likely require considerable effort to migrate. Below is a snippet of code from a dbKona code example. The connection (conn) is created using the standard JDBC 1.0 API. It is unclear if dbKona supports a connection obtained from a DataSource. ... ts1 = new TableDataSet(conn, "emp"); for (int i = 0; i < 100; i++) { Record rec = ts1.addRecord(); rec.setValue("empno", i) .setValue("ename", "Person " + i) .setValue("deptno", i); } // Save new records. dbKona does selective saves, that is, // it saves only those records in the TableDataSet. System.out.println("Inserting " + ts1.size() + " records."); ts1.save(); // Define a KeyDef for updates and deletes. KeyDef key = new KeyDef().addAttrib("empno"); // Update the 100 records that we originally added. ts2 = new TableDataSet(conn, "emp", key); ts2.where("empno < 100"); ts2.fetchRecords(); for (int i = 0; i < ts2.size(); i++) { Chapter 8. Database connectivity and persistence 175 Record rec = ts2.getRecord(i); rec.setValue("ename", "Worker " + i); } ts2.save(); ... The full example can be found at http://www.weblogic.com/docs/examples/ dbkona/db2examples.html. The KeyDef mentioned in the example is the primary key of the table. The primary key must be known in order to do updates. Unfortunately, dbKona is likely to cause problems during a migration. One problem with tools such as dbKona is that developers tend to forget about such things as application layering. That is, it is very likely that dbKona code will be found directly in the servlet code. As part of the migration effort, a distinct data layer should be introduced. dbKona provides a higher-level abstraction of JDBC, but in this example we see that dbKona is marginally higher-level than using the standard JDBC PreparedStatements. The use of JDBC 2.0 Rowsets would provide a more standard alternative to much of the dbKona functionality. A considerable amount of work must be done to convert existing dbKona source into standard JDBC 2.0, but this is the recommended and portable way. Unfortunately, this will be a largely mechanical effort, since we are not aware of tools to automate the process. For the most-part, dbKona calls can be converted directly into JDBC calls. As with htmlKona, there also is no technical reason why the dbKona code cannot be used without modification in WebSphere. However, it is unclear whether dbKona classes licensed from WebLogic Server can be legally used in WebSphere, or if dbKona can be licensed separately from WebLogic Server. For an overview of dbKona architecture see: http://www.weblogic.com/docs/ techoverview/db.html 8.5 Business objects - persistence frameworks In Java 2 Platform, Enterprise Edition the EJB specification is beginning to provide a business object standard, but there is still much that remains to be done. Similarly the Java Data Objects (JDO) Specification is also on the way and currently available as Version 0.8, public review draft. 176 Migrating WebLogic Applications to WebSphere Advanced Edition One issue with current EJB specifications as documented in the Enterprise JavaBeans Specification, Version 2.0 from Sun Microsystems is that: Every method call to an entity object via the remote and home interface is potentially a remote call. Even if the calling and called entity bean are collocated in the same JVM, the call must go through the container, which must create copies of all the parameters that are passed through the interface by value (that is, all parameters that do not extend the java.rmi.Remote interface). The container is also required to check security and apply the declarative transaction attribute on the intercomponent calls. The overhead of an inter-component call will likely be prohibitive for object interactions that are too fine-grained. The solution for fine-grained business objects considered by the EJB specification are so-called dependent objects, which should not be implemented as entity beans. Instead, a dependent object is better implemented as a Java class (or several classes) and included with the entity bean on which it depends. Regarding entity beans, the EJB 1.1 Specification left many things open to the server provider. This caused some non-portable code. The new EJB 2.0 Specification deals with many of these issues and makes some major steps towards standardization of entity beans. The revised entity bean specification includes support for container-managed relationships between entity beans and dependent objects. It provides a foundation for pluggable persistence managers and specifies a portable finder query syntax called EJB QL. Furthermore, it enables support for more efficient vendor implementations by leveraging lazy loading, dirty detection, memory footprint reduction. We expect that the major J2EE server products, like WebLogic Server and WebSphere Application Server, Advanced Edition will provide support for the new EJB standard in future versions. 8.5.1 Container-managed persistence (CMP) entity beans The coding for CMP entity beans is much simpler than for BMP (beanmanaged persistence), because most of the work is being done by the container. CMP entity beans should perform better than BMPs because the container has a lot of possibilities to optimize performance issues. Entity beans as such are the most puzzling for migration issues, because they still have a heavy dependency on server proprietary solutions. WebLogic offers two CMP persistence solutions: Chapter 8. Database connectivity and persistence 177 • The WebLogic Server RDBMS Persistence for trivial entity bean applications • TOPLink for WebLogic TOPLink is sold as an add-on to WebLogic Server, but it is a popular EJB container that is widely used in WebLogic applications. WebSphere’s CMP solution has more to offer than WebLogic’s simple CMP implementation. WebSphere already supports associations and inheritance for EJBs. There is a current restriction that EJBs must use the DataSources from DB2, Oracle, or Sybase. Other databases cannot be used for CMP entity beans. A TOPLink for WebSphere is also announced and should be available shortly. Refer to 8.5.3, “TOPLink” on page 178 to get more information about migration issues involved with that product. 8.5.2 Bean-managed persistence (BMP) entity beans As the name implies BMP entity beans have to manage their persistent data on their own. This can be done either by using direct JDBC, a persistence mapping tool or even a legacy application. The persistence approach in the BMP may be an issue for portability or migration. If the BMP persistence uses JDBC you have to consider the points mentioned earlier in this chapter. If you use other products or applications, migration issues or incompatibilities will be vendor and product specific. 8.5.3 TOPLink TOPLink for Java is a persistence framework that maps objects to relational databases. TOPLink has a significant install base and, as such, may be part of a migration effort. TOPLink for Java is written in Java and should migrate with relative ease from one application server to the next. TOPLink for WebLogic is a container designed specifically to provide persistence mapping for WebLogic Server. Some parts of WebLogic Server have, in fact, been influenced by the TOPLink implementation. TOPLink for WebLogic is BEA's preferred container-managed persistence solution. They do have an alternative (WebLogic Server RDBMS Persistence), but BEA's own sales force aggressively markets (and frequently sells) TOPLink. The 178 Migrating WebLogic Applications to WebSphere Advanced Edition point is that where there are CMP EJBs with WebLogic, TOPLink is probably being used. TOPLink was recently (April 2000) purchased by WebGain as part of a combined BEA/WebGain purchase of The Object People. TOPLink for WebSphere has been announced and will be shipping by the end of November 2000. From an application developer's point-of-view, there is only one significant difference between the WebLogic and WebSphere products. The WebLogic version of the product automatically generates primary keys for entity beans upon creation using a sequence table. Due to a timing issue with the WebSphere container, TOPLink cannot automatically generate keys for WebSphere. The application developer must modify their ejbCreate(...) methods to include a single line of code to generate sequence numbers: TOPLink.Public.EJB.SessionManager.getManager().getSession("TLWSEmployeeDem o").getActiveUnitOfWork().assignSequenceNumber(this); It's ugly code, but it's only one small change. Unfortunately it is very nonstandard. TOPLink does force a number of other non-standard things into your beans, especially if you want to take advantage of more advanced features such as deferred loading of contained objects. 8.5.3.1 Migration strategy For TOPLink for Java, there are no major issues. The migration should be relatively simple. For TOPLink for WebLogic, migration should still be a relatively simple matter of mechanically making changes to the code. 8.5.4 Other persistence managers Besides TOPLink, there are also other persistence manager products on the market that provide support for both servers. These include Thought Inc.’s CocoBase and Versant’s Object Container (OO database). Chapter 8. Database connectivity and persistence 179 180 Migrating WebLogic Applications to WebSphere Advanced Edition Chapter 9. Migration example: The Java Pet Store This chapter uses the Java Pet Store application from Sun Microsystems to provide an example of the migration approach we recommend. While individual chapters of this redbook make more detailed recommendations about specific migration topics, we use the Java Pet Store example to provide an overview of how these techniques can be combined to migrate a complete application. 9.1 Introduction This chapter is a complete example of a small, but non-trivial migration effort, a mini-migration. We apply the process outlined in 1.4, “How to use this guide” on page 10, and made use of the migration issues documented elsewhere in this book. We have chosen the well-known Java Pet Store example. Although this example is small enough to migrate in a single step, we planned to use the incremental approach discussed in 2.4, “Migration strategies” on page 26. In addition to being closer to a real migration effort, this approach helped us validate the incremental migration technique. 9.1.1 Why Java Pet Store? The Java Pet Store application is a particularly good example for our purposes: • It has been deployed on BEA WebLogic Server. • It conforms to the J2EE interfaces and architecture. • Although it is a small application, it is non-trivial. • It is a well-known example, likely to be familiar to the reader. Developed by Sun Microsystems, the Java Pet Store application has been deployed on a number of different EJB servers, including BEA WebLogic Server. A detailed step-by-step description of how to deploy the Java Pet Store on BEA WebLogic Server is available from at: http://developer.java. sun.com/developer/technicalArticles/J2EE/deployathon2/BEAreadme.html. There are currently two versions of this application available from Sun Microsystems, Version 1.0.1 and Version 1.1. We use Version 1.0.1 because it is the one that has been deployed to the BEA WebLogic Server. The Java Pet Store application was designed as a J2EE-compliant application. Indeed, it has become the J2EE reference application. It adheres to the J2EE APIs and architecture guidelines, and has been written to be © Copyright IBM Corp. 2001 181 moderately portable. As such, it highlights J2EE deployment and migration issues more than it does the vendor-specific conversion issues that might be found in non-J2EE WebLogic applications. Although we document the steps we took to migrate Java Pet Store 1.0.1 from WebLogic to WebSphere, this is not written to be the official step-by-step instructions for deploying the Java Pet Store on WebSphere. Our goal is to provide more general guidance on how to migrate WebLogic J2EE applications. As such, we provide additional hints on how to discover and resolve migration problems. The Java Pet Store is just our vehicle for accomplishing this goal. We used the following process: a. Analyze the Java Pet Store application. b. Identify major migration issues and plan the migration stages. c. Establish the migration environment. d. Migrate the EJB server, stage 1. e. Migrate the Web server, stage 2. Not all of our redbook authors were familiar with the details of the Java Pet Store application. This meant that we had to go through an initial analysis and discovery process similar to what is involved in a real migration effort. We have captured some of this experience by describing unexpected problems and how we went about solving them. In particular, we realized early on that we would have to make more Java source code changes to the Enterprise JavaBeans than we would have preferred. Since the Java Pet Store follows the Enterprise JavaBeans 1.1 Specification we had to make code changes to revert to the Enterprise JavaBeans 1.0 Specification. Anticipating a future upgrade to the Enterprise JavaBeans 1.1 Specification, we tried to do this in a way that retains as much of the original Enterprise JavaBeans 1.1 code as possible. 9.2 Understand the application The first step of a migration is to develop an understanding of the application you plan to migrate. In many cases, the developers tasked to migrate an application are not its original developers, or even the maintenance team. Also, migration requires a different perspective, one directed more towards standards and portability. As preparation for our mini-migration example, we took a few minutes to become familiar with the Java Pet Store user interface, and then spent a fair amount of time understanding its structure and 182 Migrating WebLogic Applications to WebSphere Advanced Edition implementation. We were not interested in a full understanding of the implementation. We needed just enough information to identify likely migration problems, and to evaluate possible migration strategies. Indeed, we consciously avoided becoming experts on the Java Pet Store by not studying the extensive design documentation provided by Sun Microsystems at http://developer.java.sun.com/developer/Books/DesignEntApps/chap10.pdf. 9.2.1 Java Pet Store user interface This is a typical Web store application with a typical Web store browser-based user interface. It includes pages for welcome, inventory, ordering, and checkout. Figure 52 on page 184 shows selected examples of the user interface. After installing the Java Pet Store application on our migration platform under the BEA WebLogic Server, we spent about five minutes playing with the user interface to become familiar with its functionality. If you are migrating a complex system, you will need to spend more time with this activity. Chapter 9. Migration example: The Java Pet Store 183 Figure 52. Java Pet Store user interface 9.2.2 Java Pet Store implementation Compared with the user interface, you will want to spend quite a bit more time studying the implementation of your application. The documentation provided with the Java Pet Store application was a good place for us to start, but we also found it helpful to examine the directory and package structures, the deployment descriptions, and the source code itself. We recommend that you: 184 Migrating WebLogic Applications to WebSphere Advanced Edition • Identify the application’s pieces and understand how they fit into the overall architecture. With the Java Pet Store, we paid particular attention to the Java Servlets, the JavaServer Pages, and the Enterprise JavaBeans. The general roles of these components are well-defined by the J2EE specification. Java Servlets and JavaServer Pages reside in the Web tier while Enterprise JavaBeans reside in the application tier. • Question the role of the other pieces you find in your application. For example, the Java Pet Store contains a set of model pieces that can reside in both of the servers. Discovering this sort of information is important if you plan to migrate your application in different stages. • Understand how your database fits into the application. Typically, this is done through the entity beans, but you may find that your Web tier also makes direct references to the database. We discovered that this is the case with the Java Pet Store. Again, this is important if you plan to stage your migration. • Finally, notice any unusual or interesting features. For example, the Java Pet Store contains classes that deal with security and user authorization. Migrating this sort of feature can be troublesome because it typically relies on vendor-specific or system-specific details. • Construct an inventory of the pieces in your application. The Java Pet Store application contains about 90 Java classes and 35 JavaServer Pages. Figure 53 on page 187 provides a high-level view of this inventory. The directory structure on the left of this figure was taken from Windows NT Explorer. The package structure on the right of this figure was taken from VisualAge for Java. Using this view, and digging a bit deeper into deployment descriptions and the code, we discovered the following about this inventory of pieces: - The package structure corresponds nicely to the directory structure. - All of the JavaServer Pages are located in the docroot subdirectory. - The web subdirectories contain classes for the Web tier. - The ejb subdirectories contain classes for the EJB tier. - There are seven components, each with three packages for their ejb, web, and model aspects.There are a variety of EJB types: • ShoppingCartEJB, a stateful SessionBean, in cart\ejb • AccountEJB, a BMP entity bean, in account\ejb. Chapter 9. Migration example: The Java Pet Store 185 • CatalogEJB, a stateless SessionBean, in catalog\ejb. • ShoppingClientControlEJB, a stateful SessionBean, in control\ejb. • InventoryEJB, a BMP entity bean, in inventory\ejb. • MailerEJB, a stateless SessionBean, in mailer\ejb. • OrderEJB, a BMP entity bean, in order\ejb. - Each EJB, except for the MailerEJB, is referenced by classes found in the corresponding Web tier web subdirectories. - Each EJB, except for the MailerEJB and the ShoppingClientControlEJB, has a corresponding model subdirectory. With this little bit of information, the roles of the ejb and web directories are clear. Understanding the classes in the model subdirectories requires more information about the application architecture. 186 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 53. Java Pet Store directory and package structure Chapter 9. Migration example: The Java Pet Store 187 9.2.3 Java Pet Store architecture For migration purposes, it is not necessary to understand all of the details of an application’s architecture. It is important, however, to know what pieces go onto which servers and how the pieces communicate with and depend on each other. The architecture of the Java Pet Store application exemplifies several patterns common to J2EE applications. Figure 54 on page 188 depicts the architecture. Web server 1 web browser [controller] servlet translates events [view] names of JSPs 9 7 5 [events] 8 [model] names 6 [updates model] 2 [returns list of updated models] catalog EJB server OrderEJB Account EJB ... 3 controller EJB -- state machine updates EJBs database 4 Figure 54. Java Pet Store architecture • Multi-tier server. Aside from the user’s browser, there are typically three or more tiers in an J2EE application. JavaServer Pages and Java Servlets in the Web server translate HTTP requests into method calls on the EJBs in the EJB server, and the EJBs encapsulate the underlying database. For the most part, the Java Pet Store is typical. One exception is that the catalog database can 188 Migrating WebLogic Applications to WebSphere Advanced Edition be referenced directly by both the Web server and the CatalogEJB in the EJB server. This impacts the migration effort in that database connections occur in both the Web and EJB servers. (We discuss the catalog database further in 9.2.4, “Java Pet Store database” on page 190.) • MVC pattern for user interactions. The Web server uses a variation on the Model-View-Controller (MVC) pattern, called the Model 2 Architecture. See http://developer.java. sun.com/developer/onlineTraining/JSPIntro/contents.html for more information. JavaBeans events are generated by the command processor whenever EJBs are updated. These events are defined in the com.sun.estore.control.events package. The events tell the model objects when to refresh themselves from the underlying EJBs. The JavaServer Pages simply populate themselves from the model objects located in the Web server. Since JavaBeans events require that both the event source and event listeners be in the same JVM, these components are closely coupled within the Web server, and must be migrated together. • Value objects for communicating across server boundaries. Value objects are serializable, immutable objects. They have getter methods, but no setter methods. They are also referred to as model beans in the Java Pet Store application. Model beans are typically used to communicate between EJBs and Java clients outside of the EJB server. They can be copied freely with the understanding that their value is a snapshot of EJB data values at the time they were generated. The Java Pet Store uses model beans to update the Web model objects when the underlying EJBs have been modified. The Web model objects are surrogates for the underlying EJBs, but since they are in the same JVM, they can listen to JavaBeans events generated within the Web server. Indeed, these Web server objects are implemented by extending the model beans with event listeners. For migration purposes, this tells us that the same model objects must work for both the Web server and the EJB server at each stage of the migration. These classes are shared by both servers. • JNDI names used to connect pieces in different servers. There are lots of cross-server references in a J2EE application. In the Java Pet Store application, the Web server has to find the EJBs in the EJB server. It also has to find the catalog database because the catalog is not strictly encapsulated by an EJB. Finally, the EJBs themselves have to be able to find each other and their respective databases. These connections are all handled by JNDI entries. To help with portability, the package com.sun.estore.util contains all of the JNDI lookup names. That’s the good news. The bad news is that we expected to have to modify some of these Chapter 9. Migration example: The Java Pet Store 189 names to be compatible with the EJB 1.0 Specification. For the record, JNDINames.java in the com.sun.estore.util package, defines the following static final String variables: - CATALOG_EJBHOME SCC_EJBHOME CART_EJBHOME ACCOUNT_EJBHOME ORDER_EJBHOME INVENTORY_EJBHOME MAILER_EJBHOME INVENTORY_DATASOURCE ESTORE_DATASOURCE MAIL_SESSION USE_CATALOG_EJB SECURITY_ADAPTER_CLASSNAME SERVER_TYPE SEND_CONFIRMATION_MAIL The value of each of these Strings uses the Enterprise JavaBeans 1.1 standard for the java:comp/env JNDI default naming context. For example, the value of CART_EJBHOME is java:comp/env/ejb/cart. Since the Enterprise JavaBeans 1.0 Specification does not support the new JNDI naming context, these names were an issue for our migration of the Java Pet Store application. 9.2.4 Java Pet Store database Frequently, the differences in database products and their use offer the greatest challenges when migrating enterprise applications. However, database migration is a topic in its own right and is beyond the scope of this book. Any needed database migration should be done independently of migrating your J2EE application. That said, you should be interested in how the pieces of your J2EE application map to your database. This knowledge can impact your J2EE migration in various ways, in particular with respect to deployment and for staging needed changes. When we looked at the Java Pet Store application, we found that it uses a variety of ways to implement persistence data. In general, there are several places to look to find this sort of information: • EJBs. • Deployment descriptors. • References to the java.sql.Connection interface. 190 Migrating WebLogic Applications to WebSphere Advanced Edition For the Java Pet Store, examining classes that reference the Connection type generated interesting results. Figure 55 on page 191 lists all of the classes that reference the java.sql.Connection interface. com.sun.estore.account.ejb.AccountDAO.java com.sun.estore.account.ejb.AccountEJB.java com.sun.estore.catalog.model.CatalogDAO.java com.sun.estore.catalog.model.CatalogImpl.java com.sun.estore.inventory.ejb.InventoryDAO.java com.sun.estore.inventory.ejb.InventoryEJB.java com.sun.estore.order.ejb.OrderDAO.java com.sun.estore.order.ejb.OrderDAOOracle.java com.sun.estore.order.ejb.OrderDAOCS.java com.sun.estore.order.ejb.OrderDAOSybase.java com.sun.estore.order.ejb.OrderEJB.java com.sun.estore.order.ejb.UUIDGenerator.java: Figure 55. Java Pet Store connection references The first thing to note in this list is that only three of the four packages are ejb packages. The other one is the model package for the catalog. Both the CatalogEJB (in an ejb package) and the CatalogWebImpl (in a web package) extend the CatalogImpl class (in a model package). All of the catalog database code is located in the CatalogImpl class. So the bottom line is that the catalog database is accessed from two different objects, one in the Web server and the other in the EJB server. Since the Java Pet Store catalog is a read-only database, this is a plausible implementation. It also means that if we change the CatalogImpl class, we will impact both the Web server and the EJB server. This is another example of code sharing across server boundaries. The second thing to note is that there are a number of classes with DAO in their names, meaning data access object. Remember that all of the entity beans use BMP. The DAO classes are where you will find all of the BMP SQL code. This technique encapsulates code that may need modifications as a result of database migration. The fact that the com.sun.estore.order.ejb package has separate implementations for three different database products also highlights the problems of database migration. In retrospect, we should have paid more attention to this aspect of the Java Pet Store because we also migrated to a DB2 database, which was not one of the supported databases. Finally, what is missing from Figure 55 on page 191? There are no references to the Connection type in the ShoppingClientControllerEJB, the Chapter 9. Migration example: The Java Pet Store 191 ShoppingCartEJB, or the MailerEJB. Indeed, these EJBs have no real persistent data. Given that the MailerEJB is a stateless SessionBean, this is not surprising. The ShoppingCartEJB and the ShoppingClientControllerEJB do, however, contain data, but this data is not persistent across user sessions. Their data is maintained in memory as hashtables. As stateful SessionBeans, the cart and the user state data are simply lost when the current session ends. Because they have no underlying database dependencies, these EJBs should be easier to migrate than the other EJBs in the Java Pet Store application. 9.2.4.1 Table names The Java Pet Store uses a very simple mapping between EJBs and database tables. An EJB instance generally maps to a single row in a table. This is a typical arrangement for WebLogic applications that do not use a persistence manager, such as TOPLink. In particular, the three EJBs and the one JavaBean that map to a database encapsulate access to a total of eight different tables. • AccountEJB encapsulates the account table. • InventoryEJB encapsulates the inventory table. • OrderEJB encapsulates the item, product, and lineitem tables. • CatalogModel bean encapsulate the item, product, and category tables. Table names often present database migration problems. Embedded SQL code must use actual table names, but different databases may use slightly different table names for the same data. The Java Pet Store deals with this portability problem by defining all table names as static final variables in the com.sun.estore.util package. This makes it easy to find and change them if needed. An even better approach might be to use env-entry attributes for these names. 9.2.4.2 Interesting features The Java Pet Store has a couple of interesting features that present migration issues. No doubt your applications will have their own interesting features. • As already mentioned, the catalog database is directly accessible both from the Web server and from the EJB server. • There is a SecurityAdapter class that is designed to authenticate users in accordance with local system security rules. Since there is no standard for authentication, we do not plan to offer a general solution for this common migration issue. 192 Migrating WebLogic Applications to WebSphere Advanced Edition • The MailerEJB makes use of the local system mailer process. This is also a system-dependent issue that we do not plan to address in a general way. • Many of the Java Pet Store classes are used in both the Web and the EJB servers. This complicates migration staging and deployment. 9.2.5 The migration plan After analyzing your application, you should have a pretty good idea which potential migration issues you will have to address. From this information, you can make a plan as to how to stage your migration. For the Java Pet Store, we surveyed the migration issues in this book, and based on our current knowledge of the application, identified the most likely problems, which are: • JNDI ENC The Java Pet Store makes considerable use of the Enterprise JavaBeans 1.1 JNDI environment naming context (ENC). This issue is described in detail in 7.4, “JNDI lookups expanded” on page 134. As expected, most of this is for ejb-ref and resource-ref use, but there are also several env-entry uses. Altogether, there are about 15 such references in nine different classes. • EJBException The Java Pet Store makes significant use of the non-checked EJBException defined for Enterprise JavaBeans 1.1. This issue is described in 7.3, “EJBException replaces RemoteException in EJBs” on page 130. Seven different classes use this exception. The Java Pet Store also defines its own subclass of the EJBException, called GeneralFailureException, another unchecked RuntimeException. • Principal/Identity The Enterprise JavaBeans 1.1 Principal class is used in one Java Pet Store EJB. Although this is a minor problem in terms of the number of affected classes, it is a particularly troublesome issue because it normally requires a system-dependent implementation. This issue is discussed in 7.10, “Authentication method changes” on page 148. • Collection finders Two of the OrderEJB finder methods return the Collection type. This feature was added to Enterprise JavaBeans 1.1. WebSphere currently only supports Enumeration, in accordance with the EJB 1.0 Specification. This problem is discussed in 7.6, “Finders expanded to Collection” on page 141. Chapter 9. Migration example: The Java Pet Store 193 We also considered other potential migration issues, but found that they do not arise in the Java Pet Store. These issue include: • CMP issues Since the Java Pet Store does not use CMP entities, these issues do not arise. • String primary key AccountEJB and InventoryEJB use String as their primary key, but these seem to work fine in WebSphere. 9.2.6 Migration strategy Our original plan was to use an incremental migration strategy. Due to time constraints in completing this book, we elected to use a variation on this strategy. Modifications to Web and EJB servers were pursued in parallel by different authors, and then brought together for a single application deployment. We deferred the verification of the incremental technique described in 2.4, “Migration strategies” on page 26 until after we got the application running under WebSphere. 9.2.6.1 Java Pet Store database We established the migration platform at this point according to the instructions in Chapter 3, “Configuration” on page 33. For the Java Pet Store, this required the definition of a DB2 database preloaded with Pet Store data. Since it is likely that you will also be migrating your application to DB2, you will need to do something similar. This was done by modifying the SQL database creation script for Oracle that is distributed with the Java Pet Store application. At a bare minimum, the table structure outlined in the SQL scripts needs to be created. In addition, a user needs to be created to access the database (this will be used by a DataSource within the WebSphere Application Server, Advanced Edition). The DB2 SQL script that we used is available in the \petstore\bin directory of the additional materials accompanying this book. 9.2.6.2 Pet Store on WebLogic Before you get started with migrating the Java Pet Store to WebSphere, you might want to see what is involved in deploying it on WebLogic. As you will see, this is not actually necessary for our migration task, but it will provide you with a basis for comparison. You will see that one of the main differences is that no recompilation is required for the WebLogic installation. The WebLogic deployathon page, at http://developer.java.sun.com/developer/ 194 Migrating WebLogic Applications to WebSphere Advanced Edition technicalArticles/J2EE/deployathon2/BEAreadme.html, provides easy step-by-step instructions that work well. 9.3 Migrating EJBs Throughout the remainder of this chapter, we assume directory path names as shown in Table 8. You may need to adjust for different paths on your system. Table 8. Directory path naming conventions Directory path Purpose e:\petstore Distributed WebSphere Java Pet Store solution d:\WebSphere\AppServer WebSphere installation d:\petstore\petstore.jar Temporary EJB export directory d:\WebSphere\petstore Deployed Servlets and shared classes for Java Pet Store Given the differences between the Enterprise JavaBeans 1.0 and 1.1 Specifications, it is not possible to perform a non-trivial migration from BEA WebLogic Server 5.1 to WebSphere Application Server, Advanced Edition 3.5 without source level changes. For the Java Pet Store, the relevant source code is identical, whether you use the distribution from Sun Microsystems or from WebLogic. In either case you should remove the security-related classes because they depend on system-specific services. These classes will be replaced by our own, admittedly simple, security classes. Remove: • com.sun.estore.util.J2eeSecurityAdapter.java • com.bea.estore.util.WLSecurityAdapter.java • The com.bea.estore.rdbmsrealm package. The e:\petstore directory contains the original Java Pet Store files in addition to our modifications. This is how we constructed the e:\petstore directory. 1. Download the Java Pet Store, Version 1.0.1, from Sun Microsystems from http://www.java.sun.com/j2ee/download.html#blueprints. 2. Put the file jps-1_0_1.zip into the e:\petstore\original directory and unzip it into that directory. 3. Make a copy of e:\petstore\original\jps1.0.1\src\com and paste it into a new directory e:\petstore\base. The e:\petstore\base directory contains the base Java code for our migration. Chapter 9. Migration example: The Java Pet Store 195 4. Rename e:\petstore\base\com\sun\estore\util\J2eeSecurityAdapter.java to have a java-orig file type. This gets it out of the compile, but reminds us of the original file. 5. If you chose to download the WebLogic deployment of the Java Pet Store, perform the same steps, but rename WLSecurityAdapter.java, and don’t put the rdbmsrealm package into e:\petstore\base. This is a good time to look at the Java source code. VisualAge for Java is an excellent tool for this purpose. Figure 56 on page 197 shows some of the problems in the unmodified Java code. This All Problems list was generated as follows: 1. Import the directory e:\petstore\base into a new PetStore project in VisualAge for Java. 2. Open the All Problems tab. 3. The Java Pet Store depends on several packages that are not available by default within VisualAge for Java. Three of them have been provided in the e:\petstore\lib directory — activation.jar, mail.jar, and sunxml.jar. Import each of these JARs into separate projects in VisualAge for Java. You will notice that this resolves some of the problems. 4. If you haven’t already done so, import the latest servlet.jar file from the d:\websphere\appserver\lib directory. More of the problems will be resolved. The problems that remain require source code changes to convert from the Enterprise JavaBeans 1.1 Specification to the Enterprise JavaBeans 1.0 Specification. Our goal is to make these changes while preserving as much of the original code as possible. This will make a future upgrade to the EJB 1.1 Specification easier. 9.3.1 Tools and techniques We employed a combination of two techniques for locating and modifying the Java source code problems. VisualAge for Java is great for discovering problems. For example, it is clear from Figure 56 on page 197 that the new unchecked EJBException is a problem when migrating to the EJB 1.0 Specification. Of course, we anticipated this problem. VisualAge for Java also has very powerful editing features that make source code changes like these relatively easy. 196 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 56. Initial Java Pet Store problems as seen in VisualAge for Java We also used an automated tool for changing source code. Most of our migration issues can be solved by making very local, and relatively simple source code changes. We wrote a Perl script, called mg_convert, that automatically modifies the code. Since this tool is based on simple pattern matching, it can make mistakes if unusual programming conventions are used. In the Java Pet Store example, it was easier to perform a few of the required modifications by hand instead of programming their corrections into Chapter 9. Migration example: The Java Pet Store 197 the conversion script. The advantage of this tool is that it can reliably (and repeatedly) modify large amounts of code. If you change your mind about a particular transformation, you can just rerun the script. The log that it generates is also useful as a discovery tool. Figure 57 on page 199 is an example of the generated conversion log. Finally, to make source code changes as small as possible, we provided a separate package, named com.ibm.websphere.migrate, for various helper classes. It contains classes like EnumerationConvertor to help with finders that return the Collection type, and InitialContextMigrate to help deal with the JNDI default naming context. At this point, only some of the EJB migration issues have been coded into the mg_convert tool. This Perl script is available in the e:\petstore\bin directory. The e:\petstore\bin\modify.bat command transforms the Java files in the e:\petstore\base directory, and places all modified files into the e:\petstore\modify directory. This directory can then be imported into your PetStore project in VisualAge for Java, updating the Java classes with corrections. Try importing e:\petstore\modify; all of the remaining problems should be resolved. 1. In a DOS shell, change directories to e:\petstore\bin. 2. Enter the command modify. 3. Go to the VisualAge for Java workbench and import the directory e:\petstore\migratelib into a new project. 4. Select the PetStore project. 5. Import the directory e:\petstore\modify into the PetStore project. 6. Go to the All Problems tab to see if any problems remain. 9.3.2 Source changes As indicated in 9.2.5, “The migration plan” on page 193, our analysis of the Java Pet Store code gave us a good idea of the code we needed to change. Except for the Collection finders issue, these were all apparent as errors in VisualAge for Java when we first compiled the e:\petstore\base code. The Collection finders issue did not actually cause an error until we attempted to deploy the EJBs. At that point, the EJB deployment tool caught the problem. Since these migration issues are covered in detail in Chapter 7, “Enterprise JavaBeans” on page 127, we only discuss the specifics of our solutions to the Java Pet Store here. 198 Migrating WebLogic Applications to WebSphere Advanced Edition C:\ITSO > cd petstore\bin C:\ITSO\petstore\bin > modify C:\ITSO\petstore\bin > mg_convert.pl ..\base ..\modify 1>..\modify\modify.console C:\ITSO\petstore\bin > type ..\modify\modify.console | more UNCHANGED: com/sun/estore/account/ejb/Account.java UNCHANGED: com/sun/estore/account/ejb/AccountDAO.java MODIFIED: com/sun/estore/account/ejb/AccountEJB.java import com.ibm.websphere.migrate.InitialContextMigrate; /*MIGRATION*/ import com.ibm.websphere.migrate.EJBExceptionMigrate; /*MIGRATION*/ throw new EJBExceptionMigrate (se); /*MIGRATION*/ throw new EJBExceptionMigrate (se); /*MIGRATION*/ throw new EJBExceptionMigrate (se); /*MIGRATION*/ throw new EJBExceptionMigrate (se); /*MIGRATION*/ InitialContextMigrate ic = new InitialContextMigrate(context.getEnvironment()); /*MIGRATION*/ throw new EJBExceptionMigrate(ne); /*MIGRATION*/ throw new EJBExceptionMigrate(se); /*MIGRATION*/ UNCHANGED: com/sun/estore/account/ejb/AccountHome.java UNCHANGED: com/sun/estore/account/ejb/DuplicateAccountException.java UNCHANGED: com/sun/estore/account/model/AccountModel.java UNCHANGED: com/sun/estore/account/web/AccountWebImpl.java UNCHANGED: com/sun/estore/cart/ejb/ShoppingCart.java UNCHANGED: com/sun/estore/cart/ejb/ShoppingCartEJB.java UNCHANGED: com/sun/estore/cart/ejb/ShoppingCartHome.java UNCHANGED: com/sun/estore/cart/model/CartItem.java UNCHANGED: com/sun/estore/cart/model/ShoppingCartModel.java UNCHANGED: com/sun/estore/cart/web/ShoppingCartWebImpl.java UNCHANGED: com/sun/estore/catalog/ejb/Catalog.java UNCHANGED: com/sun/estore/catalog/ejb/CatalogEJB.java UNCHANGED: com/sun/estore/catalog/ejb/CatalogHome.java UNCHANGED: com/sun/estore/catalog/model/CatalogDAO.java WARNING: com/sun/estore/catalog/model/CatalogImpl.java needs EJBContext properties if called WARNING: in EJB to lookup env-entry using java:comp/env/entryName, WARNING: or for indirect lookup of java:comp/env/subcontext/name. WARNING: Add an EJBContext variable to class and rerun conversion. MODIFIED: com/sun/estore/catalog/model/CatalogImpl.java import com.ibm.websphere.migrate.InitialContextMigrate; /*MIGRATION*/ InitialContextMigrate ic = new InitialContextMigrate(null/*properties object for env-entry*/); /*M UNCHANGED: com/sun/estore/catalog/model/CatalogModel.java UNCHANGED: com/sun/estore/catalog/model/Category.java UNCHANGED: com/sun/estore/catalog/model/InventoryItem.java UNCHANGED: com/sun/estore/catalog/model/Item.java UNCHANGED: com/sun/estore/catalog/model/Product.java UNCHANGED: com/sun/estore/catalog/web/CatalogWebImpl.java UNCHANGED: com/sun/estore/control/EStoreEventException.java MODIFIED: com/sun/estore/control/GeneralFailureException.java import com.ibm.websphere.migrate.EJBExceptionMigrate; /*MIGRATION*/ public class GeneralFailureException extends EJBExceptionMigrate /*MIGRATION*/ UNCHANGED: com/sun/estore/control/LoginFailedException.java UNCHANGED: com/sun/estore/control/ejb/ModelUpdateManager.java UNCHANGED: com/sun/estore/control/ejb/ShoppingClientController.java Figure 57. EJB conversion using the mg_convert Perl script Chapter 9. Migration example: The Java Pet Store 199 9.3.3 JNDI ENC changes Initially, this looked like the most complex issue we had to deal with. In retrospect, we probably spent more time on it than it deserved. The only cases that required changes are the env-entry cases. With that said, here is what we did. As indicated in Chapter 7, “Enterprise JavaBeans” on page 127, migrating from the EJB 1.1 JNDI default context to EJB 1.0 involves these aspects of the JNDI lookup code: 1. The type of the object being retrieved — this can be an env-entry, an ejb-ref, or a resource-ref such as a DataSource. 2. The scope of the JNDI name — this can be scoped to the EJB itself, or it can have a scope global to the JNDI server. 3. The syntax of the JNDI name — this varies between env-entry, JDBC DataSource objects, and other resources like ejb-ref. 4. The availability of the EJBContext Properties object. There are times when you need access to the EJBContext’s environment Properties object. This is required for env-entry lookups because that is where such values are found in Version 1.0 of EJBs. Unfortunately, depending on the structure of the code, you are not always guaranteed access to an appropriate EJBContext variable. This is true in the Java Pet Store example in the JNDIUtil and StateMachine classes. 5. The same JNDI lookup code may have to operate in multiple runtime environments, for example EJB 1.0 and Servlet 2.2 Finally, the Java Pet Store presented us with a special problem in the JNDIUtil.java class. This class does all of the JNDI lookups for EJBHome objects, and it is called from both the Servlet 2.2 environment and the EJB 1.0 environment. Any changes that impacted this class had to work properly in both of these environments. All JNDI ENC migration examples have the following pattern in the original code. This particular example is from EJBUtil.java InitialContext initial = new InitialContext(); Object objref = initial.lookup(JNDINames.ACCOUNT_EJBHOME); The object resulting from the lookup is then cast to its actual type. This may be a normal cast, as in the case of an Integer env-entry, or it may be a PortableRemoteObject.narrow cast, as in the case of an EJBHome. For our purposes, the type of cast does not matter. To make the required code changes as small as possible, we chose to use a helper class for the lookup 200 Migrating WebLogic Applications to WebSphere Advanced Edition method. In all cases, we converted code like that shown above to one of the following, depending on the presence of an EJBContext variable. 1. If an EBJContext variable is not available: InitialContextMigrate initial = new InitialContextMigrate (null/*properties object for env-entry*/); /*MIGRATION*/ Object objref = initial.lookup(JNDINames.ACCOUNT_EJBHOME); 2. If an EJBContext variable is available (the variable is ctx in this example): InitialContextMigrate ic = new InitialContextMigrate (ctx.getEnvironment()); /*MIGRATION*/ Boolean bool = (Boolean)ic.lookup(JNDINames.SEND_CONFIRMATION_MAIL); In either case, an import statement was added for the helper class: import com.ibm.websphere.migrate.InitialContextMigrate; /*MIGRATION*/ Notice that we have followed the convention of adding the comment /*MIGRATION*/ to every changed line of code, whether this line was changed automatically or by hand. All of the JNDI ENC changes were automated by the mg_convert script. If an EJBContext variable is not available, a warning is also generated to indicated that the EJBContext Properties object may be needed for proper execution. The EJBContext Properties object is required for EJB 1.0 env-entry lookups, but it is optional in other cases. Unfortunately, it is not possible to make this determination automatically. We also had to keep in mind the requirement discussed in step 5. on page 200 when designing these code changes; that is, the EJB 1.0/Servlet 2.2 cohabitation constraint. The pattern of changes for JNDI ENC are extremely simple, requiring the modification of a single constructor call from InitialContext() to InitialContextMigrate(Properties). The changes could easily be done by hand. VisualAge for Java, for example, offers search and edit commands that are more than adequate. In either case, the big payoff is to encapsulate the actual lookups into the InitialContextMigrate helper class. In particular, the env-entry lookups use the EJBContext Properties and also perform type conversions to the desired env-entry object type. Before looking at specific JNDI ENC examples from the Java Pet Store, we take a look at the InitialContextMigrate helper class. The InitialContextMigrate class is a wrapper for the standard javax.naming.InitialContext class. It replaces the behavior of the lookup(String) method to distinguish between the following cases at runtime, based on the value of the String argument. Chapter 9. Migration example: The Java Pet Store 201 • EJB env-entry Do the EJB 1.0 equivalent of an env-entry lookup for the JNDI name java:comp/env/envName. This means use the EJBContext Properties object provided by the InitialContextMigrate constructor to obtain an EJB 1.0 environment deployment String for envName. This was actually the only case we needed to change for the Java Pet Store. All other lookups worked with the unmodified JNDI names. An EJB 1.1 env-entry can be any of a number of Java wrapper types, for example, Integer or Boolean. Since Properties can only provide String types, the InitialContextMigrate optionally converts the retrieved String into the type specified by its first token. For example, a deployment value of “Integer 556” will construct an Integer(“556”) object. This convention impacts the environment values used for EJB deployment of the Java Pet Store. If no Properties object has been provided, we assume that this is a call from a Servlet. In this case, we just do the standard JNDI lookup. This convention allows EJBs 1.0 to live happily with Servlets 2.2, while using the same InitialContextMigrate helper class. This is important for the Java Pet Store because its JNDIUtil class is use by both EJBs and Servlets for all the different types of JNDI lookups. • Non-EJB env-entry This case is used by Servlets, and is indicated by passing null for the Properties parameter. The InitialContextMigrate lookup simply delegates to the standard InitialContext lookup. • JDBC env-resource For this case we use a standard InitialContext().lookup(). The only difference is the String provided to JNDI. Since we thought that JNDI naming might be a problem for DataSource lookups (see 8.2.1.1, “Binding a DataSource to a naming service” on page 159 for details), InitialContextMigrate provides a place to translate the JNDI name if needed. We discovered that no such translation was needed. • EJB ejb-ref This case is similar to the JDBC env-resource case, also allowing for translation of the JNDI name. Our experiments indicated that the EJB 1.1 java:comp/env/ejb/ejbName form works just fine for EJBHome lookups. • Other env-resource The Java Pet Store actually uses one non-JDBC env-resource. It is a reference to the javax.mail.Session, using java:comp/env/mail/MailSession for the JNDI name. Because of time 202 Migrating WebLogic Applications to WebSphere Advanced Edition constraints, we chose not to migrate this feature. However, the InitialContextMigrate class is a place for any special handling of such requests. The InitialContextMigrate class has two additional features that may be useful in some migration efforts. We did not actually use them with the Java Pet Store migration. For additional details, look at the InitialContextMigrate code in e:\petstore\migratelib. • If a Properties object is provided for a JDBC or EJB lookup, it is used to try to find an alias for the provided JNDI name. If one is found, it replaces the original name and is used for the actual JNDI lookup. Otherwise the original name is used for the JNDI lookup. This is useful when the JNDI resource name and the deployed name are different. This can be helpful during a transition phase of a larger migration project. • The InitialContextMigrate class can be configured to use a JNDI server other than the default name server for JDBC or EJB lookups. This is handy if you are using an incremental migration strategy and need to temporarily use resources in a different EJB or database server. 9.3.3.1 Summary of JNDI ENC changes No JNDI names had to be changed. The only essential changes were to use the InitialContextMigrate for the env-entry cases. All other JNDI lookups worked with the EJB 1.1 style of JNDI names. However, do not expect these names to provide EJB scoping in WebSphere, because that is not part of the EJB 1.0 Specification. To insure EJB scoping, use the EJBContext Properties object for aliasing as described above. Java Pet Store env-entry changes The Java Pet Store has two env-entry attributes: 1. JNDIUtil reads a Boolean from java:comp/env/sendConfirmationMail. JNDIUtil needed a bit of manual conversion because the original static method sendConfirmationMail() had no EJBContext available. We added an EJBContext ctx parameter to the method and to its only caller, StateMachine. These change were made directly in the e:\petstore\base directory. public static boolean sendConfirmationMail(EJBContext ctx){/*MIGRATION*/ InitialContextMigrate ic = new InitialContextMigrate(ctx.getEnvironment()); /*MIGRATION*/ Boolean bool = (Boolean)ic.lookup(JNDINames.SEND_CONFIRMATION_MAIL); The environment deployment value for sendConfirmationMail is “Boolean false”. Chapter 9. Migration example: The Java Pet Store 203 2. StateMachine reads a String from java:comp/env/securityAdapterClassName. This code also needed some manual conversion because the StateMachine class did not originally contain an EJBContext variable. We added the ejbCtx instance variable, by hand, and passed it to the constructor of StateMachine. It was also necessary to modify its only caller, ShoppingClientControllerEJB to pass its EJBContext object in the StateMachine constructor. InitialContextMigrate ic = new InitialContextMigrate(ejbCtx.getEnvironment()); /*MIGRATION*/ securityAdapterClassName = (String) ic.lookup(JNDINames.SECURITY_ADAPTER_CLASSNAME); Java Pet Store ejb-ref changes All EJBHome references are obtained by calling static methods in the EJBUtil class. These methods are called by Servlets and by EJBs, so modifications must work in both environments. All of these methods were changed automatically by the mg_convert script and they all follow the same pattern. public static AccountHome getAccountHome() { try { InitialContextMigrate initial = new InitialContextMigrate (null/*properties object for env-entry*/); /*MIGRATION*/ Object objref = initial.lookup(JNDINames.ACCOUNT_EJBHOME); Since these are all EJBHome lookups, there is no need to provide a Properties object to the InitialContextMigrate constructor. Indeed, since the JNDI lookup names — java:comp/env/ejb/account in this case — are not translated by the InitialContextMigrate lookup, behavior is identical to that of InitialContext. These changes can simply be ignored if you are not using the automated mg_convert script. Java Pet Store resource-ref changes OrderEJB, InventoryEJB, AccountEJB, and CatalogImpl were all automatically modified to use InitialContextMigrate to look up their DataSource objects. private Connection getDBConnection() throws SQLException { Connection connection; try { InitialContextMigrate ic = new InitialContextMigrate (context.getEnvironment()); /*MIGRATION*/ DataSource ds = (DataSource) ic.lookup(JNDINames.ESTORE_DATASOURCE); connection = ds.getConnection(); 204 Migrating WebLogic Applications to WebSphere Advanced Edition Since the semantics of these lookups are the same as the original code, these changes may be ignored if using hand editing. The CatalogImpl is one of the shared classes, used in both the Servlet and EJB environments. Consequently, it does not have an EJBContext variable available, so its InitialContextMigrate constructor takes null as its argument. protected Connection getDBConnection() { try { InitialContextMigrate ic = new InitialContextMigrate (null/*properties object for env-entry*/); /*MIGRATION*/ DataSource ds = (DataSource)ic.lookup(JNDINames.ESTORE_DATASOURCE); return ds.getConnection(); 9.3.4 EJBException changes As described in 7.3, “EJBException replaces RemoteException in EJBs” on page 130, this is a very simple change. We simply replaced the EJB 1.1 unchecked EJBException RuntimeException with a different EJB 1.0 unchecked RuntimeException, which we call EJBExceptionMigrate. EJBExceptionMigrate is unchecked because if extends java.lang.RuntimeException. This exception is defined in the provided com.ibm.websphere.migrate helper package. These changes were all automatically done by the mg_convert script, including the addition of the required import statement. The OrderEJB class provides numerous examples of this modification. It also affects AccountEJB, ShoppingClientControllerEJB, StateMachine, InventoryEJB, and MailerEJB. private Connection getDBConnection() throws SQLException { Connection connection; try { InitialContextMigrate ic = new InitialContextMigrate(context.getEnvironment()); /*MIGRATION*/ DataSource ds = (DataSource) ic.lookup(JNDINames.ESTORE_DATASOURCE); connection = ds.getConnection(); } catch (NamingException ne) { Debug.print(ne); throw new EJBExceptionMigrate(ne); /*MIGRATION*/ } catch (SQLException se) { Debug.print(se); throw new EJBExceptionMigrate(se); /*MIGRATION*/ } return connection; } Chapter 9. Migration example: The Java Pet Store 205 The Java Pet Store also defines its own unchecked RuntimeException by extending the EJB 1.1 EJBException. The same conversion works equally well for this situation, making the user-defined GeneratFailureException a subclass of EJBExceptionMigrate. import com.ibm.websphere.migrate.EJBExceptionMigrate; /*MIGRATION*/ public class GeneralFailureException extends EJBExceptionMigrate /*MIGRATION*/ With these changes in place, all of the “EJBException not handled” problems disappear from the All Problems window in Figure 56 on page 197. 9.3.5 Principal/Identity changes As described in 7.10, “Authentication method changes” on page 148, the EJB 1.0 Specification requires using the Identity type instead of the Principal type. This affects the getUserIdentity() and inCallerInRole(Identity) methods on the EJBContext object. The Java Pet Store OrderEJB and ShoppingClientControllerEJB classes make use of these methods. The mg_convert script automatically changes Principal to Identity. The isCallerInRole method requires the following slightly more complex change. This change was also automated. if (context.isCallerInRole (new IdentityMigrate("GOLD_CUSTOMER"))) { /*MIGRATION*/ IdentityMigrate is just a subclass of the abstract Identity class. These changes were successful in that they eliminated the original compiler errors, but the compiled code failed to execute properly in WebSphere. Without also enabling the WebSphere security feature, we got the NotImplementedeException at runtime. Because of time constraints, we did not pursue this problem further. As a workaround, we simply commented out the Java Pet Store security checking and used the j2ee user ID that is in the supplied database. // if ( context.isCallerInRole( // new IdentityMigrate("GOLD_CUSTOMER"))) { /*MIGRATION*/ and, // 206 String userId = sc.getCallerIdentity().getName(); /*MIGRATION*/ String userId = "j2ee"; /*MIGRATION*/ Migrating WebLogic Applications to WebSphere Advanced Edition 9.3.6 Collection finder changes As described in 7.6, “Finders expanded to Collection” on page 141, you must modify finder methods that return the Collection type. Collection is not a legal finder return type in EJB 1.0. You must use Enumeration instead. We only discovered this problem in the Java Pet Store when we tried to deploy it. It does not cause a compiler error. You will have to examine your code carefully to discover this problem earlier. It was easy to automatically locate and change the EJB and EJBHome finder methods headers from Collection to Enumeration. In the Java Pet Store, there are just two such finder methods, both in OrderEJB: public Enumeration ejbFindUserOrders( String userId ) /*MIGRATION*/ public Enumeration ejbFindByStatus( String status ) /*MIGRATION*/ Unfortunately, you also have to locate and change the EJB finder return values, and all client code that uses these finders. After the above change, you will find these quickly because of the resulting compiler errors. We made these changes manually. The finder return must convert its Collection to an Enumeration, and each client must convert its returned Enumeration back to a Collection. To reduce the amount of added code, we provided these intermediate conversions by means of helper methods in the EnumerationCollector class, found in the com.ibm.websphere.migrate package. public static Collection convertEnumeration(Enumeration enum) { Vector v = new Vector(); while (enum.hasMoreElements()) { v.add(enum.nextElement()); } return v; } public static Enumeration convertCollection(Collection col) { return new Vector(col).elements(); } Here are examples of their use, from OrderEJB and PendingOrdersBean, respectively. return(EnumerationConvertor.convertCollection (ODAO.findByStatus(dbConnection))); /*MIGRATION*/ Collection orderColl = EnumerationConvertor.convertEnumeration (home.findByStatus(Order.PENDING)); /*MIGRATION*/ These changes work for all implementations of Collection and Enumeration. The implementation of the Enumeration in the EJB code will in general be Chapter 9. Migration example: The Java Pet Store 207 different from the implementation of the Enumeration in the client code. Only the Enumeration interface is guaranteed. This is the same for Collection in EJB 1.1. 9.3.7 DB2 database support This is an example of a migration issue that we did not discover until runtime. You should plan on a few such problems in your migration efforts. In the Java Pet Store, the OrderEJB is only implemented for Oracle, Sybase, and CloudScape databases. These implementations are nicely packaged in their own classes — OrderDAOOracle, OrderDAOSybase, OrderDAOCS — each of which extends the abstract class OrderDAO. The correct implementation is selected at runtime by the following code: OrderDAO OD = null; String DBProductName = dbConnection.getMetaData().getDatabaseProductName().trim(); if (DBProductName.startsWith("Oracle")) { OD = new OrderDAOOracle(); else if (DBProductName.equals("SQL Server")) { OD = new OrderDAOSybase(); else if (DBProductName.equals("DBMS:cloudscape")) { OD = new OrderDAOCS(); } return OD; Our problem was that we had converted the PETSTORE database to DB2. This problem is an example of what is described in 8.2.3.4, “Migration issues when changing JDBC drivers or databases” on page 167. Database metadata is one of the JDBC openings into vendor-specific migration issues. Given the design of the Java Pet Store, the correct solution to this problem is to implement an OrderDAODB2 class and add it to the above case statement. Indeed, since this is a database migration problem, it should be done as an independent migration project. We do not show the details of the OrderDABDB2 class because it is not in the scope of this guide. Since this code is not exercised until final checkout from the Java Pet Store, most of the application runs without making this change. 9.4 Java Pet Store deployment In the ideal case, you deploy a J2EE application by providing the deployment tool with the application’s EAR file. This does not work for our Java Pet Store migration for several reasons: 208 Migrating WebLogic Applications to WebSphere Advanced Edition • WebSphere does not support EAR files. Although the J2EE reference platform supported EAR files early on, they have only recently become a part of the official J2EE specification. Neither WebSphere nor WebLogic support the EAR files. (See 2.2.2.3, “Java 2 Platform, Enterprise Edition (J2EE) specification” on page 22 for more details.) The next best approach is to separately deploy an EJB JAR file for the EJB server and a WAR file for the Web server. We use a variation on this approach. • We had to make source code changes. Even if EAR files were fully supported, we would have to reconstruct its contents because we have modified the source code. • Java Pet Store servlets and EJBs share code. The Java Pet Store EAR file contains separate copies of many of its classes — one for the servlets in the WAR file and another for the EJBs in a separate JAR file. Any classes that are used in common will be duplicated. For example, if you make a minor change to one of the shared classes, you must reconstruct both the WAR and the JAR files and redeploy the entire application. EJB deployment, in particular, is time consuming. Any shortcut to this process risks having different versions of the same classes in two different places, a typical cause of classpath errors. During our Java Pet Store mini-migration effort, we actually experienced this problem, and have therefore compensated for it in our deployment recommendations. • Incompatible deployment objects. The EJB 1.1 Specification uses a standard XML deployment object whereas the EJB 1.0 uses instances of the now-deprecated javax.ejb.deployment classes. During the course of this exercise, we experimented with several approaches to converting standard XML deployment descriptors into EJB 1.0 deployment objects. For our purpose, it turned out to be easier to just use a standard EJB 1.0 deployment tool to recreate the deployment descriptor objects from scratch. We experimented with the jetace, VisualAge for Java, and WebSphere deployment tools. For the Java Pet Store, VisualAge for Java turned out to be the most effective. Our source code was in VisualAge for Java, and we only had to go through the descriptor specification process once. • Deployment code generation alternatives. The EJB stubs and ties must be generated by either WebSphere or VisualAge for Java. One advantage of using VisualAge for Java is that it has a superior test environment. Unfortunately, we had problems trying to Chapter 9. Migration example: The Java Pet Store 209 use VisualAge for Java for EJB deployment and test. At the time of this writing, there was an outstanding defect that caused VisualAge for Java to hang during EJB deployment. We also tried using the deployment code generated by WebSphere as input to the VisualAge for Java test environment. We ran into serialization versioning problems. We were forced to choose WebSphere for deployment code generation. The bottom line is that we developed our own custom deployment process, which we describe here. As the deployment process evolves, a more standard approach will be possible in the future. A secondary advantage of the process described here is that you get to learn more about the structure and workings of WebSphere. We used the following deployment process for the Java Pet Store: 1. Use VisualAge for Java to create classes, EJBs, and deployment descriptors. 2. Create two different exports from VisualAge for Java — one for EJBs only, and one for everything else (including servlets and shared classes). 3. Modify the WebSphere classpath to add the Java Pet Store classes. 4. Use WebSphere to generate EJB deployment code. Refer to Table 8 on page 195 for our directory naming conventions. 9.4.1 VisualAge for Java steps We used VisualAge for Java to compile the Java Pet Store and create the EJBs. Most of the steps described here are only needed for the initial deployment. Once your projects are defined, you can redeploy as described in 9.4.3, “Redeployment cycle” on page 232. Redeployment is much simpler. The Java Pet Store depends on several other packages. We added these packages to VisualAge for Java just once. Also, the EJB deployment descriptors only need to be entered once. If you choose to hand modify the source code, then the source is only imported once. If you choose to use the mg_convert script, you will have to re-import the modified source code each time it changes. 9.4.1.1 Java Pet Store dependencies 1. Before you start, make sure that the following features have been added to your VisualAge for Java environment. See 4.1.1, “Installation” on page 60 for details. - IBM EJB Development 210 Migrating WebLogic Applications to WebSphere Advanced Edition - WebSphere Test Environment 2. Create projects containing Java Pet Store dependencies. The first three projects below contain packages on which the Java Pet Store depends. They have been provided as JAR files in e:\petstore\lib. You only need class files for these packages. Without these packages, you get a lot of undefined class compiler errors. The WebSphere Migrate project contains the source code for the migration helper classes. Import a directory of source code for this project. Of course, you need these classes only if you plan to use them for your own solution. Refer to 4.1.2, “Overview of useful VisualAge for Java features” on page 62 for details on defining VisualAge for Java projects. Table 9. Projects for Java Pet Store dependencies Project JAR files or source directory Sun XML e:\petstore\lib\sunxml.jar Java Activation e:\petstore\lib\activation.ja Java Mail e:\petstore\lib\mail.jar WebSphere Migration Package e:\petstore\migrate 3. You also need the servlet.jar from the WebSphere distribution. Import this into the existing Servlets project and version it with the one version option to make sure it is available as the default for your Java Pet Store project. 9.4.1.2 Compile Java Pet Store classes 1. Create a PetStore project and import the provided source code. - Import e:\petstore\base first. - Import e:\petstore\modify second. You only need the Java files from these directories. It is always a good idea to version your projects after each major modification as described in 4.1.2, “Overview of useful VisualAge for Java features” on page 62. To version the projects: a. Select PetStore -> manage -> open edition b. Select PetStore -> manage -> version, using the one option. 2. At this point, all of the PetStore code should have compiled correctly. Verify this by looking at the All Problems tab. If there are problems (other Chapter 9. Migration example: The Java Pet Store 211 than deprecated methods), then something is wrong — recheck the preceding steps. 9.4.1.3 Create EJB deployment descriptors 1. Click on the EJB tab and then create a new EJB group as described in 4.1.4, “EJB Development Environment” on page 71. Call it PetStoreEJBs. This group should be part of the PetStore project. 2. Create the EJBs. With the PetStoreEJBs selected, bring up the enterprise bean SmartGuide with the Add Enterprise Bean action. See Figure 58 on page 213. Step through the following process seven times — once for each EJB in the Java Pet Store. - Select Use an existing bean class. - Browse for the package. - Select the ejb package for the next EJB, for example com.sun.extore.account.ejb. - Click OK to fill in the Bean name. - Click Next to fill in initial home and remote class names. - Correct these names; for example AccountEJBHome should be AccountHome, and AccountEJB should be Account. VisualAge for Java assumes a slightly different naming convention for EJBs. With the ShoppingCartEJB, you will initially get an error about multiple ejbCreate methods. We will fix this soon. It is because the default for SessionBean is stateless, and a stateless SessionBean can only have one ejbCreate. 212 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 58. Create EJB in VisualAge for Java 3. Adjust EJB deployment attributes. See Figure 59. After each EJB has been added to the EJB group, go back and adjust the deployment attributes for each EJB. This includes the JNDI names, state management, and any environment reference attributes. - The correct JNDI names are shown in Table 10. - The state manager for ShoppingCartEJB should be #STATEFUL. Chapter 9. Migration example: The Java Pet Store 213 - Under the Environment tab, specify: • For MailerEJB, sendConfirmationMail has the value Boolean false. This is described on page 202. • For ShoppingClientControllerEJB, securityAdapterClassName has the value com.sun.estore.util.WebsphereSecurityAdapter. Table 10. Java Pet Store EJB JNDI names 214 EJB JNDI name AccountEJB java:comp/env/ejb/account CatalogEJB java:comp/env/ejb/catalog InventoryEJB java:comp/env/ejb/inventory MailerEJB java:comp/env/ejb/mail OrderEJB java:comp/env/ejb/order ShoppingCardEJB java:comp/env/ejb/card ShoppingClientControllerEJB java:comp/env/ejb/scc Migrating WebLogic Applications to WebSphere Advanced Edition Figure 59. Modify EJB deployment properties in VisualAge for Java 9.4.1.4 Export from VisualAge for Java to WebSphere 1. Export the EJB JAR file. Chapter 9. Migration example: The Java Pet Store 215 Figure 60. Export EJB JAR file Figure 61 on page 217 shows how to export the EJB JAR. Use a temporary location for the JAR file. Its contents will be imported into WebSphere at deployment time. We used d:\petstore\petstore.jar for this file. - Do not select referenced types and resources. This will expand the contents of the JAR to include all dependent classes. We want to keep the file size to a minimum. - Select beans and classes, but not java. There should be 7 beans and 21 classes — a remote, home, and ejb for each EJB. The 7 deployment objects are included as .ser files. This is the minimum required to deploy the EJBs into WebSphere. - Click Finish to create the JAR file. 2. Export all other classes. 216 Migrating WebLogic Applications to WebSphere Advanced Edition The PetStore and WebSphere Migrate projects contain all of the other classes, in particular, all of the classes shared between the Servlets and the EJBs. In fact, they also include the 21 classes already exported in the previous step. Of these, the home and remote classes are also needed by the Servlet clients. You could exclude the 7 EJB classes from the export, but we did not bother. See Figure 61 on page 217 for the details. Figure 61. Export Java Pet Store classes from VisualAge for Java - .Under the Projects tab, select both the PetStore and the IBM WebSphere Migrate projects. - Choose the Export action and Export to directory. You could export to a JAR, but a directory is easier to modify one class at a time. - Use the Servlet classes directory d:\WebSphere\petstore\classes. With this step you are actually doing part of the Servlet deployment for the Chapter 9. Migration example: The Java Pet Store 217 Java Pet Store. In a production environment, you should stop the PetStore Server before performing this step. - Only export the class files. We do not need the Java or resource files. - Click Finish to generate the directory. 9.4.2 WebSphere steps The steps described in this section accomplish the following: • Configure WebSphere for the various servers and DataSources required by the Java Pet Store. • Deploy the Web server components (Servlet and JSPs). • Deploy the EJBs. Most of this is done by standard WebSphere commands. However, due to the issues mentioned in 9.4, “Java Pet Store deployment” on page 208, a small bit of custom configuration is also required. The deployment of the Java Pet Store Web server requires the addition of two helper servlets. They are contained in the com.ibm.webshpere.migrate helper package, and have no impact on the Java Pet Store source code. Their deployment is describe in this section. • JNDIRegister Servlet. It was necessary to bind entries into the JNDI name space as a means of providing configuration information. WebSphere does not provide a way to do this via the administration console, and therefore a programmatic means of doing so was required. The easiest way we had was to write a servlet to perform the JNDI binding at initialization, and then configure WebSphere to load the servlet with the Web application. • ControllerServlet Servlet. Due to limitations in WebSphere, it was necessary to replace the Main.jsp file with a ControllerServlet, identical in features to the Main.jsp. For more details on these limitations, see 6.7.1.2, “Problems binding JSPs into servlets” on page 120. 9.4.2.1 Java Pet Store dependencies 1. Copy additional JAR files into WebSphere. 218 Migrating WebLogic Applications to WebSphere Advanced Edition The three JAR files that were needed by VisualAge for Java to compile Java Pet Store, are also needed at runtime. Copy them into the d:\WebSphere\AppServer\lib directory Table 11. WebSphere JARs for Java Pet Store dependencies JAR files WebSphere location e:\petstore\lib\sunxml.jar d:\WebSphere\AppServer\lib\sunxml.jar e:\petstore\lib\activation.jar d:\WebSphere\AppServer\lib\activation.jar e:\petstore\lib\mail.jar d:\WebSphere\AppServer\lib\mail.jar 2. Add these same JAR files to the classpath for WebSphere. Edit the configuration file d:\WebSphere\AppServer\bin\admin.config. Add three paths to the end of the very long classpath variable. Make sure your editor handles long lines, and make sure you get the syntax right. ;d:/WebSphere/AppServer/lib/sunxml.jar ;d:/WebSphere/AppServer/lib/activation.jar ;d:/WebSphere/AppServer/lib/mail.jar 3. Also add the deployed Java Pet Store classes directory to this classpath. ;d:/WebSphere/petstore/classes 4. You will have to restart the WebSphere server for these changes to take effect. You can use the NT Services to stop and start the IBM WebSphere Admin Server. 5. Use the WebSphere Data Source Wizard to define the two DataSources used by the Java Pet Store. Table 12. Java Pet Store DataSources DataSource name Database EstoreDataSource PETSTORE InventoryDataSource PETSTORE It is not necessary to add DataSources to the EJB container because there are no CMP EJBs in the Java Pet Store. 9.4.2.2 Create Java Pet Store application and deploy the EJBs 1. Create an application server on your machine node. Name the server PetStore Server. We will add an EJB container and a Web server to this application server. If you plan to do any debugging, it is handy to modify the working directory property of the application server to Chapter 9. Migration example: The Java Pet Store 219 a more convenient location. We changed it to d:\WebSphere\petstore. This is where you will find the sysout and syserr logs for debugging. 2. Create an EJB Container in the PetStore Server. Name it PetStore Container. 3. Create Enterprise Bean in the PetStore Container. Figure 62. Deploy EJBs in WebSphere See Figure 62. This is where we deploy the EJBs exported from VisualAge for Java. You will create all seven of the EJBs in one shot. - Browse for the JAR file. We put it in d:\petstore\petstore.jar. - Select the petstore.jar file. It is important to not click down inside of the JAR file. If you do, you will not deploy all of the contained EJBs and will probably get a error. See the Open window in Figure 62 on page 220. - Click Select . 220 Migrating WebLogic Applications to WebSphere Advanced Edition - Click Deploy Only. This takes a while. This is one of the reasons we separated all other classes from the EJBs. You are more apt to want to change one of the other classes and you can do that very quickly. This is where the deployment code is generated. You will get several OK confirmation windows, one for each EJB. Your PetStore Container should look like the one in Figure 73 on page 233. 9.4.2.3 Create servlet engine and deploy servlets We construct the Web server in a fashion similar to the EJBContainer. First we create a servlet engine. Then we define a Web application in the servlet engine. Finally, we populate the Web application with servlets. 1. Copy what should be the contents of the WAR file into the Web application directory d:\WebSphere\petstore. Table 13. Deploy Java Pet Store JSPs and tables Source directory Web application directory e:\petstore\original\jps1.0.1\src\docroot\* d:\WebSphere\petstore\web\* e:\petstore\original\jps1.0.1\src\lib\web-inf d:\WebSphere\petstore\web\web-inf Note the name change for the docroot. The d:\WebSphere\petstore\web directory now contains all of the HTML, JSP, and taglib files. This is part of the WAR file deployment process. Note that our migration requires no changes to the contents of these files. 2. Create servlet engine in the PetStore Server. Name it PetStore Servlet Engine. See Figure 63 on page 222. It is important to select the Full Compliance Mode option. This activates the Servlet 2.2 and JSP 1.1 versions required by the Java Pet Store. Chapter 9. Migration example: The Java Pet Store 221 Figure 63. Create Servlet Engine 3. Create Web application. Use the wizard to create a Web application. Do not simply add a servlet to the PetStore Servlet Engine. The reason is that the wizard automatically generates several useful servlets for error reporting and file serving. Figure 64, Figure 65, and Figure 66 show the basic wizard sequence. - The Web Application Name does not allow blanks. Name it PetStore. - Choose Enable File Servlet. - Choose Enable JSP 1.1. - Select PetStore Servlet Engine as the parent servlet engine. - In the Web Application Web Path field, enter /estore. Don’t forget the initial slash. - Click Next to continue with Web application advanced properties. 222 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 64. Create Web Application - step 1 Chapter 9. Migration example: The Java Pet Store 223 Figure 65. Create Web Application - step 2 224 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 66. Create Web Application - step 3 4. Specify advanced Web application properties. - The last page of the Create Web Application wizard is for advanced properties as shown in Figure 67. If you fail to complete this page, don’t panic because the same fields are available on the Advanced tab of the Web Application’s Properties window, also shown in Figure 68. Use the scrollbar to expose some of the options you need. - Document root is d:\WebSphere\petstore\web. - Classpath is d:\WebShpere\petstore\classes. - The Welcome Files is index.html. - The Error Pages maps the Exception java.lang.Exception to the Location /error. - You are done with the wizard. Click Finish. Chapter 9. Migration example: The Java Pet Store 225 Figure 67. Properties of a Web application Figure 68. Advanced properties of a Web application 5. Modify the Error Reporting Facility properties. 226 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 69. Set servlet error reporting path Error Reporting Facilities is one of the servlets created for you automatically. Use its General properties tab to change the Servlet Web Path as shown in Figure 69. - Click Edit to bring up a Path editor. - Change the path to error. You can only change part of this name. - Click OK ->Apply->OK. There is a lot of flexibility in the order for setting these properties. Indeed, Figure 69 shows a property being set after the creation of the helper servlets (which we haven’t described yet). 9.4.2.4 Create helper servlets The ControllerServlet is actually the main servlet. The JNDIRegister Servlet initializes the JNDI ENC for the PetStore Web application. Chapter 9. Migration example: The Java Pet Store 227 1. Create the ControllerServlet. See Figure 70. Figure 70. Configure Controller servlet - Create a servlet on the PetStore Web Application. - The servlet name is ControllerServlet. - ClassName is com.ibm.websphere.migrate.ControllerServlet. - Click Add to specify the Web Path as control/*. - Click OK->OK. 2. Create the JNDIRegister Servlet. See Figure 71 on page 230. This step is similar to the previous one, except that we use the Advanced tab to specify initialization parameters. - The Web Application name is PetStore. - The Servlet Name is JNDIRegister. - The Servlet Class Name is com.ibm.websphere.migrate.JNDIRegister. - There is no Web path because we don’t want users getting to this servlet. 228 Migrating WebLogic Applications to WebSphere Advanced Edition - On the Advanced tab: • Load at Startup is True (not False as shown in Figure 71). • Enter the following initialization parameters: Table 14. Servlet initialization parameters JNDI Name Value java:comp/env/useCatalogEJB false java:comp/env/ securityAdapterClassName com.ibm.websphere.migrate. WebSphereSecurityAdapter java:comp/env/serverType WebSphere • Click OK->OK. Chapter 9. Migration example: The Java Pet Store 229 Figure 71. Configure JNDIRegister servlet 230 Migrating WebLogic Applications to WebSphere Advanced Edition 9.4.2.5 Run Java Pet Store At this point, your WebSphere configuration should look like Figure 69 on page 227. You need to start the server and then run the Java Pet Store application. 1. Click PetStore Server->Start. After a little while, the appearance of the WebSphere configuration will change to that shown in Figure 72 on page 231. All of the servers, EJBs, and servlets change from stopped to running status. Figure 72. Start the application server 2. Access the Java Pet Store via your browser with the URL http://localhost/estore. Your browser will present pages like the ones shown in Figure 52 on page 184. Chapter 9. Migration example: The Java Pet Store 231 9.4.3 Redeployment cycle If your migration project is anything like ours, it did not work the first time through. We had multiple redeployment cycles to fix various problems as they were discovered. Here are the steps for a typical redeployment. 1. Modify source code, and possibly EJB deployment attributes, in the VisualAge for Java environment. You will be repeating some or all of the steps discussed in 9.4.1.2, “Compile Java Pet Store classes” on page 211 and 9.4.1.3, “Create EJB deployment descriptors” on page 212 2. Re-export classes from VisualAge for Java. This is described in 9.4.1.4, “Export from VisualAge for Java to WebSphere” on page 215. You will always need to re-export your classes. You only need to re-export EJBs if the EJBs or their deployment attributes change. VisualAge for Java makes this easy by remembering the path and file names. 3. Stop the PetStore Server. 4. If you had to re-export the EJBs, you need to redeploy them now. - First, remove each EJB from the PetStore Container as shown in Figure 73. 232 Migrating WebLogic Applications to WebSphere Advanced Edition Figure 73. Remove EJBs before redeployment - Redeploy the newly exported EJBs as described in step 3. on page 220. 5. Before restarting the PetStore Server, remove the sysout and syserr logs to make debugging easier. 6. Restart the PetStore Server. Chapter 9. Migration example: The Java Pet Store 233 234 Migrating WebLogic Applications to WebSphere Advanced Edition Appendix A. Using the additional material This redbook also contains additional material on the Internet. See the appropriate section below for instructions on using or downloading this material. A.1 Locating the additional material on the Internet The Web material associated with this redbook is also available on the Internet from the IBM Redbooks Web server. Point your Web browser to: ftp://www.redbooks.ibm.com/redbooks/SG245956 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. A.2 Using the Web material The additional Web material that accompanies this redbook includes the following: File name 5956code.zip Description Zipped Code Samples A.2.1 System requirements for downloading the Web material The following system configuration is recommended for downloading the additional Web material. Hard disk space: Operating System: 8 MB Windows NT or Windows 2000 A.2.2 How to use the Web material Create a subdirectory (folder) on your workstation and copy the contents of the Web material into this folder. The unzipped folder will contain example code as described in the chapters of this redbook. © Copyright IBM Corp. 2001 235 236 Migrating WebLogic Applications to WebSphere Advanced Edition Appendix B. Special notices This publication is intended to help developers migrate Java 2 Platform, Enterprise Edition application from BEA WebLogic Server 5.1 to WebSphere Application Server, Advanced Edition 3.5. The information in this publication is not intended as the specification of any programming interfaces that are provided by WebSphere Application Server, Advanced Edition 3.5. See the PUBLICATIONS section of the IBM Programming Announcement for WebSphere Application Server, Advanced Edition 3.5 for more information about what publications are considered to be product documentation. References in this publication to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent program that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program or service. Information in this book was developed in conjunction with use of the equipment specified, and is limited in application to those specific hardware and software products and levels. IBM may have patents or pending patent applications covering subject matter 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 the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The information contained in this document has not been submitted to any formal IBM test and is distributed AS IS. The use of this information or the implementation of any of these techniques is a customer responsibility and depends on the customer's ability to evaluate and integrate them into the customer's operational environment. While each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee © Copyright IBM Corp. 2001 237 that the same or similar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. Any pointers in this publication to external Web sites are provided for convenience only and do not in any manner serve as an endorsement of these Web sites. The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries: e (logo)® IBM ® RS/6000 SecureWay System/390 WebSphere XT Lotus eSuite PAL Redbooks Redbooks Logo S/390 SP VisualAge Wizard 400 Domino SP1 Notes The following terms are trademarks of other companies: Tivoli, Manage. Anything. Anywhere.,The Power To Manage., Anything. Anywhere.,TME, NetView, Cross-Site, Tivoli Ready, Tivoli Certified, Planet Tivoli, and Tivoli Enterprise are trademarks or registered trademarks of Tivoli Systems Inc., an IBM company, in the United States, other countries, or both. In Denmark, Tivoli is a trademark licensed from Kjøbenhavns Sommer - Tivoli A/S. C-bus is a trademark of Corollary, Inc. in the United States and/or other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States and/or other countries. PC Direct is a trademark of Ziff Communications Company in the United States and/or other countries and is used by IBM Corporation under license. ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United States and/or other countries. 238 Migrating WebLogic Applications to WebSphere Advanced Edition UNIX is a registered trademark in the United States and other countries licensed exclusively through The Open Group. SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others. Appendix B. Special notices 239 240 Migrating WebLogic Applications to WebSphere Advanced Edition Appendix C. Related publications The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook. C.1 IBM Redbooks For information on ordering these publications see “How to get IBM Redbooks” on page 245. • e-Commerce Patterns Using WebSphere Commerce Suite, Patterns for ebusiness Series , SG24-6156 • Servlet and JSP Programming with IBM WebSphere and VisualAge for Java, SG24-5755 • Application Server Solution Guide, Enterprise Edition: Getting Started, SG24-5320 • WebSphere V3 Performance Tuning Guide, SG24-5657 • WebSphere Scalability: WLM and Clustering Using WebSphere Application Server Advanced Edition, SG24-6153 • IBM WebSphere and VisualAge for Java Database Integration with DB2, Oracle, and SQL Server, SG24-5471 • IBM WebSphere Performance Pack: Load Balancing with IBM SecureWay Network Dispatcher, SG24-5858 • Design and Implement Servlets, JSPs, and EJBs for IBM WebSphere Application Server, SG24-5754 • Developing an e-business Application for the IBM WebSphere Application Server, SG24-5423 • Enterprise JavaBeans Development Using VisualAge for Java, SG24-5429 • WebSphere V3.5 Handbook, SG24-6161 C.2 IBM Redbooks collections Redbooks are also available on the following CD-ROMs. Click the CD-ROMs button at ibm.com/redbooks for information about all the CD-ROMs offered, updates and formats. © Copyright IBM Corp. 2001 241 CD-ROM Title Collection Kit Number IBM System/390 Redbooks Collection SK2T-2177 IBM Networking Redbooks Collection SK2T-6022 IBM Transaction Processing and Data Management Redbooks Collection SK2T-8038 IBM Lotus Redbooks Collection SK2T-8039 Tivoli Redbooks Collection SK2T-8044 IBM AS/400 Redbooks Collection SK2T-2849 IBM Netfinity Hardware and Software Redbooks Collection SK2T-8046 IBM RS/6000 Redbooks Collection SK2T-8043 IBM Application Development Redbooks Collection SK2T-8037 IBM Enterprise Storage and Systems Management Solutions SK3T-3694 C.3 Other resources These publications are also relevant as further information sources: • Flanagan, David, Jim Farley, William Crawford and Kris Magnusson, Java Enterprise in a Nutshell, O’Reilly & Associates, Inc. 1999, ISBN 1565924835 • Nagaratnam, Nataraj et al, Security Overview of IBM WebSphere Standard/Advance 3.02, IBM white paper, available at: http:// www.ibm.com/software/webservers/appserv/whitepapers.html • Shane Claussen and Mike Conner, Developing Dynamic Web Sites Using the WebSphere Application Server, available at: http://service2.boulder.ibm.com/devcon/news0399/artpage2.htm C.4 Referenced Web sites These Web sites are also relevant as further information sources: • http://www.ibm.com/software/webservers/appserv/ IBM Software WebSphere Application Server overview • http://java.sun.com/products/ejb/docs.html JavaBeans specifications page Sun’s Enterprise • http://www.ibm.com/software/ebusiness IBM’s Application Framework for ebusiness • http://www.ibm.com/software/developer/web/patterns/ IBM Patterns for ebusiness site • http://www.weblogic.com/docs51/resources.html BEA WebLogic Server 5.1 Documentation Center • http://java.sun.com/j2ee/ Java 2 Platform, Enterprise Edition 242 Migrating WebLogic Applications to WebSphere Advanced Edition • http://www.bea.com/products/weblogic/server/ BEA WebLogic Server • http://java.sun.com/products/jdk/1.2 Java 2 SDK, Standard Edition Version 1.2 Software • http://www.ibm.com/software/data/db2/udb/ DB2 Universal Database overview • http://www.weblogic.com/docs51/admindocs/properties.html Setting WebLogic properties • http://www.ibm.com/software/ad/vajava/ VisualAge for Java Overview • http://java.sun.com/j2ee/download.html Java 2 Platform, Enterprise Edition - Downloads and Specifications • http://www.ibm.com/software/webservers/httpservers/ IBM HTTP Server overview • http://java.sun.com/products/jsp/ JavaServer Pages technology • http://java.sun.com/products/jsp/download.html JavaServer Pages Technology download • http://www.weblogic.com/docs51/classdocs/API_jsp.html Using WebLogic JSP • http://java.sun.com/products/jsp/taglibraries.html JavaServer Pages Technology - Powering the Web Experience with Dynamic Content • http://www.javaworld.com/javaworld/jw-01-2000/jw-01-ssj-ejb2.html Create forward-compatible beans in EJB, JavaWorld January 2000 • http://www-4.ibm.com/software/webservers/appserv/doc/v35/a_as.htm WebSphere Application Server, Advanced Edition - software prerequisites • http://java.sun.com/products/jdbc/jdbc20.stdext.pdf JDBC 2.0 Standard Extension API • http://java.sun.com/j2se/1.3/docs/guide/jdbc/index.html Sun Microsystems JDBC documentation • http://www.beasys.com/products/weblogic/drivers.shtml BEA WebLogic jDriver Family • http://www.weblogic.com/docs/classdocs/API_joci.html Using jdbcKona/ Oracle • http://www.weblogic.com/docs/examples/dbkona/db2examples.html WebLogic 4.5 Simplifying JDBC programming with dbKona • http://developer.java.sun.com/developer/technicalArticles/J2EE/ deployathon2/BEAreadme.html Deploying the Java Pet Store application on WebLogic Server Appendix C. Related publications 243 • http://developer.java. sun.com/developer/onlineTraining/JSPIntro/ contents.html JavaServer Pages fundamentals, Short course contents • http://www.java.sun.com/j2ee/download.html#blueprints Download J2EE Blueprints including Java Pet Store from Sun Microsystems • http://www7b.boulder.ibm.com/wsdd/library/ WebSphere Developer Domain - Library 244 Migrating WebLogic Applications to WebSphere Advanced Edition How to get IBM Redbooks This section explains how both customers and IBM employees can find out about IBM Redbooks, redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided. • Redbooks Web Site ibm.com/redbooks Search for, view, download, or order hardcopy/CD-ROM Redbooks from the Redbooks Web site. Also read redpieces and download additional materials (code samples or diskette/CD-ROM images) from this Redbooks site. Redpieces are Redbooks in progress; not all Redbooks become redpieces and sometimes just a few chapters will be published this way. The intent is to get the information out much quicker than the formal publishing process allows. • E-mail Orders Send orders by e-mail including information from the IBM Redbooks fax order form to: In United States or Canada Outside North America e-mail address [email protected] Contact information is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl • Telephone Orders United States (toll free) Canada (toll free) Outside North America 1-800-879-2755 1-800-IBM-4YOU Country coordinator phone number is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl • Fax Orders United States (toll free) Canada Outside North America 1-800-445-9269 1-403-267-4455 Fax phone number is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl This information was current at the time of publication, but is continually subject to change. The latest information may be found at the Redbooks Web site. IBM Intranet for Employees IBM employees may register for information on workshops, residencies, and Redbooks by accessing the IBM Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materials repository for workshops, presentations, papers, and Web pages developed and written by the ITSO technical professionals; click the Additional Materials button. Employees may access MyNews at http://w3.ibm.com/ for redbook, residency, and workshop announcements. © Copyright IBM Corp. 2001 245 IBM Redbooks fax order form Please send me the following: Title Order Number First name Quantity Last name Company Address City Postal code Country Telephone number Telefax number VAT number Card issued to Signature Invoice to customer number Credit card number Credit card expiration date We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not available in all countries. Signature mandatory for credit card payment. 246 Migrating WebLogic Applications to WebSphere Advanced Edition Abbreviations and acronyms API Application Programming Interface BMP bean-managed persistence CMP container-managed persistence EJB Enterprise JavaBeans HTML HyperText Markup Language HTTP HyperText Transfer Protocol IBM International Business Machines Corporation IDE Integrated Development Environment ITSO International Technical Support Organization JDBC Java database connectivity JDK Java Development Kit JMS Java Message Service JNDI Java Naming and Directory Interface JSP JavaServer Pages J2EE Java 2 Platform, Enterprise Edition LDAP Lightweight Directory Access Protocol MVC Model-View-Controller WAS WebSphere Application Server WTE WebSphere Test Environment XML eXtensible Markup Language 2PC two-phase commit © Copyright IBM Corp. 2001 247 248 Migrating WebLogic Applications to WebSphere Advanced Edition Index A ACL 39 Apache 58, 78 application analysis 11 application redesign 13 application server create 45 architecture 4 Model 2 110 authentication form based 124 HTTP based 123 identity 148 operating system 122 principal 148 B BEA 17, 80 beans business logic 111 result beans 111 best practices 2 BMP 145, 177, 178 Bootstrap port 69 breakpoint 63 browser 5, 44, 111 business logic beans 111 C cache tag 87 CGI 109 problems 109 checkjspfiles 94 CICS 25 classpath 115 Client JAR 77 Cloudscape 51 CMP 20, 72, 127, 156, 165, 177 ejbCreate 145 CocoBase 84 COM 24 com.ibm.websphere.migrate 198 Common Gateway Interface 109 compileCommand 94 © Copyright IBM Corp. 2001 Composition Editor 59 configuration 33 connection pool 39 connection pooling 157, 163 ConnectionManager 158 console 63 container-managed persistence 20, 127, 165 D DAO 191 data access object 191 database 12, 155 configuration 51 migration 12 WebLogic connection 39 DataSource 39, 51, 63, 120, 157 add to WebSphere Test Environment 70 connecting 161 create 53 initial context 162 naming 159 DB2 33, 208 dbKona 175 debugger 63 Deployed JAR 77 deploying JSP 91 deployment descriptor 28, 74, 127, 139 development environment 33 DriverManager 158 E EJB container 29 create container 46 deployment descriptors 20 development environment 61, 71 finder methods 141 HomeHandle 144 migration issues 129 read only 150 EJB 2.0 Specification 73 EJB home 63, 72, 120 EJB JAR 77 EJB server 77 ejbCreate 145 EJBException 130, 193, 196 249 subclasses 134 EJBExceptionMigrate 133 EJBHome 144 ejb-ref 121, 134 lookups 137 ENC 193 enterprise archives 22 Enterprise JavaBeans 6, 19, 20 , 72, 127 create in VisualAge for Java 73 deployment descriptors 20 differences 20 importing to VisualAge for Java 76 specification 20 EnumerationConvertor 198 env-entry 121, 134 lookup 136 examples 8 F feature comparison 19 finder 141 Framework for e-business 14 H header names 117 HomeHandle 144 htmlKona 125 I IBM HTTP Server 41, 55 identity authentication 148 incremental migration 11 InitialContext 69, 136 InitialContextMigrate 136 installation 33 JDK 34 UDB 35 VisualAge for Java 56, 60 WebLogic 38 WebSphere 40 WebSphere Studio 55 InstantDB 41, 164 Internet Explorer 34 isCallerInRole 206 isModified method 150 250 J J2EE 1 applications 27 architecture 4 business object standard 176 feature levels 19 Reference Implementation server 83 references 120 specification 4, 22 Java 85 Java 2 Platform, Enterprise Edition 1, 31 Java Data Objects JDO 176 Java Message Service 22 Java Pet Store 8, 64, 111, 133, 181 architecture 188 collection finder changes 207 database 185, 190 database changes 208 deployment 208 EJBException 193 implementation 184 import in VisualAge for Java 64 JNDI 189 JNDI ENC 193 JNDI ENC changes 200 model 185 Principal/Identity changes 206 source changes 198 user interface 183 WebLogic implementation 195 Java Servlets 5, 18, 63, 78, 109 deploying in WebSphere 114 differences 21 migration examples 112 JavaScript 85 JavaServer Pages 5, 18, 85, 110 differences 21 JDBC 18, 21, 22, 70, 155 DriverManager 157 transactions 168 writing portable applications 173 JDBC driver 51, 70 VisualAge for Java 165 jdbcKona 174 JDK 33 installation 34 jDriver 174 jetace 76, 81, 141, 150, 209 Migrating WebLogic Applications to WebSphere Advanced Edition JMS 21, 22 JNDI 23, 63, 68, 120, 128, 130, 189 environment naming context 137, 193 lookups 29 resolving names 28 Jolt 24 JSP 78, 83 actions 85 declarations 85 deploying 91 deployment 85 directives 85 examples,WebLogic migrating JSP examples 100 expressions 85 samples 85 scriplets 85 securing 99 tags 85 XML tag format 87 JSP 1.1 Specification 86 JSP 1.2 Specification 86 JSP Compiler 63 JSP Execution Monitor 63, 66 JSP servlet 39, 91 JTA 52, 54, 164, 169 non-portable code 7 JDBC drivers 167 JTA 169 process 2, 10, 13 reasons 26 security 122, 123 sequence 11 strategies 26 testing 30 tools 83 transaction support 148 understanding the Java Pet Store 182 user database 122 migration testing environment 33 Model 2 architecture 110 Model-View-Controller 111 MVC 111, 189 N named references JNDI lookups 134 Netscape Communicator 34 O Oracle 164 K keepgenerated 95 L LDAP 122 M mg_convert 197 migration analysis 11 database 12 EJBs 127 examples 8, 33, 112 guide 2 issues 2, 6 documenting 9 J2EE specification 8 J2EE support 8 vendor services 8 vendor-specific 7 P pageCheckSeconds 93 Patterns for e-business 14, 15 persistence 150, 155 persistence access builder 61, 78 persistence manager 179 persistent name server 63, 68 portable code 2 principal authentication 148 process tag 88 protocol 52 PROVIDER_URL 69 R read-only attribute remote interfaces RemoteException repeat tag 88 resource-ref 121, lookups 137 150 72 130 134 251 result beans 111 S security 123 security migration 122 servlet engine 63 create 47 servlet mapping 119 ServletContext 121 source code 13 subprotocol 52 Sybase 164 T tag libraries 87, 98 tag library descriptor 89 Tengah Application Server 17 test system 30 TLD 99 Tomcat 33, 58, 61, 67, 78 TOPLink 24, 25, 84, 178, 192 transactions 148, 168 Tuxedo 24 U UDB 33 installation 35 unpackaged servlet 114 user database 122 UserTransaction 63 V verbose 95 Versant Object Container 84 VisualAge for Java 59, 196 add feature 61 configuring an EJB Server 77 console 63 create EJBs 73 EJB development environment 61 features 59 generating EJB deployed code 76 importing EJBs 76 installation 56, 60 JDBC driver 165 servlet engine 66 WebLogic Server integration 61 252 workbench 62 VisualAge for Java, Enterprise Edition 33 W WAR file 95, 113, 118 Web application 91 create 48 migrating 118 Web application design 110 Web path list 115 WebLogic 30, 33 5.1 17 database configuration 39 deploying JSPs 91 events 24, 25 feature comparison 19 information 17 installation 38 JSP configuration 39 start 39 testing 40 VisualAge Integration Kit 80 WebLogic Enterprise 17 weblogic.properties 39, 91 WebSphere 30 configuration 45 database configuration 51 deploying JSPs 92 examples 44 information 18 installation 40 JDBC drivers 166 JSP processors 92 test 42 WebSphere Administrative Console 43, 51, 92, 115 WebSphere feature comparison 19 WebSphere InfoCenter 51, 81 WebSphere software platform 18 WebSphere Studio 33, 83 installation 55 WebSphere Test Environment 52, 59, 61, 65, 165 add DataSource 70 Control Center 66 starting 66 workbench 62 workingDir 94 workspace 61 Migrating WebLogic Applications to WebSphere Advanced Edition WTE see WebSphere Test Environment 65 X XML 20, 81, 87, 125 deployment descriptor 139 descriptors 74 253 254 Migrating WebLogic Applications to WebSphere Advanced Edition IBM Redbooks review Your feedback is valued by the Redbook authors. In particular we are interested in situations where a Redbook "made the difference" in a task or problem you encountered. Using one of the following methods, please review the Redbook, addressing value, subject matter, structure, depth and quality as appropriate. • Use the online Contact us review redbook form found at ibm.com/redbooks • Fax this form to: USA International Access Code + 1 845 432 8264 • Send your comments in an Internet note to [email protected] Document Number Redbook Title SG24-5956-00 Migrating WebLogic Applications to WebSphere Advanced Edition Review What other subjects would you like to see IBM Redbooks address? Please rate your overall satisfaction: O Very Good Please identify yourself as belonging to one of the following groups: O Customer O Business Partner O IBM, Lotus or Tivoli Employee O None of the above Your email address: The data you provide here may be used to provide you with information from IBM or our business partners about our products, services or activities. O Please do not use the information collected here for future marketing or promotional contacts or other communications beyond the scope of this transaction. Questions about IBM’s privacy policy? The following link explains how we protect your personal information. ibm.com/privacy/yourprivacy/ © Copyright IBM Corp. 2001 O Good O Average O Poor O Solution Developer 255 Migrating WebLogic Applications to WebSphere Advanced Edition (0.5” spine) 0.475”<->0.875” 250 <-> 459 pages ® Migrating WebLogic Applications to WebSphere Advanced Edition Understanding the migration issues and preparing a migration strategy Guidelines for writing portable applications Considerations for completing and implementing a migration The WebSphere Application Server, Advanced Edition provides a leading implementation of Java 2 Platform, Enterprise Edition technologies including Java Servlets, JavaServer Pages, and Enterprise JavaBeans. A primary competitor to WebSphere is BEA WebLogic Server, with support for the same programming technologies. In theory, a developer could write and deploy applications using WebLogic and move them to WebSphere without code changes. In practice, there are nuances in the implementations of the technologies that a developer and systems integrator should be aware of. INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION This redbook will help you plan the migration of an application developed for BEA WebLogic Server, so that the application will run on WebSphere Application Server, Advanced Edition. We explain the differences between the implementations of WebLogic and WebSphere, provide guidance to developers on how to deploy existing applications from WebLogic to WebSphere, and discuss how to design portable new applications that may be deployed on WebSphere or WebLogic. 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. BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE For more information: ibm.com/redbooks SG24-5956-00 ISBN 073841722X
