Documentation Archive Developer
Search
WebObjects 5 Release Notes
PATH Documentation > WebObjects

WebObjects 5 Release Notes

Last Updated May 1, 2001

This document lists those problems known to exist in WebObjects 5. For late breaking, up to date news on the web, please refer to the WebObjects documentation at http://developer.apple.com/techpubs/webobjects and the Technical Notes available at http://developer.apple.com/technotes/index.html.



Installing WebObjects on Mac OS X

There is a bug in the installer where the installation fails on Mac OS X if you're not logged in to the root account. You must be logged in to the root account in order to install WebObjects. It's not sufficient to authenticate yourself as the root user in the installer itself. Nor is it sufficient to be logged in as a user with administrator privileges. To work around this bug, log in to the root account (the user name is "root") before installing WebObjects.

You may need to enable the root password first. To do this, navigate to the Utilities subfolder within the Applications folder in the Mac OS X Finder and double click the NetInfo Manager application. Select the Domain > Security > Authenticate menu item and authenticate yourself as a administrator. Select the Domain > Security > Enable Root User.

Alternatively, from the command line, execute:
sudo passwd root
You need to provide the password of an account with administrator privileges and a password for the root account.

After enabling the root account, log out and log in as the root user.



Using JDBC With WebObjects 5

The best source of driver information is Sun's website: http://industry.java.sun.com/products/jdbc/drivers/

Only JDBC 2.0 compatible drivers work with the WebObjects 5 runtime regardless of platform. The database vendor typically provides the JDBC driver in the form of a jar or zip file.

The JDBC driver must be installed in a place where the Java VM can find it. The simplest procedure is to add the JDBC driver jar (or zip) file to the Java VM's "extensions" directory. On Mac OS X, this directory is always /Library/Java/Home/lib/ext/. On Windows 2000, this directory would be something like C:\jdk1.3\jre\lib\ext\ but the exact details depend on where you installed the JDK 1.3 on your machine.

If you prefer, you can instead add the JDBC driver to your CLASSPATH, either explicitly listing the jar file or exploding the jar into a directory that is on the CLASSPATH.

When doing development on Windows 2000, the situation is somewhat more complicated. The WebObjects 5 runtime uses a Java 2 VM and requires a JDK 1.3 compatible JDBC driver just like Mac OS X and other platforms. However, EOModeler uses the Java Bridge which supports only JDK 1.1 on Windows and therefore requires a JDK 1.1 compatible driver. Consequently, in order to do development and testing on Windows 2000, you will need two versions of a particular JDBC driver: one that is JDK 1.3 compatible for the WebObjects 5 runtime, and another that is JDK 1.1 compatible for use by EOModeler and the Java Bridge.

To use a JDBC 1.1 driver with EOModeler on Windows 2000, you should add it to the JavaConfig.plist. Let's call it "driver11.jar". If your WebObjects installation is not in C:/Apple, substitute the appropriate path below. We use the Unix notation of "/" for the directory separator.

  1. login as an administrator
  2. copy driver11.jar to C:/Apple/Library/Java/
  3. Edit the file C:/Apple/Library/Java/JavaConfig.plist
  4. Add $NEXT_ROOT/Library/Java/driver11.jar to the entry for the "DefaultClasspath". Items in the list should be separated by a semicolon ";". Use the term "$NEXT_ROOT" literaly, following the pattern of the other entries.
Note that on Mac OS X, the Java Bridge supports the Java 2 VM so the JDK 1.3 compatible driver is used for both EOModeler and the WebObjects 5 runtime. If Windows is used only as a deployment platform, then the JDK 1.1 compatible driver is not needed.

Installation

Reference2172805
ProblemInstalling an upgrade will fail unless certain processes have been killed.
DescriptionThe "Pasteboard Server" and "Window Server" applications, which are necessary for WebObjects to function on Windows 2000, need to be killed in order to enable InstallShield to upgrade a WebObjects installation.

