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.
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 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.
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:
WebObjects Builder now only edits components, not the entire project. You use Project Builder to perform project management tasks, such as creating new projects and adding resource files.
You use Project Builder to edit all source code files, including component script files. You use WebObjects Builder to create the component's interface (HTML) and to bind it to the variables and methods in the code. You can still use WebObjects Builder to add variables and methods to a component's source code, but when you want to implement a method, you now do so in Project Builder.
To bind an element, drag from the variable or method in the object browser to the element in the HTML view. This opens the inspector, from which you select the attribute that you want to bind to. (This method of binding is similar to making connections in Interface Builder.) You no longer double-click in the object browser to make bindings.
The icon path in the inspector has been improved. There is now only one icon per element. You choose between the static or dynamic inspector using a pop-up list. You can also use the inspector to convert a dynamic element to its static counterpart or vice versa.
The Database Wizard has moved from WebObjects Builder to Project Builder. When you create a new WebObjectsApplication project or a new component, you have the option of using the wizard.
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:
In WebObjects 3.0 and 3.1, WebObjects application project directories had a .woa extension. No distinction was made between the project directory and the end-result WebObjects application directory. When you built a compiled WebObjects application in Project Builder, it put the executable file directly into the project directory.
In WebObjects 3.5, there is a difference between the project directory and the application directory. You create a project in Project Builder and name it ApplicationName with no extension. When you build the project, the result is a directory named ApplicationName.woa containing the application executable and all necessary resources. (This model is similar to how you create OpenStep applications.)
You can see this change by looking at the WebObjects examples distributed with Release 3.5. Look in <DocRoot>/WebObjects/Examples/WebScript. (WebObjects example applications are now divided by language.) Each example is in a directory that has no extension (HelloWorld). If you look inside the directory, you see HelloWorld.woa, which contains the application executable.
For more information on changes to the .woa directory, see the section "Improved Deployment Experience" in this document.
When you create a new WebObjects project or a new component inside of a WebObjects project, a wizard launches. This wizard makes it easy for you to specify the programming language, and if you're writing an application with database access, it launches the Database Wizard or Direct to Web to help you. (Direct to Web is a new feature in 3.5 and is described earlier in this document.)
WebObjectsApplication projects contain these new "suitcases:"
You can now navigate inside component directories and edit individual component files in Project Builder. Component files are now indexed, and project-wide search and replace operates on component files.
For Java components, the .java file now lives outside of the component directory. When you create a component, you are prompted to choose the source code language (Java, Objective-C, or WebScript). If you choose Java, the .java file is added to the Classes suitcase. WebScript files still reside in the component directory.
Project Builder contains these new project types:
Each WebObjects project comes with two subprojects named ClientSideJava and CommonJava. Use ClientSideJava to create client-side components. Use CommonJava to create Java classes for use both on the server and the client. These subprojects have appropriate settings for certain variables in Makefile.preamble so that all client-side Java classes end up under the document root and all common (both server and client) Java classes end up in both the document root and in the application's directory.
When you create a WebObjects project, the ClientSideJava and CommonJava subprojects are created and placed in the project directory, but they are not added to the project. If you want to use them, add them to the Subprojects suitcase of your project.
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:
For example, to launch the DodgeDemo example on Mach in WebObjects 3.1, you had to type these commands:
% cd /NextLibrary/WebServer/htdocs/WebObjects/Examples/DodgeDemo.woa % DodgeDemo -d /NextLibrary/WebServer/htdocs Examples/DodgeDemo
In 3.5, you can shorten the command to this:
% cd /NextLibrary/WebServer/htdocs/WebObjects/Examples/ObjectiveC/DodgeDemo/DodgeDemo.woa % DodgeDemo
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."
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.
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:
NOTE: Because the physical location of the .java file changed, your revision control system will most likely be affected.
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.
To improve deployment, the following changes were made in WebObjects 3.5:
To learn more about deployment features, see the online book Serving WebObjects.
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):
INSTALLDIR_WEBSERVER
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.
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.)
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.
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.
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:
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.
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, 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.
In WebObjects 3.5, applications can automatically shut themselves down. These new methods have been added to the WOApplication class:
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.
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.
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:
WOStats is a new component shared among all WebObjects applications. It displays a table of application statistics. You access WOStats by typing in its URL:
http://localhost/cgi-bin/WebObjects/MyApp.woa/-/WOStats
WOStatisticsStore is a new class in the WebObjects framework. It keeps track of all of the statistics you see on the WOStats page. You can use WOStatisticsStore if you want access to application statistics programmatically.
In particular, you can use WOStatisticsStore to archive your application's statistics in Common Log File Format (CLFF). To do so, send the message setLogFile:rotationFrequencyInDays: to the WOStatisticsStore object. When you do so, at the end of each request-response loop, the response component's descriptionForResponse:inContext: method is invoked. By default, this method just records the name of the component, but you can override it if you want to provide more information. For example, you might want to record the values of component variables as well as the component name.
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.
In WebObjects 3.5, Java support improved in these ways:
id myVar = [MyJavaClass new];
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:
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:
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.
In addition to the improvements to development tools, deployment, and Java support, the following changes have been made in WebObjects 3.5.
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.
An updated version of Enterprise Objects Framework is distributed with WebObjects 3.5 on all platforms. Enterprise Objects Framework contains these new features:
In addition to the new classes WOResourceManager and WOStatisticsStore mentioned previously, the WebObjects framework in Release 3.5 contains these changes:
NSString *myString;
- (MyEntity *)returnAnEntityMethodWithArgument:(NSNumber *)aNumber { ... }
The purpose of this feature is to allow WebObjects Builder to make more intelligent assumptions when you bind variables and methods to a component. WebScript does not perform type checking; it just passes the information along to WebObjects Builder.
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.)