Documentation Archive Developer
Search

WebObjects Release 3.5

Changes from Release 3.0 and 3.1
11/18/97

If you've used WebObjects 3.0 or 3.1, this document tells you what's new in WebObjects Release 3.5. The differences between Release 3.5 and 3.1 fall into these major areas:

This document only summarizes the changes. For more complete details, see the rest of the WebObjects documentation set (available online at http://devworld.apple.com/techinfo/techdocs/enterprise/WebObjects).

Release 3.5 is backwards-compatible with Release 3.0, meaning that you should be able to run your existing WebObjects 3.0 (and 3.1) applications without having to change source code. However, the way you use the tools has changed. In particular, the way that WebObjects application projects are organized has changed. You'll probably want to convert your projects as described later in Converting Projects.

Improved Development Experience

To improve the development experience, the following changes have been made:

Major changes to the tools are summarized here. For more information on how to use them, see the book Getting Started With WebObjects or the online book WebObjects Development: Tools and Techniques, which is available on the Apple website.

Direct to Web

Direct to Web is a new feature in WebObjects 3.5 that helps you quickly build database applications. To use Direct to Web, create a new WebObjectsApplication project in Project Builder and choose Direct to Web as the type of assistance. All you need to do is point Direct to Web at an EOModeler model file, and your application is ready to run. Launch that application, and you'll be presented with a login panel in your web browser. If you click the "Login with Web Assistant" button, you can not only view the pages that Direct to Web created for you, you can customize them using the Web Assistant as well. (Just click the Customize button, which is at the top of every page.)

For more information on using Direct to Web, see the documentation on the Apple website.

WebObjects Builder Changes

In Releases 3.0 and 3.1, WebObjects Builder was the central tool for WebObjects development; however, many preferred to use Component Editor. In Release 3.5, WebObjects Builder has been redesigned and rewritten so that it has become a much more useful tool for all WebObjects developers -- from the HTML and WOF novice to the expert.

NOTE: Palettes created in WebObjects 3.1 or earlier are incompatible with WebObjects Builder 3.5 because the underlying mechanism that WebObjects builder uses to store the HTML and bindings has changed.

The major changes to WebObjects Builder are:

Project Builder Changes

WebObjects Release 3.5 replaces the OpenStep 4.2 version of Project Builder with a Project Builder that has been enhanced to improve the WebObjects development experience. This new Project Builder is more tightly integrated with WebObjects Builder.

NOTE: In Release 3.0 and 3.1, you needed to load a bundle called WebObjectsSupport.bundle into Project Builder. This bundle is no longer necessary. When you uninstall WebObjects, WebObjectsSupport.bundle is removed from your system, and it is not added back by the WebObjects 3.5 installation. When you open Project Builder, you'll receive an error message to this effect. Go to the Bundles view in the Preferences panel and remove WebObjectsSupport.bundle.

In addition to tighter integration with WebObjects Builder, Project Builder has these other improvements:

Changes to Launching Applications

In WebObjects 3.0 and 3.1, launching an application was a two step process. First, you had to type a command line to launch the application itself. Then, you had to go to the web browser and type a URL.

WebObjects 3.5 has made launching an application much simpler:

Launching Applications in Symbolically Linked Directories

As stated previously, you can now launch most applications without specifying arguments. However, if the application is symbolically linked into the document root, instead of physically under the document root, you must supply an argument so that the application name can be determined correctly. Symbolic links resolve to a path that doesn't appear to be under the document root. Your application may appear to operate normally, but images won't load because they won't be found.

For example, all example applications on Solaris and HP-UX have this problem because the examples directory is a symbolic link to /NextLibrary/WODocumentRoot. To launch the DodgeDemo example on Solaris or HP-UX, you must specify the application name, just like you did in WebObjects 3.0: 

% cd /NextLibrary/WebServer/htdocs/WebObjects/Examples/ObjectiveC/DodgeDemo/DodgeDemo.woa
% DodgeDemo Examples/ObjectiveC/DodgeDemo

Note that you only have to give the path to the project directory, not the path to the .woa directory inside of the project directory. For the reason behind this, see "The Debugging Shortcut."

Converting Projects

Because of the changes made to Project Builder and WebObjects Builder, you need to convert existing projects to the 3.5 style of project. Project Builder does much of the conversion for you.

NOTE: Before you begin, you probably want to remove the .woa extension from the project directory and back up that directory.

Converting Existing 3.0 Projects to 3.5 Projects

After you install WebObjects 3.5, when you open an existing project in Project Builder, Project Builder automatically converts it to a 3.5 project for you. The conversion utility looks at the extension of each file in the project and moves the file to a new suitcase if necessary. If a file extension is not recognized, you'll be prompted to manually assign the file with that extension to the appropriate suitcase.

Here's a summary of what the conversion does:

WOProject.plist
WOProject.plist is obsolete, so it is deleted.

Components (.wo extension)
All .wo components are moved from the Interfaces suitcase to the WebComponents suitcase. It was common to have components that your application needs in the project directory but not add them to the project itself because doing so was unnecessary. In WebObjects 3.5, it is necessary for all components to be part of the project so that they will be copied into the .woa directory during project builds. For this reason, the conversion utility adds to the WebComponents suitcase all components that physically reside in the project directory but are not part of the project itself.

Java files (.java extension)
If any component has a .java file in it, it is moved out of the .wo directory to the .wo's parent directory and is added to the Classes suitcase of the project (or subproject if the .wo is in a subproject).

NOTE: Because the physical location of the .java file changed, your revision control system will most likely be affected.

Java subprojects
If your project has Java files, you'll be asked if you want the ClientSideJava and CommonJava subprojects in your project. If you respond with Yes, you'll be able to add all client-side Java classes to the ClientSideJava subproject and all classes intended for both the client and the server to the CommonJava subproject.

Resource files
The Other Resources suitcase is replaced with two suitcases: WebServer Resources and Resources. Images with known extensions are moved into the WebServer Resources suitcase. All other resource files are placed in the Resources suitcase.

Makefile.preamble
Several new make variables have been added. These new variables are appended to your existing Makefile.preamble with the default values assigned.

Subprojects
Subprojects are recursively converted using the same conversions described above.

Converting WebScript-Only Projects to 3.5

The conversion described in the previous section only takes place for directories that contain a PB.project file. In WebObjects 3.0 and 3.1, applications written entirely in WebScript did not require the use of Project Builder, and so they do not have a PB.project file. In this case, you should create a new project in Project Builder of type WebObjectsApplication and add files to the project manually. Use the list above as a guide.

Improved Deployment

To improve deployment, the following changes were made in WebObjects 3.5:

To learn more about deployment features, see the online book Serving WebObjects.

Installing a WebObjects Application

The directory NeXT_ROOT/NextLibrary/WOApps was introduced in WebObjects 3.0 as a secure place to store your WebObjects applications so that scripts weren't accessible through the document root. Installing an application in the WOApps directory was a cumbersome process; you had to place the entire application directory in WOApps and then you had to make a "sparse" copy of the directory in the web server's document root so that the web server would be able to find image files and other web server resources.

In WebObjects 3.5, this split install process is automated in Project Builder. To install a WebObjects application (including entirely scripted applications):

  1. If your project contains web server resources, go to the Makefile.preamble file under Supporting Files. Uncomment the line that defines this macro:

    INSTALLDIR_WEBSERVER

  2. Open the Project Build panel.

  3. Click the checkmark button to open the Build Options panel.

  4. Choose install as the build target.

  5. Click the Build button.

Project Builder builds your application project and then installs it, placing the appropriate directories in NeXT_ROOT/NextLibrary/WOApps and in the document root. (For more details, read the next section.)

To get the proper format and placement of the .woa directory, you should build even entirely scripted applications at least once. Scripted applications contain a file with a main function identical to the main in WODefaultApp. For this reason in WebObjects 3.5, scripted applications often have their own executable and don't need to rely on WODefaultApp.

Resource Management Changes

A WebObjects application now contains standard directories to store application resources. A deployed WebObjects application has the following directories: 

NeXT_ROOT/NextLibrary/WOApps/MyApp.woa/
	MyApp[.exe]
	Resources/
	WebServerResources/

<DocRoot>/WebObjects/MyApp.woa/
	WebServerResources/

The Resources directory contains the component directories, the application and session script files (if any), and any other resource files that an application might need access to (for example, plists or model files). The WebServerResources directory contains resources that both the application and the HTTP server might need access to, such as image files that should be displayed in the browser. (In Project Builder, you place all web server resources in the WebServer Resources suitcase, and Project Builder places them in the WebServerResources directory during a build.)

Shared Components and Resources

In WebObjects 3.0, to share a component or a resource file between applications, you had to copy that file into each application where you wanted to use it.

To improve sharing of components and resources, WebObjects 3.5 introduces the WebObjects Framework project type. WebObjects Framework builds a framework in which you can store components (or any other type of resource) to be shared across applications.

A WebObjects framework typically has the following directories: 

NeXTROOT/NextLibrary/Frameworks/MyFramework.framework/
	Resources/
	WebServerResources/

<DocRoot>/WebObjects/Frameworks/MyFramework.framework/
	WebServerResources/

As with WebObjects applications, the Resources directory contains the component directories and any other resource files that the framework needs to access. The WebServerResources directory contains resources that both the framework and the HTTP server might need access to, such as image files that should be displayed in the browser.

The Debugging Shortcut

When you're in development mode, you typically do not have an application installed in NeXT_ROOT/NextLibrary/WOApps. Instead you have a project directory under the document root, and the built .woa directory is inside that project directory. As a convenience for debugging, WebObjects looks one level up from the .woa directory to see if the directory is inside of a project directory. If it is, the components and resources from the project directory are used instead of the resources inside the Resources and WebServerResources directories of the .woa directory. This way, you can edit scripts or replace images and other resource files in the project and not have to rebuild the application to see the changes.

Image File Location

In WebObjects 3.0, when you wanted a component to have access to an image, you placed the image file inside of the component directory. In WebObjects 3.5, this practice is supported for backwards compatibility, but its use is deprecated. Instead, you should place image files in the WebServer Resources suitcase in Project Builder.

Two new attributes have been added to certain dynamic elements (for example, WOImage and WOActiveImage) to support this new location for image files:

filename
The image's file name including its extension. In reality, this is the path to the image relative to the application's WebServerResources directory.

framework
The framework attribute supports shared images stored in a framework. If the image is in a framework, you set the framework attribute to that framework's name (minus the .framework extension).

You can also place components in a framework and have them access image files stored in the application. To do this, you set the WOImage's framework attribute to "app".

You only use this attribute if the component and the image are in two separate locations. For example, if both the component and the image are in the same framework, you don't need this attribute. However, if the component is in framework A and the image is in framework B, you would need this attribute (set as framework = "B").

For more information, see the descriptions of WOImage and WOActiveImage in the Dynamic Elements Reference.

Accessing Resources Programmatically

You used to access resources using methods in WOApplication and WOComponent. These methods are still supported, but their use is discouraged. Instead, you retrieve resources using the new WOResourceManager class. For more information, see the WOResourceManager class specification in the WebObjects Reference.

The Monitor Application

The Monitor application, which is used to deploy WebObjects applications and monitor their performance, was distributed as an example in WebObjects 3.0 and 3.1. It is now a fully supported application. This application makes it easy to maintain the WebObjects.conf file, particularly if you are load-balancing applications.

The example version of Monitor came with a special subclass of WOApplication that you needed to use in all WebObjects applications you wanted to monitor. In Release 3.5, all of the API in Monitor's subclass of WOApplication has been added to WOApplication, so the recompile is no longer necessary. However, the 3.5 Monitor API is incompatible with the previous version. If you used the previous version of Monitor, you need to recompile all of your applications to use the 3.5 version of WOApplication.

For more information on using Monitor to deploy applications, see the online book Serving WebObjects.

Automatic Application Shutdown

In WebObjects 3.5, applications can automatically shut themselves down. These new methods have been added to the WOApplication class:

terminateAfterTimeInterval:
The application shuts down after the specific time interval (in seconds) has elapsed. All currently active sessions are abruptly terminated.
setMinimumActiveSessionsCount:
Sets the minimum number of active sessions. If the number of active sessions falls below this minimum, the application may terminate.
refuseNewSessions:
Sets whether the application should refuse any requests to create new sessions. If the application refuses to create new sessions and the active session count falls below the minimum, the application shuts itself down. In this way, you can gracefully shut the application down without affecting any of your users (or affecting the smallest possible number of users).

The Monitor application also contains UI that you can use to set the application to shut itself down either abruptly or by refusing new sessions. You can also schedule the application to shut itself down daily, weekly, or after a given number of hours.

In addition, Monitor contains an Autorecover button for each application instance. If this button is enabled, Monitor automatically restarts the application instance after it shuts down. Using a combination of refuseNewSessions: and Autorecover, sets of application instances can periodically recycle themselves, thereby maintaining high performance even for applications with memory leaks.

Scalability Testing

WebObjects 3.0 and 3.1 included a recording and playback example that could be used to perform scalability testing. In WebObjects 3.5, recording and playback scalability testing has become a supported feature. The recording adaptor is installed as NextLibrary/WOAdaptors/CGI-Recording. The playback tool is installed in NextLibrary/Executables/WOPlayback. For more information on how to use these tools, see the online book Serving WebObjects.

Deployment Statistics

In WebObjects 3.5, all applications keep statistics about themselves, such as the number of active sessions, the total number of sessions created, the startup time, the number of transactions processed, and so on. You can access these statistics in a couple of different ways:

NOTE: If you have overridden createSession in any of your WebObjects applications, those applications will not have the WOStatistics or application shutdown features properly implemented. You'll need to change your implementation of createSession. For more information, see the WebObjects Release Notes available through NeXTanswers #2455.

Improved Java Support

In WebObjects 3.5, Java support improved in these ways:

Changes to Client-Side Java Components

WebObjects 3.5 supports Java archive (.jar) files through modifications to projects and to the WOApplet dynamic element. As stated previously, all WebObjects projects can include the subprojects ClientSideJava and CommonJava for client and server-side Java classes. When you build a project that has these subprojects, Project Builder creates a .jar file suitable for downloading onto the client. In addition, WOApplet has been modified to support .jar files. It contains these new attributes:

archive
Use this attribute for archive files that you have generated outside of a WebObjects application or framework. The value for this attribute is appended to the archiveNames attribute value.
archiveNames
Use this attribute for archive files that are built as part of a WebObjects application or framework project.
agcArchive
The archive file containing the AppletGroupController class (similar to the archive attribute).
agcArchiveNames
Similar to archiveNames, but the archive contains the AppletGroupController class.

If you want to use these attributes, you should be aware of the following limitations:

Because of these limitations, the following is the recommended way to use .jar files with client-side components:

  1. Create one .jar file, X.jar, that contains:

    • Your Java client-side classes
    • The next.wo.client package
    • Any third party packages you are using

  2. Include the binding archive="X.jar" in all the WOApplets on the page.

  3. Include the binding agcArchive="X.jar" in one of the WOApplets on the page.

This ensures that all the classes needed by both your applets and the AppletGroupController will be found in the .jar file. Incidentally, this is also how you will get maximum performance out of .jar files.

The prepackaged client-side component classes that were distributed with WebObjects 3.0 are now available as a .jar file named WOExtensions.jar. This .jar file is in the WOExtensions framework, which is described below.

Other Major Changes

In addition to the improvements to development tools, deployment, and Java support, the following changes have been made in WebObjects 3.5.

WOExtensions Framework

A new framework of dynamic elements and shared components, the WOExtensions framework, is distributed with WebObjects 3.5. This framework contains the client-side components distributed with WebObjects, the WOStats component described previously, plus other dynamic elements and components that are ready to use in your application. You can freely access all of these through palettes in WebObjects Builder. For more information, see the WOExtensions Reference.

Enterprise Objects Framework Changes

An updated version of Enterprise Objects Framework is distributed with WebObjects 3.5 on all platforms. Enterprise Objects Framework contains these new features:

WebObjects Framework Changes

In addition to the new classes WOResourceManager and WOStatisticsStore mentioned previously, the WebObjects framework in Release 3.5 contains these changes:

New Documentation

All of the WebObjects documentation has been updated for 3.5. Most of the documentation is installed on your system when you install WebObjects. In particular, look for these noteworthy changes:

As stated previously, most 3.5 documentation is available on your system. However, the following pieces of documentation are currently being written. When they are completed, they will be made available through the Apple website. (You can click the "Updated Documentation at Apple" link in the left frame of the WebObjects Home Page to see if they are available.)