These can be killed either by removing them from the Startup menu and rebooting or by selecting the executable in the TaskManager's Processes pane (where they are named pbs.exe and WindowServer.exe) and killing the processes explicitly.
Workaround    Kill the "Pasteboard Server" and "Window Server" apps by either of the methods described.
  
  
Reference2250013
ProblemIncomplete uninstalls cause subsequent uninstalls to fail
DescriptionIf the NT uninstaller application is aborted or fails during the uninstall process it will cause subsequent uninstalls to fail.
Workaround    If uninstallation is aborted or fails, follow the steps outlined in the Readme.txt file in the Uninstall/UninstallWO5.0 directory on your CD.
  
  
Reference2252905
ProblemUninstalling from an account other than Administrator can result in some items not being removed
DescriptionIf you happen to uninstall WebObjects or Yellow Box from an account that doesn't have Administrator privileges, some items--such as the Start Menu items--will not be removed.
Workaround    Uninstall from the Administrator account, or from the account with administrator privileges that was used to install the product.
  
  
Reference2425526
ProblemSystem paths longer than 255 characters can cause problems during installation on Windows.
DescriptionDuring installation to an NT machine with long system paths (greater than 255 characters) there may be some problems. The installer will be unable to include necessary additions to the PATH environment variable, which means that some of the post-install scripts will fail because they can't locate needed commands. It also means that installed applications and services won't work following the installation.
Workaround    When installing try choosing an install path that isn't very long. For example, the default "C:\Apple" is a good choice. If you have a number of items in your system path you might try moving those items to a user PATH environment variable. To do this, create a user environment variable called PATH, add the values from the system path environment variable to it, and include %PATH% in the value (for instance, "%PATH%;C:\MyStuff"). Do not, however, move any of the Windows system path settings to the user path variable.
  
  
Reference2619370
ProblemWebObjects applications launch with the incorrect Java VM on Solaris and HP-UX.
DescriptionOn Windows, Solaris, and HP-UX, the Java VM that is used is determined like this:
1. The CLSSPATH.TXT file inside the application wrapper appropriate for your platform contains a line starting with "JVM". If the path specified by this line is absolute, the JVM specified by the path is executed.
2. If the path specified by the "JVM" line is relative (for example, if it's simply "java") the operating system resolves the full path of the executable according to the PATH environment variable.

In some installations, the PATH environment variable contains paths to two or more different Java VMs. As a result, your application may launch with the incorrect VM. This is not a problem on Windows; the WebObjects installer on Windows sets the PATH environment variable correctly.
Workaround    Be sure that the path to the correct Java VM (JDK 1.2 or later) appears before paths to all other Java VMs. Alternatively, you can edit your application's CLSSPATH.TXT file to specify the full path to the correct JVM. Warning: Recompiling the project will overwrite this rule.
  
  
Reference2655315
ProblemInstalling a new JVM after installing WebObjects may interfere with WOServices' startup scripts.
DescriptionDuring the installation of WebObjects 5, the installer records the path to the '.../bin/' directory containing the JVM ("java") executable used to perform the license key verification. The full path to this directory is placed at the beginning of the PATH environment variable employed by the WOServices-generated startup scripts (which ensure that WebObjects services are automatically started at the machine's boot-time). This means that the JVM present during the install is likely to be the JVM that is used to launch WebObjects services. If this JVM is too old (that is, if it is from too old a version of the JRE or JDK) or somehow replaced or moved after the installation, that original path will still be placed in the startup scripts and WebObjects services may not start correctly at boot-time, even if scripts are generated.
Workaround    There are three workarounds for this:
(1) Use the '-altJVMPath' flag with the 'WOServices' executable (see 'WOServices -help'). A path specified with this flag (in the form 'WOServices enable -altJVMPath /opt/new/j2sdk1.3.0/bin') will be prepended to the PATH environment variable inside the generated startup script (note that the prepending of the path applies only to that single execution of 'WOServices'; that is, the path is not recorded in 'WOServices' permanently).

(2) Move the old JVM back to or new JVM into the location recorded at startup, thereby ensuring that the recorded path is actually valid.

(3) Manually edit occurrences of the PATH environment variable in 'WOServices_utils.sh' as befits your needs (note that the first method is the intended solution, as it is non-destructive).
  
  
Reference2677151
ProblemOn Windows, WebObjects needs to know when you change the web server after you install WebObjects.
DescriptionWebObjects maintains the information about the web server in two configuration files.
Workaround    To configure WebObjects to work with a new web server:
1. Copy the contents of the old web server's CGI-Bin directory to the new web server's CGI-Bin directory.
2. Copy the contents of the old web server's document root directory to the new web server's document root directory.
3. Modify the C:\Apple\Library\Frameworks\JavaWebObjects\Resources\WebServerConfig.plist file with a text editor. Change the line that sets the "DocumentRoot". This should be set to the full path of the document root. Change the line that sets the "WOAdaptorURL". This should be set to the path of the CGI-Bin directory relative to the web server's root directory (not the web server's document root).
4. Make the same changes to C:\Apple\Library\WebObjects\Configuration file.
  
  
Reference2680165
ProblemThe WebObjects 5 Solaris uninstall.sh script may fail to uninstall WebObjects fully.
DescriptionWebObjects 5's uninstaller, located at $NEXT_ROOT/Library/Executables/uninstall.sh, will most likely not uninstall WebObjects fully. It will, for instance, leave the $NEXT_ROOT directory (the main directory into which WebObjects was installed; also known as the WEBOBJECTS ROOT directory) in place. Additionally, it will not stop any running instances of wotaskd.
Workaround    Completing the uninstallation process is quite simple: first, use the '$NEXT_ROOT/Library/WebObjects/Executables/WOServices stop' command to kill a running wotaskd instance, if one exists. Then, execute the uninstall.sh script from any directory. Finally, remove the $NEXT_ROOT directory. Note that WebObjects only deletes the files that it installs -- if you add files anywhere inside the $NEXT_ROOT directory tree, the removal of those directories will fail (be careful not to name any of your files the same names as those included in a WebObjects installation).
  
  
Reference2682204
ProblemThe WebObjects 5 installer fails on Mac OS X if you're not logged in to the root account.
DescriptionContrary to what the installation guide says, the WebObjects 5 installer requires you to be logged in to the root account. It's not sufficient to authenticate yourself as the root user in the installer itself. Nor is it sufficient to be logged in as a user with administrator privileges.
Workaround    Log in to the root account before installing WebObjects. You may need to enable the root password first. To do this, navigate to the Utilities subfolder within the Applications folder in the Mac OS X Finder and double click the NetInfo Manager application. Select the Domain > Security > Authenticate menu item and authenticate yourself as a administrator. Select the Domain > Security > Enable Root User. Alternatively, from the command line, execute:
sudo passwd root
You need to provide the password of an account with administrator privileges and a password for the root account.

After enabling the root account, log out and log in as the root user.
  
  

WebObjects Framework

Reference2219521
ProblemMy DirectAction raises when I trigger it
DescriptionI added a DirectAction to my project and trying to access it from the browser causes a:
Oct 21 14:29:58 TestD2W2L2[2539] <WODirectActionRequestHandler>: NSInvalidArgumentException exception occurred while handling request:
_BRIDGEUnmappedInitMethodImp: the java class da does not implement any constructor that maps to the Objective C method initWithRequest:
Workaround    Your DirectAction has to implement a constructor which takes a WORequest as an argument:

public class MyDirectAction extends WODirectAction {
    public MyDirectAction(WORequest r) {
        super(r);
        ...
    }
}

this is the constructor used by WOF during request handling
  
  
Reference2260519
ProblemWOApplication.application().port() returns a nonsensical result
DescriptionIf your user defaults have WOPort=-1, then WOApplication.application().port() returns -1.
Workaround    Access the port number directly from the adaptor via:

WOApplication.application().adaptors().objectAtIndex(0).port();
  
  
Reference2269517
ProblemRapid turnaround doesn't seem to work for aggregates (Windows only).
DescriptionThe default NSProjectSearchPath '(../..)' doesn't work for aggregates because the .woa is built into the top level of the aggregate.
Workaround    Change the user default for your application to point either to the aggregate itself or to "..". For example:

defaults write MyApplication NSProjectSearchPath '("~/projects/MyAggregate")'

or
defaults write MyApplication NSProjectSearchPath '("..")'
  
  
Reference2273821
ProblemThe session size numbers on the WOStats page appear to be too large.
DescriptionThe session size numbers are only an indication of the actual size of the session. When an application has finished initializing, its memory size is noted. The session size that is reported is based on the memory increase since startup, and is divided by the current number of active sessions. The memory increase includes any cached data and/or data initialized after startup, skewing the size computation.
Workaround    None.
  
  
Reference2274039
ProblemIDs in Cookies are dropped at the front door of applications.
DescriptionWhen "IDs in Cookies" is turned on for a WebObjects application, and you enter that application through the default request handler, cookies with old IDs are ignored in the request. In the response, new cookies for new IDs are sent back, or, in the case when there wouldn't be any new ID needed (such as in a stateless application), cookies clearing out the old IDs are sent back. This ensures that a user gets a new session when reentering a site, even if his browser keeps old, non-expired cookies around. This behavior is non customizable.
Workaround    To force existing cookies (and the IDs they carry) to be accepted by the main page, use a complete url that includes the page name. For example:
/cgi-bin/WebObjects/MyApp.woa/1/wo/Main.wo
This way, your older IDs in cookies will be preserved.
  
  
Reference2276414
ProblemSessions are not dealloced with WOAditionalAdaptors
DescriptionIf you attempt to use the WOAdditionalAdaptors feature, sessions may not timeout.
Workaround    None.
  
  
Reference2277580
ProblemWOApplicationWillFinishLaunchingNotification has been relocated
DescriptionIf your application depends on receiving WOApplicationWillFinishLaunchingNotification, be aware that it now comes after app init, before the adaptors are registered.
WOApplicationDidFinishLaunchingNotification comes after the adaptors are registered, just prior to receiving requests.
Workaround    None.
  
  
Reference2279328
ProblemWOResourceManager may leak for dynamic resources if 'key' attribute is not used.
DescriptionIf you use WOImage like
MyImage : WOImage {
    data = someData;
    mimeType = "image/gif";
}

This can potentially leak as the data will be kept in memory under a random key. Some browsers don't ever load the resource. Playback clients will not load the resource either. In such cases, WOResourceManager will cache copies of it indefinitely.
Workaround    Use the 'key' attribute to cache the same image over and over and save memory. Or call 'flushDataCache' on WOResourceManager.
  
  
Reference2282001
ProblemThe current context and the current request aren't accessible from within a WOSession initializer
DescriptionWOSession's initializer doesn't set its context instance variable, so it isn't possible to access either the current context or the current request for use in your WOSession subclass initializer.
Workaround    There are two ways to work around this problem. The simplest is to implement awake() on your session. At this point, the context instance variable is set. Since awake() is invoked for every request, though, you'll have to protect your code so it is executed only once in awake() (if it is initialization code, it most likely needs to happen only once). A better solution, assuming you only need the request object, is to implement createSessionForRequest() in your subclass of WOApplication:

public WOSession createSessionForRequest(WORequest aRequest) {
    Session session = (Session)super.createSessionForRequest(aRequest);
    // put your custom initialization that needs the request object here.
    return session;
}
  
  
Reference2290990
ProblemStandard error and warning messages aren't localized.
DescriptionWhen running a WebObjects application, some standard error and warning messages--such as "You have backtracked too far"--can be sent directly to the user. These messages aren't localized and can confuse a non-English user.
Workaround    Provide your own implementation for the different handle...Error methods in WOApplication:

handlePageRestorationError for localizing the "backtracked too far" messages
handleSessionCreationError when the application is unable to create a new Session
handleSessionRestorationError when the WOApplication is unable to find the Session

Its always a good idea to implement the above methods, providing your own logic and user interface to handle exceptional conditions.
  
  
Reference2304924
ProblemWebObjects is not thread safe with component caching disabled
DescriptionWebObjects isn't thread safe when AllowsConcurrentHandling is set to true and CachingEnabled is set to false.
Workaround    When deploying WebObjects applications, be sure to set -WOCachingEnabled true.
  
  
Reference2332399
ProblemResources are not found on Microsoft Windows.
DescriptionOn file systems that are case-insensitive, resources may not be loaded if their names are spelled differently from the name returned by the file system. NSBundle and related classes use case-sensitive matching of resource and path names. This can result in a resource not being found in WebObjects 5, even though the file can be accessed directly from the file system where the case is irrelevant.
Workaround    When you specify a resource, be sure the name has the correct case.
  
  
Reference2343393
ProblemA WebObjects component, which worked in 4.0.1, reports an error with WebObjects 5.
DescriptionThe WebObjects 5 .wod format does not support attribute names containing hyphens unless they are enclosed in double-quotes. For example:
Foo: WOMetaRefresh {
    http-equiv = "goop";
}

should read
Foo: WOMetaRefresh {
    "http-equiv" = "goop";
}
Workaround    Add quotes to attributes containing hyphens.
  
  
Reference2364124
ProblemInner classes require special naming convention in the mapping coder
DescriptionSpecifying the name of an inner class in a mapping model (such as MappingHelper.RelatedLinks) produces a 'NOClassDef' exception.
Workaround    The Sun VM expects the inner classes to be specified with their internal names. In the above example, use MappingHelper$RelatedLinks instead
  
  
Reference2366474
ProblemWOXMLDecoder raises an exception decoding a class with an inner class.
DescriptionSuppose that a class Omicron has an inner class Iota. Both classes implement the WOXMLCoding interface (and implement a decoding constructor). Decoding an instance of Iota causes the following exception to raise:
com.webobjects.appserver.xml.WOXMLException [java.lang.reflect.InvocationTargetException]
Workaround    Change the scope of the nested class to public and static.
  
  
Reference2372492
ProblemCookie expire header date format change
DescriptionIn order to comply with RFC 2109 and the Netscape informal specification, the date format used with the cookie expire header has been changed to "%a, %d-%b-%Y, %H:%M:%S GMT". Previously %A was used rather than %a. %a formats weekdays as Mon, Tue, Wed, etc. rather than the full weekday name.
Workaround    None
  
  
Reference2374907
ProblemThe default error page doesn't appear after the application raises an exception.
DescriptionBy default, WebObjects displays a standard error page in the browser when an application error occurs. The default WebObjects error page is defined by the WOExceptionPage.wo component in the JavaWOExtensions.framework. If this exception page can't be displayed because of a problem with the component itself, WebObjects displays a rudimentary page with information related to the issue. This page doesn't contain any alert image or hyperlink. It simply displays text describing the error. One way this page can appear is if WebObjects encounters a uncaught exception while creating a Session object.
Workaround    not applicable
  
  
Reference2375462
ProblemDisplay group queryOperator string queries behave differently from how they behaved in WebObjects releases prior to 4.5.
DescriptionIn previous versions, when you performed a string query with the query operator set to =, the result matched 'caseInsensitiveLike value*' instead of '= value'. This behavior has been fixed for 4.5.
Workaround    Use the "starts with" string qualifier operator. See the stringQualifierOperators method in the WODisplayGroup class specification for more information.
  
  
Reference2378754
ProblemWOHyperlink documentation incorrectly indicates that the actionClass binding must be specified.
DescriptionThe actionClass binding only needs to be specified if the directActionName binding is specified.
Workaround    None needed.
  
  
Reference2393373
ProblemThe XML Framework reference doesn't specify the behavior to expect when you use the unmappedTagsKey attribute in a mapping model entity.
DescriptionIf your entity has the attribute unmappedTagsKey=myKey, any tags for which there is no specified mapping will be saved as key/value pairs in an NSMutableDictionary named myKey.
Workaround    None.
  
  
Reference2394732
ProblemThe WODirectActionHandler now allows direct-connect requests when the application is refusing new session.
DescriptionIn previous versions of WebObjects, if an application is refusing new sessions and a request with no session id comes in, a redirect is returned to the sender. In WebObjects 4.5, if an application is refusing new sessions and a request with no session id comes in through the adaptor, a redirect is returned to the sender. If the request is made using direct connect, it is processed normally.
Workaround    None needed.
  
  
Reference2396118
ProblemWOMessage string encoding constants are strings, not integers.
DescriptionIn Java, character encodings are represented by strings, which is different from how character encodings were represented in previous versions of WebObjects. To determine the string that represents a character encoding supported by the JDK 1.3, consult the table at http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html
Workaround    Specify the character encoding as a string.
  
  
Reference2399206
ProblemThe XML decoder cannot decode NSData that contains characters outside of the range of XML-allowed characters (those less than \u0020).
DescriptionThese characters will occur frequently when encoding or decoding NSData objects that represent images.
Workaround    None at this time. Avoid encoding or decoding images.
  
  
Reference2408143
ProblemWOMessage's setUserInfo method makes a copy of its dictionary argument.
DescriptionWOMessage's setUserInfo method unconditionally makes an immutable copy of the dictionary passed as an argument to the method. This can be a problem if changes made elsewhere to the dictionary's contents need to be reflected in the userInfo dictionary.
Workaround    If you need to pass in a mutable dictionary that can be changed by others down the chain, wrap the mutable dictionary in a read-only (immutable) dictionary and pass the immutable dictionary to setUserInfo. Be extremely careful doing this if your application is multi-threaded and the userinfo data may be accessed by more than one thread.
  
  
Reference2418073
ProblemApplications shouldn't listen on port 1085
DescriptionPort 1085 is reserved for the exclusive use of wotaskd. Any application that tries to listen on this port will fail.
Workaround    Choose another port (note that ports above 1024 are quite commonly used - see iana.org for info).
  
  
Reference2425444
ProblemWhen binding a date object to a WOTextField, you must also bind a formatter.
DescriptionIf you bind an NSTimestamp object to a WOTextField's value attribute but do not bind either a date format string to dateFormat or a formatter object to formatter, after submission the date object will be invalid. For example, entering '10/10/20' will store an NSTimestamp with a yearOfCommonEra: 1.
Workaround    Bind either the dateFormat or formatter attributes as well.
  
  
Reference2428376
ProblemFormatters can alter values associated with WOTextFields.
DescriptionThis problem appears when

1. you use a pattern that rounds the number, truncates times from date and time input, or performs any other lossy conversions and
2. the form's submit action redisplays the same component.

If the user enters a number that gets rounded by the formatter and submits the form, the rounded version appears in the text field. If the user submits the form again, the text field's value becomes the rounded version of the number.
Workaround    Change the formatter's pattern string so that it does not perform any lossy conversions (like rounding a number, truncating to only the month/day/year instead of full time, etc), use a custom formatter, or do not attach a formatter to the WOTextField.

Alternatively, if your WOTextField is connected to the property of an EOEnterpriseObject, you can override the set method for the property so it rounds the same way the formatter does. For example, if the property holds an integer and the NSNumberFormatter discards fractional information, the value held in the property matches the value displayed by the text field, and no loss of information occurs.
  
  
Reference2430661
ProblemXML Mappings needn't be unique for decoding, contrary to what the documentation says
DescriptionThe XML Framework reference documentation states that mappings must be unique for a given property when decoding. This isn't true: they don't have to be unique for decoding (although they must be unique for encoding). The RelatedLinks example illustrates one situation where you can take advantage of multiple tags mapped to a single property.
Workaround    Not applicable.
  
  
Reference2571405
ProblemThe WOXMLDecoder throws a WOXMLException when you try to decode an object with a key that contains spaces.
DescriptionThe previous version of the XML coder allows you to encode keys containing spaces, but throws when you try to decode these keys. (The current version of the XML coder also throws when you try to encode keys containing spaces.)
Workaround    Whenever you use the various encode or decode "for key" methods, make sure that the keys are valid XML names. Additionally, if you encode a NSDictionary with encodeObjectForKey, make sure the keys in the NSDictionary are valid XML names. Otherwise the encoding or decoding process may fail with a WOXMLException.
  
  
Reference2596955
ProblemWebObjects is not finding my projects.
DescriptionTo tell WebObjects where to look for your system's projects you must define the NSProjectSearchPath user default. Set this default to an array of paths where your projects may be found. (Relative paths are taken relative to the executable of your project.) The order of the entries in the array defines the order in which projects will be located. The array would look like: ("someDirectory", "someOtherDirectory", . . . )

The default NSProjectSearchPath was changed in this version of WebObjects from ("../..") to (".."). This default may prevent WebObjects from locating your project.

For example, if your application's executable resides in

c:\web\docroot\WebObjects\Projects\MyProject\MyProject.woa

then relative to the executable's directory, ".." is:

c:\web\docroot\WebObjects\Projects\MyProject\


With the previous default, ("../.."), WebObjects would instead look in

c:\web\docroot\WebObjects\Projects

and find extra things.
Workaround    You should set your NSProjectSearchPath to point to the directories where you keep your projects as you work on them. When your application is starting up, pay close attention to the log messages that indicate that a given project is found and will be used instead of the built product. Many problems can be solved by understanding how to interpret this output.
  
  
Reference2599994
ProblemWebObjects 5 does not provide utility classes to perform character set encoding conversion for strings or streams.
DescriptionJava already supports character set encoding conversions.
Workaround    To convert strings, use java.lang.String(byte[], String). To convert files, use the java.io.InputStreamReader and java.io.OutputStreamWriter classes, which support character set encoding. Additionally, if you want to convert to and from Macintosh encodings, you need to download the Internationalized version of the Java Runtime Environment, which includes the i18.jar internationalization package.
  
  
Reference2605569
ProblemWOApplication.setDebuggingEnabled has been removed from API.
DescriptionThis functionality is now handled by NSLog.
Workaround    See the NSLog documentation.
  
  
Reference2607502
ProblemSome dynamic elements are deprecated.
DescriptionWOQuicktime, WONestedList, WOCheckBoxList, and WORadioButtonList are deprecated components and are made available for compatibility only.
Workaround    The following alternatives exist for the deprecated elements.
WOQuicktime -> JavaWOSmil framework and its classes
WONestedList -> WOJExamples/WXNestedList
WORadioButtonList -> WOJExamples/WXRadioButtonList
WOCheckBoxList -> WOJExamples/WXCheckBoxList
  
  
Reference2608778
ProblemCc'ed mail recipients appear in the To field as well as the cc field in messages sent using WOMailDelivery.
DescriptionThe sun.net.smtp package does not support cc'ed mail. As a workaround, WOMailDelivery copies all addresses in the cc field to the addresses in the To field without removing them from the cc field. This way the mail reaches the addresses in the cc field (via the To field). At the same time, addresses originally in the cc field also appear in the To field. Only one email is actually sent to each of these addresses.
Workaround    None.
  
  
Reference2661559
ProblemProject Builder WO, ProjectBuilder on Windows, and Project Builder on Mac OS X do not provide an intuitive way to adding a global server resource (e.g. Localizable.strings) for localized WebObjects applications.
DescriptionFor localized WebObjects applications, developers usually provide a default global resource (e.g. flag.gif or Hello.wo). This resource is used when the language specified by the user's browser is not supported by the application. However, adding a global server resource (for example, Localizable.strings) is not intuitive in Project Builder WO, ProjectBuilder on Windows, and Project Builder on Mac OS X.
Workaround    Consider the Localizable.strings file as an example. For Project Builder WO (and ProjectBuilder on Windows), localize the file as per normal but do not remove the file from disk when prompted. On the UI, you will notice that it disappears as global server resource. Close the project. Edit the project's PB.project file using a text editor. Search for the "WOAPP_RESOURCES" key. Add "Localizable.strings" as part of the value, within the parentheses. Edit the Makefile. Search for the "GLOBAL_RESOURCES" key and append "Localizable.strings" to the value. Reopen the project.

For Project Builder on Mac OS X, if the project was imported from Project Builder WO (or ProjectBuilder on Windows), then the global resource is handled correctly and appears in the "Resources" area and is labeled as "Global". If the project was created from scratch, first create "Localizable.strings" and localize it to the languages you want. Subsequently create another new file with the same name " Localizable.strings" and drag it to the "Resources" area.
  
  
Reference2678075
ProblemIf you append a string to a response after you initialize the response's content to a NSData object, the content in the NSData object is forgotten.
DescriptionWebObjects allows you to build a response by first initializing the content using setContent(String) or setContent(NSData), and then appending content using appendContentString(String) and appendContentData(NSData). However, there is an asymmetry in the WOResponse implementation: If you initialize the content with an NSData object and then append a string, WebObjects forgets the content in the NSData object.
Workaround    Don't use setContent(NSData) if you plan to append a string to the response. Instead, set the content to an empty string and then append the NSData object. After than you can append as many strings and NSData objects as you want.
  
  

WOExtensions

Reference2369994
ProblemWOTable WebObjects Extension specification is missing the cellWidth and tableWidth bindings.
DescriptionThe documentation should have the following bindings:

tableWidth
The width of the table. This attribute is passed to the HTML TABLE tag.

cellWidth
The width of the cells in the table. This attribute is passed to each HTML TD tag in the table.
Workaround    None needed.
  
  
Reference2395684
ProblemJSValidatedField WOExtensions component fails to check the validity of fields if the user does not tab through them.
DescriptionThe Java Script code for JSValidatedField is only invoked when the user tabs through the field. If the user submits the form without tabbing through the fields, the fields will not be validated.
Workaround    None.
  
  
Reference2593451
ProblemPreviously, WOKeyValueConditional has lacked the negate binding.
DescriptionIn contrast to WOConditional, WOKeyValueConditional has lacked the negate binding in previous versions. The workaround has been to negate the value set in the condition binding.
Workaround    WOKeyValueConditional now has a negate binding. Components that currently use WOKeyValueConditional do not need to be modified to set the new binding. The default value of the negate binding is false, so the condition binding will not be negated.
  
  
Reference2635508
ProblemWOApplescript behaves incorrectly.
DescriptionThe WOAppleScript component is deprecated. You should not use this component.
Workaround    None.
  
  

Direct to Web

Reference2201189
ProblemDirectToWeb does not handle queries custom data types
DescriptionIf one of your attributes has a custom data types (i.e. not one of the built-in types such as NSNumber, NSDecimalNumber, NSDate, NSCalendateDate..) you can get an exception when DirectToWeb is trying to display it.
Workaround    Using the Web Assistant, navigate to the faulty query page in expert mode and hide the property that has a custom type.
  
  
Reference2274611
ProblemDirectToWeb raises on custom or non-existent keys
DescriptionEither due to a mistyped key in the Live Assistant or the removal or renaming of an attribute or relationship in EOModeler, an EOUnknownKey exception can be raised when you run a DirectToWeb application.
Workaround    Using the Live Assistant's expert mode, select the task/entity couple for which you're getting an exception and hide the key that is causing the problem.
  
  
Reference2424172
ProblemDirect to Web applications can hang.
DescriptionAn editing context in your application may be locked and not properly unlocked. Due to the details of how Direct to Web locks editing contexts, an editing context isn't unlocked when you create a new Direct to Web page without rendering it.

In WebObjects, the locking and unlocking of session.defaultEditingContext is performed transparently. However, if your application uses other editing contexts, you need to lock them yourself.

Direct to Web helps you manage the locking of such editing contexts:

- The edit and inspect pages lock the editing context when the setObject method is invoked.

- The edit-relationship page locks the editing context when the setObjectAndMasterRelationshipKey method is invoked.

- The inspect, edit, and edit-relationship pages lock the editing context of the object they manipulate when the awake method is invoked

- The inspect, edit and edit-relationship pages unlock the editing context of the object they manipulate when the sleep method is invoked.

Therefore the following code:
myPage=D2W.factory().inspectPageForEntityNamed("FOO",session());
myPage.setObject(myEO);
return myPage;

requires no extra lock/unlock statements on your part, even when myEO is not in session.defaultEditingContext.

However if you do not render the page right away but store it instead, the editing context remains locked unless you unlock it yourself.
Workaround    Unlock the editing context explicitly by calling sleep():

myPage=D2W.factory().inspectPageForEntityNamed("FOO",session());
myPage.setObject(myEO);
myPage.sleep();
thisOtherPage.setNextPage(myPage);
  
  
Reference2427535
ProblemThe Direct to Web Assistant in Netscape 4.7 on Windows throws up an alert panel when I click Update.
DescriptionThe alert message that appears is something like: "Socket is not a file descriptor". This problem only happens after resizing either the window or the browser frame which contains the small Assistant Applet (whose visible part is the 'Show Assistant' button).
Workaround    Try reloading the page. Avoid resizing the browser window after launching the assistant. If possible, use Microsoft Internet Explorer, appletviewer, or a different version of Netscape.
  
  
Reference2458195
ProblemRules from d2w.d2wmodel files are merged into the user.d2wmodel file when saving
DescriptionDirectToWeb applications merge all rules found in all d2w.d2wmodel files and the user.d2wmodel file. When settings are saved using the WebAssistant, rules of priority 100 are saved to the user.d2wmodel files. If a developer keeps rules with priority 100 in files other than the user.d2wmodel files, these rules will be merged into the user.d2wmodel file when a save is done from the web assistant.
Workaround    Don't create rules with priority of 100 in files other than the user.d2wmodel file. Assign a different priority to rules in d2w.d2wmodel files
  
  
Reference2465051
ProblemIf you edit the display of the WOLMasterDetailPage in the Web Assistant, it will not have any effect.
DescriptionThe master detail page is actually two tasks put together: select and edit. You need to edit these task pages separately to modify the master detail page.
Workaround    Use 'Expert Mode' to edit the configuration of the select and edit tasks for the selected entity to configure the attributes that you want displayed.
  
  
Reference2477438
ProblemShared entities do not appear in Direct to Web applications
DescriptionBy default, shared entities are hidden because they're usually not interesting to inspect and not editable. However, you can access them through relationship.
Workaround    If you really need to edit or show shared entities, use the Web Assistant to make them editable or read-only.
  
  
Reference2504035
ProblemIn Direct to Web, some properties in a tab panel unexpectedly appear above the tabs.
DescriptionUsing the Web Assistant, you can configure a Direct to Web page to use a TabPage layout. When you change this setting to use the TabPage layout, the Web Assistant automatically assigns a tab name to each property displayed on the page, EXCEPT for properties that you had inspected with the Web Assistant before you changed the page layout setting. When a property does not have a tab name associated with it, D2W displays the property above and outside of the tabs of the page.
Workaround    Set the tab name for all properties on pages using the TabPage layout.
  
  
Reference2507444
ProblemDirectToWeb does not find attributes in relationships that use inheritance
DescriptionConsider a model with an entity A that has a relationship to entity B. Also, entity B has a subclass called B1 which contains an attribute (att1) not present in entity B. Keypaths of the type a.b.att1 will not work correctly with the rule system.
Workaround    none, other than avoiding rules that contain the the keypath a.b.att1 when you have the above scenario
  
  
Reference2517806
ProblemDirect To Web's EditRelationship pages don't handle mandatory to-one relationships very well
DescriptionDirect To Web currently has only one way to edit relationships: a page called EditRelationship. This page assumes that all relationships objects can be deleted, which violates the sematics of mandatory to-one relationships.
Workaround    Generate the page template for the edit relationship page and remove the delete button so that the user can't delete mandatory relationships. Or chose a component that won't lead the user to the EditRelationship page when editing a mandatory to-one.
  
  
Reference2565612
ProblemNetscape 4.xx is slow to render an uncollapsed WORadioButtonMatrix component.
DescriptionFor example, in a DirectToWeb application, if one uses a D2WEditToOneRelationship and picks the "Radio" UI style and checks the "allow collapsing" option, it may take Netscape a long time to render the page after the user "clicks on the triangle" and uncollapses the WORadioButtonMatrix. The delay is due to the table rendering algorithm in Netscape 4.xx.
Workaround    Uncheck the "allow collapsing" option.
  
  
Reference2628707
ProblemJavaConverter doesn't convert 4.5 DirectToWeb apps completely correctly.
DescriptionAfter using JavaConverter on a 4.5 DirectToWeb app there are still problems compiling and running the application. Here are some suggested workarounds:
Workaround    

1. Make sure you regenerate the makefile as explained in the JavaConverter documentation.

2. JavaConverter doesn't bring over the files in the "SUPPORTING FILES", including the makefile preambles and postambles. All of the makefiles need to be added by hand to this folder.

3. If you are using the JDBC adaptor, the converter incorrectly adds the JavaJDBCEOAdaptor framework to your project. It should add the JavaJDBCAdaptor framework.

4. JavaConverter flags a JC_ERROR message on the invocation of pageWithName in the logout method for the MenuHeader class (if you still have that class in your project). Ignore this message. This use of pageWithName is legal.

5. Make sure your Application class has the following main function to intialize the WOF Stack:

public static void main(String argv[]) {
    WOApplication.main(argv, Application.class);
}

6. JavaConverter doesn't handle EOModel conversions, so make sure your model is pointing to the correct adaptor. In addition, you may have to convert the attribute type names. NSString should be changed to String. NSDate and NSCalendarDate should be changed to NSTimestamp. NSNumber should be changed to java.math.BigDecimal.

7. References of NSValidation.Exception should be changed to NSValidation.ValidationException.

8. If you have generated the Java stub for a DirectToWeb dynamic template, make sure your file has the following constructor:

public YOUR_CLASS_NAME(WOContext aContext) {
    super(aContext);
}

9. Pages you have frozen using DirectToWeb could contain variable definitions like

private EOEnterpriseObject itemForMovies;

change all itemFor... references from private to protected so that WebObjects can resolve these keys at runtime.
  
  
Reference2666929
ProblemChanging primary keys that are class properties causes an exception to be thrown. This was not a problem in previous releases.
DescriptionWhile it was technically possible to change primary keys that were class properties even after assigning their initial values, this actually caused major inconsistencies and resulted in substantial problems. Reassigning a primary key is now considered an error and causes WebObjects to throw an IllegalStateException.

Note that in general, primary keys should not be class properties at all. They should only be used internally by WebObjects. However, it is still possible to access them in a read-only fashion by making them class properties, and/or to let the user assign an initial value (which then must be left unchanged).
Workaround    Don't change primary key values. A better solution is not to expose them as
class properties at all. Note that by default, DirectToWeb and DirectToJava do not display primary keys even if they are class-properties.
  
  
Reference2684724
ProblemD2WDisplayLargeString won't allow me to scroll over the data.
DescriptionWhen WebObjects produces HTML for the D2WDisplayLargeString component it adds the "disabled" attribute to the TEXTAREA tag. This tag, unfortunately, does not behave in the same way for all browsers. Some of them will disable just the text area and let the user scroll through the information while others will disable the whole element and thus stop the user of seeing all the information if there is more text than will fit into the outlines of the box.
Workaround    Set the number of rows and columns of the D2WDisplayLargeString so that all the information for that attribute can be viewed without scrolling the text area box.
  
  

Java Client

Reference2281716
ProblemJava Client applets can use the wrong session on the application server
DescriptionWeb browsers don't usually start a new Java VM when a new applet is started. The Java Client applet stores some information about the session in static variables--these variables may be reused if a second Java Client applet is started in the same VM. If the original session has already timed out by the time you display the second applet, you'll get a "your session timed out" error message. Otherwise, the second applet will use the original applet's session on the server, instead of the current one.
Workaround    Run the client as an application, or restart the Web browser between uses of a Java Client applet.
  
  
Reference2370377
ProblemIt isn't documented that locking operations aren't supported in the client side of a Java Client application are no-ops.
DescriptionLocking is not implemented in com.apple.client.eocontrol.EOEditingContext and EODistributedObjectStore, but there is public API in those classes that makes it appear otherwise. The EODistributedObjectStore method isObjectLockedWithGlobalID always returns false because locking isn't supported in the client. Similarly, the EODistributedObjectStore method lockObjectWithGlobalID raises an exception. The client-side EOEditingContext locking methods (lockObjectWithGlobalID, lockObject, locksObjectBeforeFirstModification, setLocksObjectBeforeFirstModification, and isObjectLockedWithGlobalID) are also affected: lockObjectWithGlobalID and lockObject raise on first use; locksObjectBeforeFirstModification and setLocksObjectBeforeFirstModification trigger a raise if set to true and you modify an object; and isObjectLockedWithGlobalID always returns false.
Workaround    None.
  
  
Reference2397380
ProblemJava beans embedded in a Java Client application in 4.5 don't run out of a jar/zip file.
DescriptionThe Java Client framework cannot directly reference individual resources within a jar/zip file. Therefore Java Client cannot act as a container for a Java Beans inside jar/zip files.
Workaround    Unarchive Java beans into .class files (and other resources) and put them in the CLASSPATH.
  
  
Reference2688576
ProblemProjects containing Java Client interface files fail to compile correctly.
DescriptionWhen you save an interface file in a Java Client project, the Interface Builder palettes provided with WebObjects add additional information to them in the form of Java classes. If you rename an interface file in the file system, copy it with another name, or use Project Builder features to create platform or language variants, you need to open the new interface file in Interface Builder and explicitly save it to regenerate the Java Client-specific information.
Workaround    Open affected interface files in Interface Builder and save them explicitly.
  
  

Direct to Java Client

Reference2367086
ProblemJava Client windows do not become visible on Windows.
DescriptionThere appears to be a bug in earlier versions of the Windows AWT which results in windows not becoming visible. The Windows task bar actually shows the window.
Workaround    Right-click on the window's button in the task bar and use the context menu to maximize the window.
  
  
Reference2481832
ProblemReverting form windows in Direct to Java Client can leave windows unusable.
DescriptionThis problem occurs if
1. you create a form window for a main entity "A" which is owned by another entity "B" (entity "B" has a relationship to entity "A" which "owns destination")
2. you display a subform to allow the user to select/deselect the object from entity "A"
3. the user selects or deselects the object and subsequently reverts the change
Because entity "A" owns entity "B", the object of entity "B" is deleted when it is removed from the relationship to "A". As a result, there is no object left in the main display group to display any kind of data. Reverting the change (pressing the Revert button) restores the objects, but does not put them back into the display groups. Thus, the window still appears empty.
Workaround    The default rule system of Direct to Java Client never creates a user interface like this because it hardly ever makes sense. However, you can create it manually, for example, by changing parameters in the Direct to Java Client Assistant. If you do so, disable the select and deselect actions in the subform.
  
  

Enterprise Objects Framework

Reference2176526
ProblemApplying a qualifier with key path to top of horizontally mapped inheritance hierarchy generates invalid SQL.
DescriptionEnterprise Objects Framework's query building mechanism doesn't handle relationships to inheritance hierarchies. For example, suppose that you are are attempting to qualify a fetch through a to-many relationship (planes) that points to the top of a horizontally mapped inheritance hierarchy (for the entities Plane, FighterPlane, and TrainerPlane). If you want the query to test against all tables, you'd expect Enterprise Objects Framework to generate SQL similar to the following:

SELECT  t0.AIRPORT_ID
FROM PLANE t1, FIGHTER t2, TRAINER t3, AIRPORT t0
WHERE
(t1.LENGTH <= 1000 AND t0.AIRPORT_ID  = t1.AIRPORT_FK) OR
(t2.LENGTH <= 1000 AND t0.AIRPORT_ID  = t1.AIRPORT_FK) OR
(t3.LENGTH <= 1000 AND t0.AIRPORT_ID  = t1.AIRPORT_FK)

Instead, Enterprise Objects Framework generates the following SQL:

SELECT  t0.AIRPORT_ID
FROM PLANE t1, AIRPORT t0
WHERE
(t1.LENGTH <= 1000) AND
t0.AIRPORT_ID = t1.AIRPORT_FK

In other words, only the table for the root of the hierarchy is queried.
Workaround    You can create a qualifier that generates the correct SQL by:

1. Adding relationships in the source entity to all the tables in the inheritance hierarchy. For example, to the Airport entity, you'd add the relationships toFighters and toTrainers to the destination entities FighterPlane and TrainerPlane, respectively. Mark the relationships so they aren't class properties.

2. When building your query, explicitly list these extra relationships. In the Planes example, you'd fetch from Airport where "planes.length < 1000 OR toFigtherPlanes.length < 1000 OR toTrainerPlanes.length < 1000"

Alternatively, you might be able to solve this problem more generally by writing a post processor for EOQualifiers that splits up clauses that perform inheritance tests. The post processor could even programmatically generate the additional relationships on demand and register them with the model using names like "plane_Subclass_Fighter".

A generic EOQualifier post processor could be wired into Enterprise Objects Framework so that application writers don't have to know it exists. The right place for such a mechanism is probably in EOKeyValueQualifier's schemaBasedQualifierWithRootEntity: method (see EOSQLQualifier.h). You could put the post processor code in a subclass of EOKeyValueQualifier (with an appropriate call to super after the transformation, if any, is performed) and have your subclass pose as EOKeyValueQualifier.
  
  
Reference2177181
ProblemQualifying across a to-many relationship using the '"=" operator does not give the expected results.
DescriptionThe "=" qualifier operator is not designed to test whether an object appears in the list of objects across a to-many relationship. Instead, you should use the "contains" operator. For example, if you have a Movie object and you want to find out which Studio has a particular movie in its "movies" array, you can use the following:

"movies contains %@", someMovieObj

The "contains" qualifier works both for searching in memory and accessing the database.

If the to-many relationship has a reverse relationship that is to-one, you achieve much better performance if you query in the reverse direction. For example:

someMovieObject.valueForKey("studio")
Workaround    Use the "contains" operator to qualify across a to-many relationship. For better performance in cases where the reverse relationship is to-one, search in the reverse direction.
  
  
Reference2177631
ProblemAn EORelationship can return nil for its inverseRelationship after the inverse is added
DescriptionThe first time you ask the EORelationship for its inverseRelationship it searches all relationships in its destinationEntity looking for an inverse, it caches the result of this search. This cache does not always get invalidated when the relationships of the destinationEntity change, so after editing a model and adding an inverse relationship to an EORelationship (either in code or with EOModeler), an inverseRelationship message sent to the EORelationship can return nil.
Workaround    See the category on EORelationship in the ModelerBundle/RelationshipExtras.m example.
  
  
Reference2182008
ProblemAn NSNumber primary key with a value of 0 is assumed to mean NULL, invoking EOF's primary key generation (perhaps erroneously).
DescriptionStarting in EOF 2.2, EODatabaseContext assumes that an object with a single attribute primary key with a value of zero indicates a newly created instance. And as such, EOF attempts to get a new primary key for the object using the delegate hook or the adaptor-specific primary key generation mechanism. This change allows you to use scalar data types in your EO's (like "int") for primary keys, and still rely on EOF's automatic primary key generation. Unfortunately, if you have an existing database rows with primary keys of 0, attempts to update corresponding enterprise objects cause the EODatabaseContext to incorrectly attempt to get a new primary key. This can leave invalid foreign key refernces in other tables.
Workaround    Implement the EODatabaseContext delegate method databaseContext:newPrimaryKeyForObject:entity: and catch the case where the framework will mistakenly get a new key.

From EODatabaseContext.h
- (NSDictionary *)databaseContext:(EODatabaseContext *)context
newPrimaryKeyForObject:(id)object
entity:(EOEntity *)entity;
// If a newly inserted EO doesn't already have have a primary key set,
// this delegate is called to generate a key.  If the delegate is not implemented,
// or returns nil, then the DatabaseContext will call
// [EOAdaptorChannel primaryKeyForNewRowWithEntity:(EOEntity *)entity]
// to attempt to generate the key.


Example delegate implementation:
{
    ...
    model = [[EOModelGroup defaultGroup] modelNamed:@"myModel"];
    dbContext = [EODatabaseContext registeredDatabaseContextForModel:modeleditingContext:editingContext];
    [dbContext setDelegate:self];
    ...
}

- (NSDictionary *)databaseContext:(EODatabaseContext *)context
newPrimaryKeyForObject:(id)object
entity:(EOEntity *)entity
{
    if (entity == entityThatIKnowHasAValidRowWithAKeyOfZero)
        if ([[object valueForKey:primaryKeyThatCanBeZero] isEqual:[NSNumber zero]])
            return [NSNumber zero];
    return nil;
}
  
  
Reference2280881
ProblemConcurrent multithreaded saves may bypass optimistic locking check
DescriptionAlthough it has not yet been verified, EOF may have a brief window where two sessions modifying the same object will get last-one-wins behavior, instead of a merge (which is still last-one-wins at the attribute level). For example:
Editing context 1 locks, modifies object 1
Editing context 2 locks, modifies object 1
Editing context 1 saves changes, unlocks, change notification enqueued on editing context 1
Editing context 2 saves its modifications to object 1 without merging in editing context 1's modifications
Workaround    None.
  
  
Reference2329635
ProblemEOF can generate incorrect SQL for disjunctions of qualifiers where one of the qualifiers involves an optional relationship.
DescriptionThe form of the SQL generated for an EOOrQualifier is similar to the SQL generated for an EOAndQualifier, but with "OR" substituted for "AND". For example, the qualifier "attr1 = v1 OR rel.attr2 = v2" would generate a SQL WHERE clause something like...
WHERE (ENTITY.ATTR1 = v1 or REL.ATTR2 = v2) AND REL.PK = ENTITY.PK

For a mandatory relationship 'rel', there will always be a match in the REL table and the above SQL WHERE clause will end up giving the correct result. However, for an optional relationship with a NULL value, the WHERE clause fails to return any rows even if there were rows in the ENTITY table that matched the value v1.

The appropriate SQL would be
WHERE ENTITY.ATTR1 = v1 or (REL.ATTR2 = v2 AND REL.PK = ENTITY.PK)

which would give the correct results for all cases.
Workaround    Separate your original fetch specification into independent fetch specifications that do not have disjunctions involving optional relationships, and concatenate the multiple results. Naturally, the same EO might be returned by multiple fetch specifications so you may need to filter out duplicates from the concatenated results. For complicated fetch specifications, it may be more effecient to use a custom SQL query (see documentation on EOCustomQueryExpressionHintKey in EODatabaseContext.h). If you choose to use custom SQL and you have multiple qualifiers across relationships, you should consider using DISTINCT since there may be multiple ways for one EO to satisfy the qualifier.
  
  
Reference2359723
ProblemThe EOF documentation implies that only a single SELECT statement is needed to perform a deep fetch when all the subentities of the fetch specification's entity map to the same table. However, only one specific case is handled with a single SELECT. In the general case, one SELECT is issued for each subentity.
DescriptionEOF 4.5 performs one SELECT for an inheritance hierarchy if each subentity is mapped to the same table and if each subentity either has a restricting qualifier of the form "attr = val", where "attr" is the same for all subentities and "val" is unique to each subentity, or the subentity is abstract and has no restricting qualifier. If some subentity doesn't qualify for the optimization, then its parent also doesn't qualify. However, if some subtree of an inheritance hierarchy qualifies for the single table fetch, then that subtree is fetched in one SELECT even though other subentities of the parent entity have to be fetched individually.
Workaround    Arrange your single table inheritance heirarchy so that it meets the optimization criteria.
  
  
Reference2417236
ProblemUsing InvalidateAllObjects or InvalidateObjectsWithGlobalIDs directly on an object store coordinator or database context can cause deadlocking problems with shared editing contexts.
DescriptionWhen you invalidate objects via an editing context (shared or non-shared), the context's implementation insures that the shared context it knows about is completely unlocked for the duration of the invalidation process. This prevents deadlocking with locks in EOAccess. For example, if another thread already has locked EOAccess, but needs a shared context's writer lock, your application would deadlock if the current thread still had a reader lock on the shared context.
Workaround    If you need to invalidate objects directly via the object store coordinator or database context classes, be sure that your thread does not hold any locks on any shared contexts. If you are only using the default shared context, you can do this like so:
EOSharedEditingContext.defaultSharedEditingContext().surrenderReaderLocks();
myCoordinator.invalidateAllObjects();
EOSharedEditingContext.defaultSharedEditingContext().retrieveReaderLocks();
  
  
Reference2431180
ProblemAfter calling myEODatabaseContext.invalidateAllObjects(), subsequent saves either fail to save changes or just raise.
DescriptionIf an application has any EOEditingContexts that contain unsaved inserted objects, any call to myEODatabaseContext.invalidateAllObjects() will leave those EOEditingContexts in an inconsistent state. If you try to save the changes in any such EOEditingContext, the inserted objects will not be saved, or you might get an exception because these objects are mistakenly treated as updated objects.
Workaround    Replace all invocations of
dbc.invalidateAllObjects()

with
dbc.invalidateObjectsWithGlobalIDs(dbc.database().snapshots().allKeys())
  
  
Reference2450687
ProblemEOF does not automatically generate special 12 byte primary keys.
DescriptionIn previous versions of WebObjects, EOF would automatically generate primary keys for primary key attributes of type NSData which were exactly 12 bytes long. Starting with WebObjects 5, EOF no longer provides this functionality.
Workaround    Implement the EODatabaseContext Delegate method databaseContextNewPrimaryKey() or assign the primary key yourself. EOTemporaryGlobalID.assignGloballyUniqueBytes() might be a useful tool in that process, as well as various classes in the standard JDK packages java.security and java.util, notably java.security.MessageDigest.
  
  
Reference 2505668
ProblemThe application does not reflect changes in the model until the project is rebuilt.
DescriptionCurrently, there is no rapid turnaround for model discovery. The application gets its information from the build directory, so the applicatiion loads the built model instead of the original.
Workaround    Rebuild the project after changing the model.
  
  
Reference2577100
ProblemEOSQLQualifier does not behave correctly.
DescriptionEOSQLQualifier is deprecated. Do not use, subclass, or replace this class.
Workaround    Use EOQualifier in EOControl.
  
  
Reference2604493
ProblemEOAdaptorChannel and EOAdaptorContext no longer have setDebugEnabled methods.
DescriptionThese methods have been removed because NSLog now handles all of the debug logging.
Workaround    Use NSLog.setDebugGroups and NSLog.setDebugLevel to selectively enable debug messages. The debug groups associated with the adaptors are DebugGroupDatabaseAccess and DebugGroupSQLGeneration.
  
  
Reference2663960
ProblemEnterpriseObjects in an "Owns Destination" relationship are not automatically inserted/deleted if the relationship is altered several times rapidly.
DescriptionObjects in an "Owns Destination" relationship receive some special treatment. They are automatically inserted into the owner's EOEditingContext, and they are automatically deleted whenever the relationship with the owner is broken, or the owner itself is deleted. However, these changes can only be tracked with a precision of one event. Specifically, if several changes are made to an "Owns Destination" relationship before the next invocation of processRecentChanges(), only the last change will be noticed by the EOEditingContext.

This is a very rare problem. One usually does not need to invoke processRecentChanges() directly. When it occurs, it is exclusively in code directly using EOF in a programmatic manner.
Workaround    To avoid this problem, either invoke processRecentChanges() or saveChanges() on the EOEditingContext involved more frequently. Typically, this invocation would be immediately after using addObjectToBothSidesOfRelationship() or removeObjectFromBothSidesOfRelationship(). Alternatively, one can assume responsibility for inserting and deleting these owned objects from the EOEditingContext oneself.
  
  

Database Adaptors

Reference2520093
ProblemCorrupted JDBC type information is not detected gracefully.
DescriptionThe JDBC type information is cached in the EOModel file as part of the connection dictionary. It can become corrupted if a user incorrectly edits the connection dictionary in EOModeler.
Workaround    Delete the jdbc2Info entry from the model's connection dictionary. The adaptor will refetch the JDBC info when it needs it.
  
  
Reference2526957
ProblemTrailing spaces are not always trimmed from CHAR attributes.
DescriptionA database column of type CHAR holds a string value that is right-padded with spaces to the width of the column. String values in Enterprise Objects, however, normally do not have trailing spaces. An attribute in an EOModel that maps to a CHAR column should have a "Value Type" of "c" to indicate that the JDBC Adaptor should trim trailing spaces when fetching values for that attribute. If the Value Type is blank, then no trimming will occur. Attributes mapping to VARCHAR columns are never trimmed.
Workaround    Set the attribute's Value Type to "c".
  
  
Reference2562635
ProblemThe JDBC adaptor does not support the use of Oracle REF CURSOR or custom types in stored procedures.
DescriptionThe JDBC adaptor does not handle custom types or REF CURSOR. A proprietary datatype, REF CURSOR denotes a variable that points to a query work area rather than store an item.

If one were to create a new EOStoredProcedure based on a stored procedure that takes a REF CURSOR as input, one might encounter exceptions like the following:

PLS-00306: wrong number or types of arguments in call to 'FETCH_MOVIES_ALL'
ORA-06550: line 1, column 7:
PL/SQL: Statement ignored

The reason is that the JDBC adaptor is trying to pass attribute values where the stored procedure expects a REF CURSOR.
Workaround    To make the stored procedure work with the JDBC adaptor, revise the stored procedure to take Java variables as input and to return results as output. If revision is not an option, then create a stored procedure "wrapper" that invokes the original one but has the characteristics required to work with the JDBC adaptor.
  
  

Foundation Framework

Reference2421581
ProblemThe "cache-control: no-cache" http header causes Internet Explorer 5 to hang when using a proxy server.
DescriptionBy default WebObjects adds the "cache-control" header with a value of "no-cache" (among others) to responses. This particular header causes Microsoft's Internet Explorer 5 to hang if a proxy server is being used.
Workaround    Set the WOAllowsCacheControlHeader user default to false. This will cause the "cache-control" header (and all associated values) to be omitted from WebObjects responses.
  
  
Reference2505603
ProblemUsing %w in a NSTimestampFormatter does not format the day of the week as a number. Using %z in a NSTimestampFormatter does not format the time zone as an offset.
DescriptionDue to the implementation of NSTimestampFormatter, the %w format specifier is unsupported. The formatter formats the day as if %a was used instead. The %z format specifier is also unsupported. The formatter formats the time zone as an abbreviation instead.
Workaround    None.
  
  
Reference2662230
ProblemProjects created with the beta version of WebObjects 5 need to include the JavaXML framework to function properly
DescriptionAfter WebObjects5 beta was shipped, we moved the xml parser into its own framework named JavaXML. This framework is required by all projects that include the Java Foundation framework, even if they don't explicitly perform xml parsing. The runtime needs it to resolve some symbols when the Foundation classes are initialized. A common symptom of this problem is seeing error messages like the following when the application starts up:

Exception occurred while loading bundles from classpath during NSBundle class initialization: org/xml/sax/SAXException

All new projects greated with the final version of WebObjects 5 include this framework by default.
Workaround    For projects built with the beta, add /System/Library/Frameworks/JavaXML.framework to your project and recompile.
  
  
Reference2668027
ProblemNSTimestamp returns values that are off by an hour after 2037 and before 1902.
DescriptionNSTimestamp relies on NSTimeZone, which uses the Unix implementation of time zones. This implementation has rollover problems at the Unix beginning and end of time (2^31 seconds before or after January 1, 1970). As a result, timestamps created with dates before 1902 or after 2037 may be off by an hour.
Workaround    none
  
  
Reference2679121
ProblemNSNumberFormatter cannot be both shared and changed in a multithreaded environment.
DescriptionNSNumberFormatter can be shared among many threads, however, in such an environment, these threads may not change the number formatter (i.e. invoke any of the set... methods). The format() and parseObject() routines have no side effects on the number formatter, and may be safely called as long as no other thread is changing the number formatter with a set... invocation.

One consequence of this is that the "defaultFormatter" returned by various framework methods such as defaultFormatterForClass() and defaultFormatterForKeyPath() must be treated as though they were immutable.
Workaround    One can create a proxy object which performs more aggressive locking, and pass the proxy between threads. One would have to ensure that only one thread could change the NSNumberFormatter object at a time, and at that time, no other threads were using the number formatter in any manner. Basically, a multi-reader, single-writer lock.
  
  
Reference2685345
ProblemNSValidation and validation method semantics have changed.
DescriptionDevelopers should be particularly aware of this change to validation methods. In WebObjects 4.5, validation methods returned an exception object if the target object was invalid, and received a pointer to the target as their parameter. If coercion was necessary, the validation method would perform a side effect on its parameter.
Workaround    In WebObjects 5, this was changed to better accomodate the Java language. There are no side effects on the argument, and the return value is the desired, valid value. If something is invalid, an NSValidation.ValidationException must be thrown. Returning null is be interpreted as value coercion to the null Object reference.
  
  
Reference2687367
ProblemNSTimestamp is not fully compatible with java.util.Date.
DescriptionThe following two pieces of code may return different results during/near daylight savings time transitions:
GregorianCalendar myCalendar = GregorianCalendar.getInstance();
myCalendar.set(year, month, day, hour, minute, second);
NSTimestamp myTimestamp = new NSTimestamp(myCalendar.getTime());
and
NSTimestamp myTimestamp = new NSTimestamp(year, month, day, hour, minute, second);
This is due to a bug in the way java.util.Calendar computes time from field values.
Workaround    Use NSTimestamp(year, month, day, hour, minute, second). It is no longer deprecated.
  
  

Development Tools

Reference2180253
ProblemWebObjects Builder does not validate keys and values in the bindings inspector
DescriptionWebObjects Builder lets you write illegal values (such as values with unrecognized characters) for binding attributes and values. These values are written to your .wod file without validation, so your .wod file will not be correct.
Workaround    Don't set your bindings to such values. If you do, close the component and reopen it. WebObjects Builder displays a parse error and puts you in source editing mode, where you can fix the corrupted bindings.
  
  
Reference2256367
ProblemConfiguration of WODisplayGroups in WebObjects Builder is not undoable.
DescriptionWebObjects Builder won't undo any changes made to a WODisplayGroup via the configuration panel.
Workaround    Changes can be reverted before dismissing the panel. Otherwise, you must restore the desired settings by hand.
  
  
Reference2269932
ProblemAdding a subproject of type EOJavaClientSubproject does not add the EOJavaClient.framework to the project's frameworks.
DescriptionIf you create Java Client interface controllers and interface files (nib files) in a Java Client subproject, you have to add the EOJavaClient.framework to the root project's frameworks. Otherwise you can't compile the client-side classes and you can't run the application.
Workaround    Add the EOJavaClient.framework by hand.
  
  
Reference2274651
ProblemIn WebObjects Builder, opening a file for which you do not have read permission presents a blank document; no warning is generated
DescriptionAttempting to open a file for which you do not have read permission will result in a new blank document. This could result in the false perception that the component is actually blank, which may not be the case.
Workaround    Make sure permissions are set correctly for projects you are working on and copy any read-only examples to your own directory.
  
  
Reference2275826
ProblemEOPalette won't parse keys from the source code of client-side Java classes
DescriptionIf you drop a display group into a client-side nib, EOPalette won't recognize keys from the client-side class associated with the entity. Instead, it parses keys from the server side class.
Workaround    Add any keys you need manually, using the EODisplayGroup inspector.
  
  
Reference2327908
ProblemJava Client applications need the Java Plugin from Sun.
DescriptionWe recommend running Java Client applets with Sun's Java Plugin. Java Client applications run only on a Java 2 (JDK 1.2) or higher virtual machine.
Workaround    In the WOJavaClientApplet element (typically in your project's Main.wo component), set the useJavaPlugin attribute to true.
  
  
Reference2330551
ProblemWebObjects Builder deletes two keys when they are defined on the same line in the source file.
DescriptionIf you have the following code:

public String aKey, aKey2;

and you delete aKey using WebObjects Builder's key pull-down menu, aKey2 is also deleted.
Workaround    Define your keys on separate lines.
  
  
Reference2370222
ProblemOpening a WebObjects 4.0 component can generate errors in WebObjects Builder.
DescriptionIn WebObjects 5, WebObjects Builder now detects errors in components. One particular error occurs when previous versions of WebObjects Builder inserted the text "Custom" between the <WEBOBJECT> and </WEBOBJECT> tags for a custom component. If the component does not contain a WOComponentContent dynamic element, such component content is illegal and the current WebObjects Builder flags the content as an error.
Workaround    Remove the "Custom" text between the <WEBOBJECT> and </WEBOBJECT> tags for custom components without WOComponentContent.
  
  
Reference2415737
ProblemDeploying WebObjects book images show a File Transfer button that doesn't appear in the final version of Monitor.
DescriptionDue to security considerations, a planned "File Transfer" feature in the WebObjects Monitor application was pulled from the app after the Deploying WebObjects book was submitted to the release. All of the images in this book show a "File Transfer" button that doesn't appear in the final product.
Workaround    None.
  
  
Reference2418323
ProblemSubprojects deeper than two levels do not render html in rapid turnaround mode
DescriptionIn development mode, rapid turnaround only works for the resource files in your top level project directory and in the first level of subprojects.
Workaround    Add to the NSProjectSearchPath user default each of the subprojects' subprojects directory paths. See the documentation on user defaults to learn how to modify them.
  
  
Reference2425256
ProblemOn Windows 2000, some of the fonts used by tools such as ProjectBuilder, FileMerge, WebObjectsBuilder are hard to read
DescriptionWindows 2000 introduced a new "message" font, Tahoma. This font is difficult to read at point sizes larger than 9.
Workaround    Open the Display control panel, click on the Appearance tab, select Message Box from the Item pulldown menu, and then select another font (such as MS Sans Serif) instead of Tahoma.
  
  
Reference2555382
ProblemJava Virtual Machine can't find classes in third party .jar files.
DescriptionIf your application depends on third party jar files, you may need to be sure they're located correctly on the file system and your application's launch script points to them.
Workaround    By modifying the Makefile.preamble, you make the third party jar files for development and deployment. Suppose you need to include a foo.jar java library to your project.

1. In your application directory, save it as Java/foo.jar.
2. Add it to your Resources bucket under a Java directory (on Project Builder WO, you may have to add the Java/foo.jar path directly to the PB.project plist file). When you compile the application, foo.jar will appear at the same level as <your-application>.jar under Contents/Resources/Java.
3. Modify the OTHER_CLASSPATH flag (which is normally commented out) in the Makefile.preamble file so it contains both the deployment and development locations:

OTHER_CLASSPATH = APPROOT/Contents/Resources/Java/foo.jar$(CLASSPATH_DELIMITER)$(SRCROOT)/Java/foo.jar

The APPROOT identifier in the first path component is ignored during development. At launch time, however, the launch scripts replace APPROOT by the actual application path, which ensures the jar file is available when the application is deployed.

Note that the second path component of OTHER_CLASSPATH is the actual build time location of the foo.jar package. It needs to appear after the deployment path because otherwise the jar file may be picked up when testing the application on a networked development environment.
  
  
Reference2644150
ProblemCompiled applications moved to or from Windows do not work on the destination platform: The classpath passed to the Java VM is incorrect, or the launch script terminates before the JVM can be invoked.
DescriptionThis may be due to a translation error in moving the classpath file between platforms. While UNIX platforms (including Mac OS X) use a newline (\n) character to delineate the end of a line, Windows uses a carriage return followed by a line feed character (\r\n, sometimes displayed as ^M, e.g. when viewing a file in the 'vi' editor). Some tools used to move files between platforms may incorrectly translate end-of-line characters to incorrect values for the new platforms.

For instance, it appears that using the version of ftp supplied with Windows 2000 and transferring files in Binary mode may result in this mistranslation of text files.
Workaround    Use of an alternative method to copy the application to another platform may work. For example, one could use an alternate ftp program, or copy the files to or from a Samba-mounted fileserver using Windows Explorer.
  
  
Reference2650631
ProblemWhen you change an EOModel used inside an interface currently open in Interface Builder, and drag a new entity or fetch specification from EOModeler to the interface file, you get errors about missing items.
DescriptionInterface Builder palettes do not immediately notice changes to EOModels.
Workaround    Revert the interface file in InterfaceBuilder to the saved version (or close and reopen it).
  
  
Reference2662018
ProblemA WebObjects project cannot be installed from inside the Project Builder IDE on Mac OS X, or performing a split install did not work on Mac OS X.
DescriptionAn install should not be performed from inside the Project Builder IDE. This should be done from a Terminal command line. Split installs require that the install command be issued twice, once with each of two different build styles.
Workaround    To perform a "standard" (not split) install, make you you have appropriate permissions, change to the directory containing your project's .pbproj file and type the command:

pbxbuild install -buildstyle Deployment DSTROOT=/

To perform a split install, first perform a standard install and then type the command:

pbxbuild install -buildstyle WebServer DSTROOT=/
  
  
Reference2673052
ProblemWebObjects projects created or imported into the new Project Builder on Mac OS X in the WebObjects 5 Beta prerelease do not compile properly under WebObjects 5 final release.
DescriptionSeveral changes were made to the build system for WebObjects 5 on Mac OS X between Beta and the final release which were not backwards-compatible with projects created on the Beta release.
Workaround    The safest workaround is to import the WebObjects 4.5 project again. If the project is newly-created for WebObjects 5, you can create a new project using the project templates in the final release and import your files into the new project.

An alternative solution to make a Beta project work is to modify the targets of your project as follows:

1) Clean the project.
2) Choose the "Server" target in the targets list.
3) Choose "Rename" from the "Project" menu and rename the "Server" target to "Application Server".
4) Select the "Build Settings" tab.
5) The field labeled "Product name" should have the value "<your-project-namegt;$(SERVER_UNIQUIFIER)". Change this value to "_WO$(SERVER_UNIQUIFIER)<your-project-name>".
6) Choose the "Client" target in the targets list.
7) Choose "Rename" from the "Project" menu and rename the "Client" target to "Web Server".
8) Select the "Build Settings" tab.
9) The field labeled "Product name" should have the value "<your-project-name>$(CLIENT_UNIQUIFIER)". Change this value to "_WO$(CLIENT_UNIQUIFIER)<your-project-name>".
10) Add the JavaXML.framework from /System/Library/Frameworks to your project.
11) Rebuild the project.
  
  
Reference2674710
ProblemSpecifying the flavor of Sun JVM to use by adding the appropriate switch (-server, -client, -classic) as a launch argument does not work.
DescriptionThe switch to select the flavor of Sun JVM to use must always be specified as the first argument passed to the JVM invocation. However, the arguments specified using the JVM_OPTIONS or JDB_OPTIONS values in the Makefile.preamble (in ProjectBuilderWO on Windows 2000) or in the main target's build settings (in Project Builder on Mac OS X), or on the command line when invoking a WebObjects launch script, do not guarantee that such a switch will be placed first among the arguments.
Workaround    In order to use these switches, you should set the JAVA_VM build setting in your Makefile.preamble (in ProjectBuilderWO on Windows 2000) or in the main target's build settings (in Project Builder on Mac OS X). Add the appropriate switch after the JVM's name and it will always be included as the first argument. For example, to use the -server switch, set the variable to:

