Migrating WebLogic Applications to WebSphere Advanced Edition

Migrating WebLogic Applications to WebSphere Advanced Edition
Migrating WebLogic
Applications to WebSphere
Advanced Edition
Understanding the migration issues
and preparing a migration strategy
Guidelines for writing portable
Considerations for completing
and implementing a migration
Bill Moore
Robert Janker
Benjamin Papez
Leigh Power
Robert Watkins
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.
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
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
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
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
Migrating WebLogic Applications to WebSphere Advanced Edition
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
(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
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
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]
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 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.
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
These specifications correspond roughly to chapters in this book. If you are
not familiar with a particular specification, you may choose to skip that
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
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.
Migrating WebLogic Applications to WebSphere Advanced Edition
J2EE Application
Tier 1
Info Tier 4
JDBC DataSource
JDBC DataSource
Lookup properties, resources,
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
• 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
• 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
• Perform actual migrations of simple examples.
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
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
• 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
• 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
• Vendors provide needed services that are not yet covered by the J2EE
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:
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
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
• 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
Where appropriate, we have documented migration issues according to this
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
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
• 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
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.
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
• 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
• 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/. 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
Migrating WebLogic Applications to WebSphere Advanced Edition 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
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:
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
• Chapter 4, “Development tools” on page 59
Chapter 1. Introduction
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.
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
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/
© Copyright IBM Corp. 2001
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
Commerce Suite
for Java
Voice Server Personalization
Portal Server
Web Content
WebSphere Site
Edge Server
WebSphere Application Servers
Red Hat
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.
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
Enterprise JavaBeans (EJB)
JavaServer Pages (JSP)
Servlet and Web applications
Chapter 2. Features comparison and migration strategy
19 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
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/
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
For further information on the differences between WebLogic and
WebSphere, with regards to Enterprise JavaBeans, see Chapter 7,
“Enterprise JavaBeans” on page 127.
Migrating WebLogic Applications to WebSphere Advanced Edition 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
For further information on the differences between WebLogic and
WebSphere, with regards to Java Server Pages, see Chapter 5, “JavaServer
Pages” on page 85. 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
JMS interface to MQ
Full J2EE Specification
Chapter 2. Features comparison and migration strategy
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
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. 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. 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.
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 =
The java:comp/env name space is set up by the WebLogic container, and is
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 =
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
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
TOPLink For WebLogic
TOPLink For WebSphere 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. 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.
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. 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
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. 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 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
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
• 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.
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
• 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
Web Browser
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. 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
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:
<description>My EJB</description>
Migrating WebLogic Applications to WebSphere Advanced Edition
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 =
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
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. 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. 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/
For more information about WebSphere, see http://www.ibm.com/software/
Migrating WebLogic Applications to WebSphere Advanced Edition
For more information about Java 2 Platform, Enterprise Edition, see http://
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
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
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
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
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
Migrating WebLogic Applications to WebSphere Advanced Edition
do here. The exact level was (you can test with “java -version” at a command
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
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
4. Open the DB2 Command Center and execute the script shown in Figure 7.
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
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://
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
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
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://
2. Database configuration
To setup the database connection to DB2 you have to edit the WebLogic
properties for setting the connection pool
and the DataSource:
To add an ACL for the connection pool:
To enable WebLogic Server finding all the necessary classes and
resources for accessing DB2 you have to append the following directories
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.
4. Start WebLogic Server.
Chapter 3. Configuration
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
5. Test WebLogic Server.
Now you can open a browser and try the URL http://localhost:7001/
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.
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
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.
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
Figure 13. Starting default host
Now you can start a browser and try one of the example applications:
If your installation was successful there should be the output shown in
Figure 14.
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
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
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.
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
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.
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
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
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
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
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
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
3. From the driver combobox select the JDBC driver you want to use.
We selected the Cloudscape JDBC driver we have just configured
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
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
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:
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:
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:
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
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
Figure 23. VisualAge Quick Start
3. Select the features shown in Figure 24.
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:
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
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
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
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
• 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
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
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/
• 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
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.
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
1. Open the Quick Start panel either by pressing F2 or clicking File -> Quick
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
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.
VisualAge for Java
WebSphere Test
EJB Development
Web Application
EJB Server(s)
JSP Compiler
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
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
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
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.
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
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 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
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
Figure 28 shows an example of the JSP Execution Monitor in use.
Figure 28. JSP Execution Monitor
Chapter 4. Development tools
More information about the setup and the handling of this tool can be
found in the VisualAge for Java online help at:
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. 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
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. 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
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, “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
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
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
Migrating WebLogic Applications to WebSphere Advanced Edition
functionality, but similar functions will be mandated by the EJB 2.0
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/
• Using the EJB Development Environment overview: http://
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. 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
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:
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
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
Chapter 4. Development tools
75 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. 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
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. 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
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
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
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
More information about this feature and manuals on how to use it can be
found in the IBM VisualAge for Java online help documentation:
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
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:
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
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
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
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
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
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:
Chapter 4. Development tools
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
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, “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
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
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
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.
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
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
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
full support
full support
not supported:
- portable tag extension
- 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:
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
Chapter 5. JavaServer Pages
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
More information about how to use these tags can be found at http://
We developed the following small sample JSP (testbeatags.jsp) to use these
three tags:
<!doctype html public "-//w3c/dtd/HTML 4.0//en">
<!-- no Copyright -->
<title>Use of BEA Tags Example</title>
<%@ page import="java.util.Date" %>
<%@ taglib uri="/taglib.tld" prefix="wl" %>
<body bgcolor=#ffffff>
<font color=#DB1260>
<h1>CACHE TAG</h1>
The current date is <%= new Date() %>.
<wl:cache timeout ="5s">
The 5 seconds cached date is <%= new Date() %>.
<wl:cache timeout ="10s">
<p> The 10 seconds cached date is <%= new Date() %>.
<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%>
<h1>PROCESS TAG</h1>
<wl:process notname="1">
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"/>
<wl:process name=" 1 ">
<p> you selected 1
<wl:process name=" 2 ">
<p> you selected 2
<p> <a href="./testbeatags.jsp">Click Here</a> to start again!
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
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
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
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
D:\WebSphere\AppServer\hosts\default_host\ITSO Web
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
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:
The Web application can be specified as an expanded directory hierarchy,
for example:
Or as an archived format (.war file):
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:
You can simply copy your JSPs to the directory:
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:
Chapter 5. JavaServer Pages
compileCommand=<path to javac>,\
workingDir=<path to output directory>,\
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. 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.
Migrating WebLogic Applications to WebSphere Advanced Edition
Figure 33. JSP servlet settings in a WebSphere application 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:
Every request
Amount of time in seconds before next check
Chapter 5. JavaServer Pages
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:
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.
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. The compileCommand parameter
The WebLogic parameter compileCommand has no equivalent in
WebSphere. 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
Servlet name
Location of Java and class files produced
JSP 1.1
JSP 1.0
JSP 0.91
Migrating WebLogic Applications to WebSphere Advanced Edition 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. 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
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.
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
Chapter 5. JavaServer Pages
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
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
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, /
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
2. Copy all the files from D:\weblogic\examples\jsp\ to the JSPExamples
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
5. Now open a browser and try the following URL http://localhost/itso/
6. Select HelloWorld.jsp and choose the run link
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" %>
<%@ page isErrorPage="true" import="java.io.PrintStream" %>.
Then the sample works. Start it with the URL http://localhost/itso/
• 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>
Start the sample with the URL
• SessionServlet
Add the line <%@ import="java.util.Enumeration" %> to the file. The URL to
start the sample is:
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
e. Create a new directory:
D:\WebSphere\AppServer\hosts\default_host\ITSO Web
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
g. Copy pagehits.jsp from D:\weblogic\examples\jsp\tagext\counter to
D:\WebSphere\AppServer\hosts\default_host\ITSO Web
h. Copy counter.tld from D:\weblogic\examples\jsp\tagext\counter to
D:\WebSphere\AppServer\hosts\default_host\ITSO Web
i. Run the example from your browser with the URL http://localhost/
• 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">
<!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.
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
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.
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
m. In the file
change the first appearance of:
<%@ include file="CodeTag.java" %>
<%@ 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
• 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">
<!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">
<title>JSP DATE EXAMPLE</title>
<jsp:directive.page import="java.util.Date" />
<body bgcolor=#ffffff>
<font color=#DB1260>
Migrating WebLogic Applications to WebSphere Advanced Edition
<h1>JSP DATE</h1>
The date is <jsp:expression> new Date() </jsp:expression>.
Chapter 5. JavaServer Pages
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
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
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.
Logic Bean
Java Applet
Server Bean
Figure 43. Model 2 architecture
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
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
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:
These examples were migrated with no code changes.
The examples that were not migrated are:
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.
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
The lessons learned during these migrations are documented within this
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
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
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
• You need to determine the initialization parameters that the servlet will
The last two items can be determined by examining your weblogic.properties
file. Consider the following entry:
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
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.
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
- The initialization parameters are on the Advanced tab of the Create
Servlet dialog.
Chapter 6. Java Servlets
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.
Migrating WebLogic Applications to WebSphere Advanced Edition 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
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. 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
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
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.
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 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:
Chapter 6. Java Servlets
The correct servlet-mapping would be:
</servlet-mapping> 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:
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.
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
Values passed in as attributes on the servlet engine are available via the
getAttribute() method on the servlet Context (available via
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 =
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
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. 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
Figure 48. Selecting the authentication mechanism
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
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. 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
Figure 49. Setting the challenge type
Selecting a challenge type of Basic (User ID and Password) will configure
WebSphere to use HTTP-based authentication. Configuring WebSphere to use form-based authentication
WebSphere can be configured to use form-based authentication. To do this,
follow the steps outlined in, “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.
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
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
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
(servlet, application)
lookup resource
lookup resource
CMP & transactions
deployment descriptors
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.
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
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
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
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
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
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
EJB 1.1
EJB 1.0
[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.
Deprecated but supported.
Behavior same as for
Container throws
RemoteException [note 3].
Any client transaction is not
marked for rollback.
Chapter 7. Enterprise JavaBeans
EJB 1.1
EJB 1.0
[note 2]
Container throws
RemoteException [note 3].
Any client transaction is
marked for rollback.
Not defined [note 4].
Other unchecked
Container throws
RemoteException [note 3].
Any client transaction is
marked for rollback.
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();
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);
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
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 {
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-
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
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
type: Integer, Boolean, Double,
Byte, Short, Long, Float,
local scope: JNDI lookup by
global scope: JNDI lookup by
(possible, but not currently
type: String.
local scope: EJBContext
environment properties
global scope: not supported.
Chapter 7. Enterprise JavaBeans
object type
EJB 1.1
EJB 1.0
type: EJBHome.
local scope: JNDI lookup by
global scope: JNDI lookup by
type: EJBHome.
local scope: not supported.
global scope: JNDI lookup by
(only JDBC
resource shown)
type: DataSource.
local scope: JNDI lookup by
global scope: JNDI lookup by
type: DataSource.
local scope: not supported.
global scope: JNDI lookup by
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
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:
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
• Manually manage the global JNDI name space to avoid conflicts.
• Provide indirection using the EJB 1.0 environment properties.
• Deploy with full ENC names. 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
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. 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:.
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
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. 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:
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
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?
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, “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
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
- 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
- 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
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
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
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
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, “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
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 {
dbConnection = getDBConnection();
ArrayList orderIdList = new ArrayList();
Statement stmt = dbConnection.createStatement();
ResultSet result = stmt.executeQuery(userOrderSelect(uid));
if ( !result.next() ) {
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 {
} 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.
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()) {
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
• Modify the EJB method to return an Enumeration.
public Enumeration ejbFindOrders(String uid) throws FinderException {
ArrayList orderIdList = new ArrayList();
return convertCollection(orderIdList); // Order primary keys
• Modify the Home interface Finder method declaration to return an
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
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
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
HomeHandle homeRef = home.getHomeHandle();
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.
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();
public AccountHome getAccountHome ()
throws RemoteException, IOException, ClassNotFoundException {
String jndiName = (String)someStream.readObject();
InitialContext ctx = new InitialContext();
AccountHome home = (AccountHome)ProtableRemoteObject.narrow
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
• 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
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 {
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 {
return ;
public class BMPOrderEJB implements EJBEntity extends BMPOrderImpl {
public Integer ejbCreate() throws CreateException {
return ejbCreateImpl();
Chapter 7. Enterprise JavaBeans
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.
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
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
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”));
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://
Chapter 7. Enterprise JavaBeans
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
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
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
• 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
Chapter 7. Enterprise JavaBeans
• 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
• Use of UserTransaction tightened
The container must provide UserTransaction interface in JNDI context
• 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
• Primary key can be java.lang.String
This is not a problem in WebSphere because it already supports String
primary keys.
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
• 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
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
JDBC features, and that the role of proprietary extensions will become less
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
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
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
JNDI Naming
lookup( )
jdbc/example DS
Se rve
ber Descr
getConnection( )
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
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. 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:
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.
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
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
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 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. 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.
Migrating WebLogic Applications to WebSphere Advanced Edition
In the class where you want to obtain the DataSource, import the following
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();
Context ctx = new InitialContext(env);
catch (NamingException e)
// handle exception
And for WebSphere it would look like this:
Hashtable env = new Hashtable();
Context ctx = new InitialContext(env);
catch (NamingException e)
// handle exception
Chapter 8. Database connectivity and persistence
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:
Context ctx = new InitialContext();
DataSource ds = (DataSource) ctx.lookup("jdbc/EstoreDB");
Connection conn = ds.getConnection();
// execute query
// process results
(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.
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
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;
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
if (conn != null)
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
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 :
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. 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
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,
“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. 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
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. 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:
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
Migrating WebLogic Applications to WebSphere Advanced Edition
DataSource runable on both systems. They are mainly for performance
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. 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
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
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
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
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. 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/
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;
Context ctx = null;
Hashtable env = new Hashtable();
// Parameters for the WebLogic Server.
// Substitute the correct hostname, port number
// user name, and password for your environment:
Chapter 8. Database connectivity and persistence
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)
// Start a transaction on the current thread:
// 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:
// 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.
// or:
catch (Exception e)
Migrating WebLogic Applications to WebSphere Advanced Edition
if (conn != null)
if (tx != null)
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
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
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.”
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
• 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
• 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
- 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
- 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
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://
For details of using the jdbcKona family of JDBC drivers: http://
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.");
// 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");
for (int i = 0; i < ts2.size(); i++) {
Chapter 8. Database connectivity and persistence
Record rec = ts2.getRecord(i);
rec.setValue("ename", "Worker " + i);
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
For an overview of dbKona architecture see: http://www.weblogic.com/docs/
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.
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
• The WebLogic Server RDBMS Persistence for trivial entity bean
• 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
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
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
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:
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. 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
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
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
• 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.
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
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
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
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
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
Chapter 9. Migration example: The Java Pet Store
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:
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
• 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.
Migrating WebLogic Applications to WebSphere Advanced Edition
Figure 53. Java Pet Store directory and package structure
Chapter 9. Migration example: The Java Pet Store
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
names of
5 [events]
6 [updates model]
2 [returns list
of updated
EJB server
EJB -- state
updates EJBs
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
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
• 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
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:
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.
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.
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
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
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. 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. 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.
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:
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
• 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
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
• 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. 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. 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/
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
Table 8. Directory path naming conventions
Directory path
Distributed WebSphere Java Pet Store solution
WebSphere installation
Temporary EJB export directory
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
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
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
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.
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
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.
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
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
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;
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
• 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
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, “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
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
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. 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
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
Chapter 9. Migration example: The Java Pet Store
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)
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)
connection = ds.getConnection();
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 =
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)
connection = ds.getConnection();
} catch (NamingException ne) {
throw new EJBExceptionMigrate(ne); /*MIGRATION*/
} catch (SQLException se) {
throw new EJBExceptionMigrate(se); /*MIGRATION*/
return connection;
Chapter 9. Migration example: The Java Pet Store
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*/
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
public static Collection convertEnumeration(Enumeration enum) {
Vector v = new Vector();
while (enum.hasMoreElements()) {
return v;
public static Enumeration convertCollection(Collection col) {
return new Vector(col).elements();
Here are examples of their use, from OrderEJB and PendingOrdersBean,
(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
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 =
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, “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:
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, “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
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
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. 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
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
JAR files or source directory
Java Activation
Java Mail
WebSphere Migration Package
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. 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
than deprecated methods), then something is wrong — recheck the
preceding steps. 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
- 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
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
- 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
JNDI name
Migrating WebLogic Applications to WebSphere Advanced Edition
Figure 59. Modify EJB deployment properties in VisualAge for Java Export from VisualAge for Java to WebSphere
1. Export the EJB JAR file.
Chapter 9. Migration example: The Java Pet Store
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
- 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.
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
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, “Problems binding JSPs into
servlets” on page 120. Java Pet Store dependencies
1. Copy additional JAR files into WebSphere.
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
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.
3. Also add the deployed Java Pet Store classes directory to this classpath.
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
It is not necessary to add DataSources to the EJB container because
there are no CMP EJBs in the Java Pet Store. 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
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
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 .
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. 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
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
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.
Migrating WebLogic Applications to WebSphere Advanced Edition
Figure 64. Create Web Application - step 1
Chapter 9. Migration example: The Java Pet Store
Figure 65. Create Web Application - step 2
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
Figure 67. Properties of a Web application
Figure 68. Advanced properties of a Web application
5. Modify the Error Reporting Facility properties.
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). 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
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
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
• Click OK->OK.
Chapter 9. Migration example: The Java Pet Store
Figure 71. Configure JNDIRegister servlet
Migrating WebLogic Applications to WebSphere Advanced Edition 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
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
Your browser will present pages like the ones shown in Figure 52 on
page 184.
Chapter 9. Migration example: The Java Pet Store
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, “Compile Java Pet Store classes” on page 211
and, “Create EJB deployment descriptors” on page 212
2. Re-export classes from VisualAge for Java.
This is described in, “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.
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
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
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:
Alternatively, you can go to the IBM Redbooks Web site at:
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
File name
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
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
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
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)®
Redbooks Logo
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
C-bus is a trademark of Corollary, Inc. in the United States and/or other
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and/or other
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.
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
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,
• 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
CD-ROM Title
Collection Kit
IBM System/390 Redbooks Collection
IBM Networking Redbooks Collection
IBM Transaction Processing and Data Management Redbooks Collection SK2T-8038
IBM Lotus Redbooks Collection
Tivoli Redbooks Collection
IBM AS/400 Redbooks Collection
IBM Netfinity Hardware and Software Redbooks Collection
IBM RS/6000 Redbooks Collection
IBM Application Development Redbooks Collection
IBM Enterprise Storage and Systems Management Solutions
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
• Nagaratnam, Nataraj et al, Security Overview of IBM WebSphere
Standard/Advance 3.02, IBM white paper, available at: http://
• Shane Claussen and Mike Conner, Developing Dynamic Web Sites Using
the WebSphere Application Server, available at:
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
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
• 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
• 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
• 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/
• 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
• 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
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:
• Telephone Orders
United States (toll free)
Canada (toll free)
Outside North America
Country coordinator phone number is in the “How to Order”
section at this site:
• Fax Orders
United States (toll free)
Outside North America
Fax phone number is in the “How to Order” section at this site:
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
IBM Redbooks fax order form
Please send me the following:
Order Number
First name
Last name
Postal code
Telephone number
Telefax number
VAT number
Card issued to
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.
Migrating WebLogic Applications to WebSphere Advanced Edition
Abbreviations and acronyms
Programming Interface
Enterprise JavaBeans
HyperText Markup
HyperText Transfer
International Business
Machines Corporation
International Technical
Support Organization
Java database
Java Development Kit
Java Message Service
Java Naming and
Directory Interface
JavaServer Pages
Java 2 Platform,
Enterprise Edition
Lightweight Directory
Access Protocol
WebSphere Application
WebSphere Test
eXtensible Markup
two-phase commit
© Copyright IBM Corp. 2001
Migrating WebLogic Applications to WebSphere Advanced Edition
ACL 39
Apache 58, 78
analysis 11
application redesign 13
application server
create 45
architecture 4
Model 2 110
form based 124
HTTP based 123
identity 148
operating system 122
principal 148
BEA 17, 80
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
cache tag 87
CGI 109
problems 109
checkjspfiles 94
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
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
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 server 77
ejbCreate 145
EJBException 130, 193, 196
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
feature comparison 19
finder 141
Framework for e-business 14
header names 117
HomeHandle 144
htmlKona 125
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
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 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
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
named references
lookups 134
Netscape Communicator 34
Oracle 164
keepgenerated 95
LDAP 122
mg_convert 197
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
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
read-only attribute
remote interfaces
repeat tag 88
resource-ref 121,
lookups 137
result beans 111
security 123
security migration 122
servlet engine 63
create 47
servlet mapping 119
ServletContext 121
source code 13
subprotocol 52
Sybase 164
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
UDB 33
installation 35
unpackaged servlet 114
user database 122
UserTransaction 63
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
workbench 62
VisualAge for Java, Enterprise Edition 33
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,
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
XML 20, 81, 87, 125
deployment descriptor 139
descriptors 74
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
Migrating WebLogic Applications to WebSphere Advanced Edition
What other subjects would you
like to see IBM Redbooks
Please rate your overall
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
The following link explains how we protect your personal information.
© Copyright IBM Corp. 2001
O Good
O Average
O Poor
O Solution Developer
Migrating WebLogic Applications to WebSphere Advanced Edition
(0.5” spine)
250 <-> 459 pages
Migrating WebLogic
Applications to WebSphere
Advanced Edition
Understanding the
migration issues and
preparing a
migration strategy
Guidelines for
writing portable
Considerations for
completing and
implementing a
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.
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
IBM Redbooks are developed by
the IBM International Technical
Support Organization. Experts
from IBM, Customers and
Partners from around the world
create timely technical
information based on realistic
scenarios. Specific
recommendations are provided
to help you implement IT
solutions more effectively in
your environment.
For more information:
ISBN 073841722X
Was this manual useful for you? yes no
Thank you for your participation!

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

Download PDF