=============================================================
It takes a good developer many hours to get up-and-running with
EJB with no assistance. An immense amount of work has been put into this
code to get you going with EJB quickly and painlessly. There are full build
scripts and instructions for using BEA WebLogic. Without much effort, you
should be able to get the examples compiled and running, and you'll then be
prepared to use the examples as templates for your own beans.
=============================================================

This README file details how to install and configure the software and
sample code from the book. Before you install, be sure to check the book's
accompanying Web site for any source code updates. The Web site is:

http://www.TheServerSide.com/books/masteringEJB

--------------------------------------------------------------
General Install Notes
--------------------------------------------------------------

* FOR BEST RESULTS, READ THIS README FILE COMPLETELY AND FOLLOW THE DIRECTIONS
IN THIS README FILE EXACTLY. DO NOT SKIP ANY STEPS.

* TO ENSURE THAT THE EXAMPLES RUN PROPERLY, YOU MUST USE THE VERSIONS OF THE
SOFTWARE (SUCH AS THE JDK, BEA WEBLOGIC, ETC) THAT ARE SPECIFIED.

* This file describes how to get up and running with MOST of the source code
examples. Some examples may require additional packages installed.
Those source code examples have their own README files that explain what
you'll need. So you don't need to install unnecessary packages unless you'll
use them.

* If this is your first time using this code, then absolutely
DO NOT try to import the book's code into your favorite development
environment (JBuilder, VJ++, Visual Cafe, VisualAge for Java, makefiles,
ant, etc) until you've gotten the code to run as it was intended from the
code. Once you've gotten the source code to compile and run, THEN try
importing it into your favorite IDE, use ant, etc, because you will
now have this successful installation that you can use to debug any
problems you encounter when importing code into your development
environment.

--------------------------------------------------------------
Windows Installation Guide
--------------------------------------------------------------

The following instructions assume your Hard Disk is C:.

1) You must have an Internet connection to use these examples. This book's
source code connects via a loopback to your own machine, and if it can't,
then you won't be able to run any examples. To test whether or not you
can connect to yourself, open up an MS-DOS prompt
(via Start-run->command), and type:

ping localhost

You should see some responses. If you don't, you need to set up your
Internet connection first.

2) Open up an MS-DOS prompt (via Start->run->command) and copy the examples
to C:\book\EJB20\code. For example:

md C:\book\EJB20\code
unzip (using full directory structure explosion) the code into C:\book\EJB20\code

NOTE THAT YOU MUST USE C:\book\EJB20\code!!
DO NOT USE ANOTHER DRIVE LETTER OR FOLDER!!

3) Download a copy of BEA Weblogic Server 6.1 from http://www.bea.com.

NOTE THAT YOU MUST DOWNLOAD VERSION 6.1!!!!
DO NOT USE ANOTHER VERSION!!!

4) Next, install the downloaded weblogic server. During the installation,
you will be prompted with a few questions. Answer them as follows:

* Install the software into c:\bea.
* Set the system password to be 'administrator'.


5) Copy the weblogic configuration script to overwrite the one BEA gives you:

copy c:\book\EJB20\code\config.xml c:\bea\wlserver6.1\config\mydomain

6) Modify the c:\book\EJB20\code\env.bat file to suit your preferences. This will
configure your environment (PATH, CLASSPATH, etc).

7) Next, set up your environment. From your examples directory, type:

env.bat

NOTE THAT THIS ENVIRONMENT SCRIPT MUST BE RUN FROM A COMMAND PROMPT
AND NOT FROM WINDOWS EXPLORER.

NOTE THAT YOU MUST RE-RUN THIS BATCH FILE EVERY TIME YOU START A NEW
COMMAND PROMPT!

8) Try compiling and running an example. Go into one of the chapters that
has a bean example (such as C:\book\EJB20\code\StatelessSession\HelloWorld). Type:

compile.bat

Then go into c:\book\EJB20\code and run:

startWebLogic.bat