JAVA_VM = java -server

This can also be accomplished by editing the classpath file directly and setting the value on the line beginning with '# JVM ==', for instance:

# JVM == java -server

Note that if your JVM is an absolute path, and that path contains spaces or other special characters in it, then you must explicitly quote the path to the JVM or the launch script might incorrectly parse this value.
  
  
Reference2675174
ProblemDeployment testing and configuration should include Java vm options.
DescriptionThe exact performance characteristics of the Java runtime vary from platform to platform. For optimal performance, we recommend experimenting with the options available for Java on your deployment platform. Adjusting the minimum and maximum heap sizes can affect the number of simultaneous sessions your application can handle.

For more information see:
http://java.sun.com/docs/hotspot/VMOptions.html
http://java.sun.com/docs/hotspot/PerformanceFAQ.html
Workaround    Not applicable.
  
  
Reference2676249
ProblemA project imported from ProjectBuilderWO into Project Builder on Mac OS X looks or behaves differently from brand new projects created using Project Builder.
DescriptionThere are certain issues which project import in Project Builder does not solve, and which must be resolved by the developer after importing the project. Known issues include:

1) The organization of the file groups in the file browser in PB will closely mirror that of the original PBWO project, rather than the organization of the WebObjects Application PB template.
2) Information in the Makefile.preamble and Makefile.postamble files in a PBWO project cannot be processed by project import and will not appear in the PB project.
3) JavaClient applications with a subproject whose Java files are compiled for both the server and the client sides (e.g., a Common.subproj) will have their files linked to only the Application Server target in PB, not also to the Web Server target.
4) The project's signature in the PkgInfo file after compilation will be APPL???? or FMWK???? not APPLwebo or FMWKwebo.
5) The default debugger for an imported project will be gdb, not jdb.
6) Aggregate projects may import strangely, or not at all.
Workaround    Most of these issues can be worked around by the user after import. To fix the corresponding issues above, do the following:

