---

Converting Projects from WebObjects 3.5 to 4.0

1. Make a backup copy of your application, and save that backup copy somewhere other than in the base directory.

2. Convert your project's makefiles as described in the document $NEXT_ROOT /Developer/Makefiles/Conversion/DirectoryLayout/ConvertMakefilesReadMe.rtf.

   ( $NEXT_ROOT is the root installation directory specified when WebObjects was installed.) The project files must change to point to new locations for the build tools. ConvertMakefilesReadMe.rtf tells you how to make those changes.

3. If your project contains Java code files, convert them as described in Converting Java Code From WebObjects 3.5 .

   The Java APIs changed considerably between WebObjects 3.5 and 4. If you've written Java code, you must convert it before you can compile.

4. Open your project in Project Builder, and click "Upgrade Now" when prompted.

   Among other things, upgrading your project in this fashion will:

   - Upgrade your PB.project file to the latest version.

   - Upgrade your makefiles to the latest versions.
   - Convert your WebObject project suitcases to the new format.
   - Convert your project so that it conforms to the WebObjects 4 localization scheme. As a result of this, script (.wos) and .api files are moved outside of their component (.wo) directories. Script files now appear in the Classes suitcase.

5. Build. If errors occur during the build, fix them and re-build the project.

   The WebObjects Framework contains many optimizations that should greatly improve your application's performance. However, you may find your code relied on some part of the request-response loop or template parsing code that is no longer always performed.

6. Run the project. If your application doesn't run as expected, see the following sections:

   - Troubleshooting WebObjects 4 Template Parsing

   - Troubleshooting WebObjects 4 Request Handling

   - WebScript Changes

   Also check the What's New in WebObjects document for a list of differences between the current release and the previous one.

7. At this stage, if you want, you can remove all usage of deprecated API. WebObjects has been rewritten to be thread-safe, which required deprecating some of the existing APIs. You can still use deprecated API as long as you do not enable multithreading in your application. You'll receive warnings about deprecated API at run-time. For a complete list of what's deprecated, see the "Deprecated API" file that's included as part of each framework's reference documentation.

8. Make the following changes as appropriate for your system:

   - Convert dynamic elements to use escapeHTML and displayString (WOBrowser, WOPopUpButton, WOCheckBoxList, WONestedList).

   - Replace EOFetchSpecification hints with the appropriate new methods (see the EOFetchSpecification class reference).