This will start BEA WebLogic. Next, open up an MS-DOS prompt
(via Start->run->command), and set your environment with 'env.bat'.
Then from the example directory you want to run (such as
C:\book\EJB20\code\StatelessSession\HelloWorld), type:

run_client.bat

--

Notes:

In general, I recommend you use Windows NT, 2000, or XP rather than
Windows 98 or ME. BEA does not really support WebLogic under 98 or ME.
You may run into problems since 98 or ME is not a stable development platform.

If you're using Windows 98 or ME, you may see an "out of environment space"
error. This is because Windows isn't allocating enough space for your
environment variables. You can increase your space via the following
procedure (recommended by Sun):

Close the DOS window (the error can corrupt its CLASSPATH variable)
Open a new MS-DOS window
Click on the MS-DOS icon at the top-left of the Window
Select the Properties option
Click on the "Memory" tab
Adjust the "Initial Environment" drop-down box from "Auto" to "2816"
Click on OK
Set your environment once more (run the env.bat file)


--

Notes:

* If you have problems, full instructions for setting up BEA WebLogic
can be found at http://e-docs.bea.com

--------------------------------------------------------------
How the examples are organized
--------------------------------------------------------------

Each example has the following directory structure:

README (Optional) Notes on the example
compile.bat Script to compile examples (Win32)
compile.sh Script to compile examples (UNIX)
run_client.bat Script to run test client (Win32)
run_client.sh Script to run test client (UNIX)
\src All example source code is here
\deployment Deployment descriptors and manifest files for beans
\classes Output directory where classes are placed
\lib Output directory where EJB-JAR is placed

When you compile an example, the following happens:

1) The source code in \src is compiled into class files and placed in \classes
2) The deployment descriptors are copied into the \classes folder.
3) An Ejb-Jar file is created, which contains the generated classes and the
deployment descriptors. The Ejb-Jar is placed in \lib.
4) The Ejb-Jar is copied into the Weblogic folder. When Weblogic starts up,
it will generate any necessary helper code.

--------------------------------------------------------------
Other Notes
--------------------------------------------------------------

* A cloudscape database (an RDBMS written in Java that's bundled with
WebLogic) has been preconfigured and is ready to go. The cloudscape
database is in the ejbdatabase directory within the examples directory
(e.g. C:\book\EJB20\code\ejbdatabase).

* TIP: If you're using Windows NT, open up a DOS prompt, click on the upper
left hand corner icon, choose "Properties...", click the Layout tab,
then set the Screen Buffer Size height to 2500, and the Window Size
height to 40. This will let you easily debug BEA WebLogic's output.

* Although the source code in this book should be relatively portable across
EJB servers, the beans will only work unmodified within BEA WebLogic due to
compilation script differences, spec ambiguities, and proprietary deployment
descriptors. If you wish to port this code to another server, we'd be happy
to host the code on TheServerSide.com.

* If you want to play with the cloudscape database, I've included a
"cloudscape" script that will start the cloudscape database visual GUI.
When the GUI opens, choose file->Open..., and choose the "ejbdatabase"
directory (should be in the directory you installed the source code).

* Cloudscape does not support transaction isolation levels other than
serializable, and BEA WebLogic spits errors out when using it. I have
provided a workaround by only using the serializable isolation level in
the bean examples.


--------------------------------------------------------------
Using a different database
--------------------------------------------------------------

IF THIS IS YOUR FIRST TIME USING THIS CODE THEN PLEASE DO NOT TRY TO USE
ANOTHER DATABASE - FIRST GET IT RUNNING WITH CLOUDSCAPE.

If afterwards you want to port this code to a different database, be sure that BEA
WebLogic supports your database by checking the BEA Web site (http://www.bea.com).
If you are using another application server, check your product documentation
for supported databases.

Then you can tune and run the following files:

C:\book\EJB20\code\EJB.sql
C:\book\EJB20\code\create_database.bat

--------------------------------------------------------------
Legal Stuff
--------------------------------------------------------------

This document and all other data within this archive is (c) 2001 by
The Middleware Company and is published by John Wiley & Sons, Inc.