1) File groups can be reorganized in a highly flexible manner in PB. In particular, the file groups representing .subproj folders no longer have any functional purpose in compiling a project in PB - since file organization and build product organization are orthogonal in PB - and those files can be reorganized as desired.
2) Data in Makefile.preamble and Makefile.postamble files must be ported manually after import. Build variables will likely have to be set in the Build Settings panel of one or more targets. Additional targets can be implemented as Shell Script or Copy Files Build Phases on one or more targets.
3) After importing a subproject which contains Java files intended for both the server and the client sides, files can be added to any targets which the import process did not automatically add them to. It is valid for files to be attached to multiple targets in PB.
4) The product signature is defined in the Application Settings or Framework Settings tab of the project's main target (the one with the same name as the project). The CFBundleSignature value (labelled just "signature" in the Simple Settings view) can be changed from ???? to webo after import.
5) The debugger used to debug a project is defined in the Executables tab of the project's main target. Go to the Debugger subtab and change the radio button to select "Java Debugger" rather than "Gdb".
6) Aggregate projects are not supported in WebObjects 5. Individual products in an aggregate PBWO project should be identified and imported individually into separate PB projects.
  
  
Reference2677023
ProblemLaunching a WebObjects application on Windows 2000 from a directory mounted via Samba, or using a framework or jar file on a Samba-mounted volume, does not work.
DescriptionThe most common case of this occurs when your application itself is sitting on a samba-mounted directory. In this case, lines in the CLSSPATH.TXT that begin with APPROOT will resolve to a samba-mounted directory and so will not be used at run-time. When one tries to run the application, it will throw a java.lang.NoClassDefFoundError for the "Application" class, which is defined in the application's local jar.

One will get a similar exception if one tries to use a framework on a samba-mounted volume as well.
Workaround    Do not launch WebObjects applications mounted remotely via Samba. Do not refer to jar files or frameworks on samba-mounted directories. Copy the application or resource to the local disk and re-launch your application.
  
  
Reference2681948
ProblemIf Project Builder crashes, rapid turnaround stops working.
DescriptionIf Project Builder crashes, a communication socket does not get cleaned up properly. This prevents future invocations of Project Builder from binding to the socket. The net effect is that rapid turnaround is broken.
Workaround    Reboot your machine.
  
  

Web Server Adaptors

Reference2173679
ProblemCan't run two WebObjects adaptors on the same machine with two different web servers.
DescriptionIf you attempt to run two WebObjects adaptors on the same machine with two different web servers, the adaptors share the public WebObjects.conf file, allowing applications to be visible on both web servers.
Workaround    There is a #define that sets the location of the configuration directory in Apple/Developer/Examples/WebObjects/Source/Adaptors/Adaptor/woconfig.h. Change this #define and recompile the adaptor. Now you can have several web servers running adaptors that do not share the same applications.
  
  
Reference2389605
ProblemWhy does WebObjects use an HTTP success status code when a WebObjects app returns an error?
DescriptionWhen the webserver adaptor detects an error, it returns a simple HTML page describing the problem, but not an error status. This is done so that the user will see the returned HTML, and not the message the browser thinks should be substituted.
Workaround    None, aside from modifying the adaptor source and rebuilding.
  
  
Reference2420040
ProblemSecurity warning: asking Apache for a non-existent application can generate an application listing
DescriptionWhen you specify an invalid application name to the WebObjects Apache plug-in, the plug-in invokes the CGI is adaptor which then produces a list (including hyperlinks) of all available applications (on the subnet if you're running in multicast mode). Giving your end users access to all running WebObjects applications is often undesireable, especially in deployment situations.
Workaround    Either remove the CGI adaptor or install the Apache module as /Apps/WebObjects instead of cgi-bin.
  
  
Reference2455171
ProblemWOHTTPConnections cannot be shared between worker threads.
DescriptionDue to the fact that WOHTTPConnection currently has one input buffer per instance, and no locking thereof, WOHTTPConnection objects cannot easily be shared between threads, as unpredictable results will occur.
Workaround    Either avoid sharing WOHTTPConnection objects between threads, or add additional locking logic in your own code.
  
  
Reference2670515
ProblemAdaptor uses default configuration if no wotaskd responding to multicast found
DescriptionIf the WebObjects adaptor is configured to search for wotaskd using multicast and no server responds, the adaptor falls back to querying wotaskd on localhost:1085. This may produce unexpected and undesired results.
Workaround    The WebObjects adaptor has been modified to only read configuration from servers which respond to the multicast query. If no servers respond to the multicast query, the adaptor does not attempt to read configuration.
  
  

Deployment

Reference2282569
ProblemApplications with dynamic images may leak them.
DescriptionIf you are testing such an application with the playback tool, the tool will not do the necessary callbacks to retrieve dynamic images. Therefore, these images will stay in the data cache of the app and never be released. Same can happen once deployed, as clients disable image loading from their browser. You will see your application leaking when it is not really, it is just waiting indefinitely for someone to come ask for an image.
Workaround    When using the data, mimeType bindings for dynamic images, try to use the key binding as well. With the key binding set to employee.picture, only once will the picture be saved in memory and stay there, limiting the amount of data leaked. Otherwise, you can always use the -flushCache call on WOResourceManager regularly. This clears out everything from the data cache, so this may impact currently connected users.
  
  
Reference2340057
ProblemRequests to a WebObjects application cause stat calls in Netscape servers
DescriptionWhen observing a Netscape server using a tool such as "truss" with the NSAPI or CGI adaptor accepting requests for a WebObjects application, several stat calls are visible. This is indicative of the machine perfoming system calls to look up directories, which can have a detrimental impact on performance.
Workaround    The stat calls are primarily caused by the presence of a PathCheck directive in Netscape's obj.conf:
PathCheck fn=find-pathinfo
If you are not using CGI programs (that is, the NSAPI adaptor with WebObjects and no other CGI programs), this directive can be removed to reduce the number of stat calls.
  
  
Reference2359284
Problem"Disabling or Protecting Administrator Access" in "What's New in WebObjects 4.5" isn't quite correct for CGI.
DescriptionIn the CGI section beneath "Disabling or Protecting Administrator Access" in the "What's New in WebObjects 4.5" document, you're told to uncomment some code in "main.c". In fact, the code is in WebObjects.c and can be found in the main() function.
Workaround    Use environment variables as described later in the CGI section or uncomment the code in WebObjects.c.
  
  
Reference2394552
Problemwotaskd writes out a usable WOConfig.xml file.
Descriptionwotaskd now writes a WOConfig.xml file to /Local/Library/WebObjects/Configuration. This is an XML file in the same format as the XML returned by hitting wotaskd at port 1085, and it can be used to enable the file-based load balancing scheme. See "Accessing Configuration Information" in "What's New in WebObjects 4.5" for information on how to disable multicast mode and instead have your web server adaptors obtain their configuration information from this XML file.
Workaround    None needed.
  
  
Reference2404574
ProblemWindows: wotaskd crashed and will not restart
DescriptionOn Windows, if wotaskd crashes for some reason it should be restarted automatically by the woservice process. However, if the machine is set to have Dr Watson visual alerts appear in the event of a crash, the process will hang and wotaskd won't restart until the Dr Watson panel is dismissed.
Workaround    Turn off Dr Watson visual alerts. This is usually required for any server machine.
  
  
Reference2408559
ProblemApplications that launch from a terminal shell fail to launch under wotaskd.
DescriptionThis situation can occur when the application needs environment settings not available from wotaskd, which runs as root. In particular, an incorrect CLASSPATH environment variable can prevent an application from launching.

If you su to root, the shell inherits your environment variables including CLASSPATH. These environment variables do not reflect the environment variables available when the application is started under wotaskd.
Workaround    Modify the wotaskd startup script to provide a CLASSPATH that includes all frameworks your application needs.
  
  
Reference2418131
ProblemIt isn't always clear which port you need to connect to for Monitor and the WOInfoCenter.
DescriptionMuch of the debugging information for Monitor and WOInfoCenter has been turned off. Because of that, it may not be clear which port you're supposed to connect to.
Workaround    Create a default so that you always get the same port. For instance:
defaults write Monitor WOPort 9999
  
  
Reference2424573
ProblemA POST request to a WebObjects application via Apache 1.3 or later using the CGI adaptor results in null form values.
DescriptionThe latest version of Apache passes certain environment variables to the CGI adaptor that contain newline characters. The WebObjects CGI adaptor converts all of these environment variables to headers - which can confuse the application when parsing HTTP headers - resulting in the loss of form values.
Workaround    Use a CGI utility such as printenv (it may be installed by default in your cgi-bin directory but you may need to add execute permission) to determine if you have any environment variables being passed to CGI programs that contain newline characters. A common one is SERVER_SIGNATURE. Modify Apache's configuration file ServerSignature entry to be Off. It may also be possible to use the new SetEnvIf Directive, although this workaround has not been tested.
  
  
Reference2424576
ProblemNSAPI adaptor fails to build on Windows
DescriptionOn Windows the NSAPI adaptor doesn't compile, complaining about not being able to find header files.
Workaround    Install the Netscape server 3.6, locate the header files in their source or examples directory, and follow the build instructions in c:/Apple/Developer/Examples/WebObjects/Source/Adaptors/BuildingInstructions.html
  
  
Reference2425106
ProblemWebObjects applications launched by wotaskd have logging redirected to /dev/null
DescriptionWhen wotaskd launches WebObjects applications, it redirects logging to /dev/null.
Workaround    Launch a shell script instead. The name of the shell script (minus the extension) must be the same as the name of the executable. So, for instance, if you have a script to launch HelloWorldCompiled, the script should be named HelloWorldCompiled.sh (on Windows, the executable would be HelloWorldCompiled.exe and the script would be HelloWorldCompiled.bat).
  
  
Reference2425742
ProblemMonitor's Path Wizard can be confused by the back button
DescriptionIf you use the browser's back button in Monitor's Path Wizard, you may see an exception. Monitor is still running, however. The wizard is not correctly keeping track of the current page.
Workaround    Avoid using the browser back button when in the Path Wizard.
  
  
Reference2659527
ProblemSessions don't time out according to the setting of the WOSessionTimeOut user default.
DescriptionThe documentation sometimes incorrectly refers to the WOSessionTimeOut user default as WOSessionTimeout. WebObjects does not recognize the latter spelling.
Workaround    Be sure to spell the user default with the proper capitalization: WOSessionTimeOut.
  
  
Reference2665595
Problemtcsh runs out of memory when executing WebObjects applications.
DescriptionThis shell limits the stack size and data size of the applications that run within it.
Workaround    execute the unlimit command before executing the applications.
  
  
Reference2673699
ProblemI need to know the command line arguments for WOServices.
DescriptionOn MacOSX, WOServices is called javawoservice.sh and located at /System/Library/WebObjects/JavaApplications/wotaskd.woa/Contents/Resources/javawoservice.sh. The usage synopsis for javawoservices.sh is:
javawoservice.sh [ -help ] | [ [ -waitTime <seconds> ] [ retries <attempts> ]
              [ -scaleTimeouts YES|NO ] [ -scaleFactor <amount> ] ]
              -appPath <path> [ <application-specific arguments> ]
Note: javawoservice.sh -help gives you much more information about the arguments themselves.

On Solaris and UNIX platforms other than Mac OS X, WOServices is located at $NEXT_ROOT/Library/WebObjects/Executables/WOServices. The usage synopsis for WOServices is:
WOServices [ -help ] | [start |  stop |
    enable -altJVMPath <path-to-other-Java-VM> | disable]
Note: WOServices -help gives you much more information about the arguments themselves.
Workaround    None needed.
  
  

Examples

Reference2676784
ProblemStrange behavior when running multiple webservers on a single host using Apache or CGI adaptors.
DescriptionFor performance reasons, the new Apache and CGI adaptors in 4.5.1 and 5.0 use a shared state file, WOAdaptorState. This file is stored in the temporary directory (/tmp or C:\temp, typically). However, running multiple webservers on the same machine may cause collisions if more than one are using the WebObjects Apache or CGI adaptors. In the event of collisions, the results will be confusing. Because the location and name of the WOAdaptorState file is hardcoded, the webservers will "fight" over the configuration, and whichever webserver last requested configuration information will overwrite the configuration stored in the file.
Workaround    For each CGI or Apache adaptor, edit the source code to make the location or name of the WOAdaptorState file unique and compile.
  
  
Reference2678094
ProblemThe Mac OS X Server WebServices Performance Cache actually lowers WebObjects performance.
DescriptionMac OS X Server ships with a performance cache for the webserver; this performance cache caches static webpages in memory for better performance. The performance cache is enabled by default. However, since WebObjects primarily serves dynamic webpages (which cannot be cached), the performance cache is an added layer between the client and the WebObjects application. If the performance cache is enabled, WebObjects application may serve requests slightly slower. If the host is primarily being used to serve WebObjects applications, it is suggested that the performance cache be disabled.
Workaround    Disable the Performance Cache as follows:
1. Start and log-in to the Server Admin application.
2. Go to the Internet tab.
3. Click Web and choose the "Configure Web Service" option from the menu.
4. Go to the General tab.
5. Deselect "Enable Performance Cache".
6. Click Save.
  
  
Reference2685595
Problemwotaskd quits when I log out of Windows 2000.
DescriptionBecause of limitations in Windows 2000, wotaskd is not longer a service (nor is JavaMonitor). It is a user application, with icons in the start bar. It will not start automatically upon boot, but it will start automatically upon login (of any user). However, logging out will kill wotaskd.

To kill wotaskd from the task manager, find the StartWOTaskD.exe process, and choose "End Process Tree". This will kill the java process associated with wotaskd.

To add launch parameters to wotaskd, simply edit the properties of the "start Task Daemon" shortcut in the Startup Items folder of the Start Menu (right click on the icon in the startup group and edit the Target command).
Workaround    None.
  
  

Examples

Reference2271407
ProblemNetscape does not send "en" language choice if any other languages are chosen.
DescriptionThe default language choice for Netscape is "en". If the user chooses any other language in addition to this, the "en" choice will not be included in the list of languages transmitted. Hence, some language other than english may be chosen.
Workaround    None
  
  

Documentation

Reference2659899
ProblemClicking a PDF documentation link in HelpViewer on Mac OS X doesn't work.
DescriptionHelpViewer doesn't handle links to PDF documents.
Workaround    Open the WebObjects documentation page in a web browser. The home page for the local documentation is
/Developer/Documentation/WebObjects/webobjects.html.
  
  
WebObjects Release Notes  Copyright 1998-2001 by Apple Computer, Inc. All Rights Reserved.