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.

login as an administrator
copy driver11.jar to C:/Apple/Library/Java/
Edit the file C:/Apple/Library/Java/JavaConfig.plist
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

Reference	2172805
Problem	Installing an upgrade will fail unless certain processes have been killed.
Description	The "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.


Reference	2250013
Problem	Incomplete uninstalls cause subsequent uninstalls to fail
Description	If 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.


Reference	2252905
Problem	Uninstalling from an account other than Administrator can result in some items not being removed
Description	If 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.


Reference	2425526
Problem	System paths longer than 255 characters can cause problems during installation on Windows.
Description	During 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.


Reference	2619370
Problem	WebObjects applications launch with the incorrect Java VM on Solaris and HP-UX.
Description	On 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.


Reference	2655315
Problem	Installing a new JVM after installing WebObjects may interfere with WOServices' startup scripts.
Description	During 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).


Reference	2677151
Problem	On Windows, WebObjects needs to know when you change the web server after you install WebObjects.
Description	WebObjects 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.


Reference	2680165
Problem	The WebObjects 5 Solaris uninstall.sh script may fail to uninstall WebObjects fully.
Description	WebObjects 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).


Reference	2682204
Problem	The WebObjects 5 installer fails on Mac OS X if you're not logged in to the root account.
Description	Contrary 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

Reference	2219521
Problem	My DirectAction raises when I trigger it
Description	I 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


Reference	2260519
Problem	WOApplication.application().port() returns a nonsensical result
Description	If 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();


Reference	2269517
Problem	Rapid turnaround doesn't seem to work for aggregates (Windows only).
Description	The 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 '("..")'


Reference	2273821
Problem	The session size numbers on the WOStats page appear to be too large.
Description	The 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.


Reference	2274039
Problem	IDs in Cookies are dropped at the front door of applications.
Description	When "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.


Reference	2276414
Problem	Sessions are not dealloced with WOAditionalAdaptors
Description	If you attempt to use the WOAdditionalAdaptors feature, sessions may not timeout.
Workaround	None.


Reference	2277580
Problem	WOApplicationWillFinishLaunchingNotification has been relocated
Description	If 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.


Reference	2279328
Problem	WOResourceManager may leak for dynamic resources if 'key' attribute is not used.
Description	If 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.


Reference	2282001
Problem	The current context and the current request aren't accessible from within a WOSession initializer
Description	WOSession'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; }


Reference	2290990
Problem	Standard error and warning messages aren't localized.
Description	When 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.


Reference	2304924
Problem	WebObjects is not thread safe with component caching disabled
Description	WebObjects 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.


Reference	2332399
Problem	Resources are not found on Microsoft Windows.
Description	On 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.


Reference	2343393
Problem	A WebObjects component, which worked in 4.0.1, reports an error with WebObjects 5.
Description	The 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.


Reference	2364124
Problem	Inner classes require special naming convention in the mapping coder
Description	Specifying 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


Reference	2366474
Problem	WOXMLDecoder raises an exception decoding a class with an inner class.
Description	Suppose 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.


Reference	2372492
Problem	Cookie expire header date format change
Description	In 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


Reference	2374907
Problem	The default error page doesn't appear after the application raises an exception.
Description	By 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


Reference	2375462
Problem	Display group queryOperator string queries behave differently from how they behaved in WebObjects releases prior to 4.5.
Description	In 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.


Reference	2378754
Problem	WOHyperlink documentation incorrectly indicates that the actionClass binding must be specified.
Description	The actionClass binding only needs to be specified if the directActionName binding is specified.
Workaround	None needed.


Reference	2393373
Problem	The XML Framework reference doesn't specify the behavior to expect when you use the unmappedTagsKey attribute in a mapping model entity.
Description	If 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.


Reference	2394732
Problem	The WODirectActionHandler now allows direct-connect requests when the application is refusing new session.
Description	In 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.


Reference	2396118
Problem	WOMessage string encoding constants are strings, not integers.
Description	In 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.


Reference	2399206
Problem	The XML decoder cannot decode NSData that contains characters outside of the range of XML-allowed characters (those less than \u0020).
Description	These characters will occur frequently when encoding or decoding NSData objects that represent images.
Workaround	None at this time. Avoid encoding or decoding images.


Reference	2408143
Problem	WOMessage's setUserInfo method makes a copy of its dictionary argument.
Description	WOMessage'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.


Reference	2418073
Problem	Applications shouldn't listen on port 1085
Description	Port 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).


Reference	2425444
Problem	When binding a date object to a WOTextField, you must also bind a formatter.
Description	If 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.


Reference	2428376
Problem	Formatters can alter values associated with WOTextFields.
Description	This 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.


Reference	2430661
Problem	XML Mappings needn't be unique for decoding, contrary to what the documentation says
Description	The 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.


Reference	2571405
Problem	The WOXMLDecoder throws a WOXMLException when you try to decode an object with a key that contains spaces.
Description	The 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.


Reference	2596955
Problem	WebObjects is not finding my projects.
Description	To 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.


Reference	2599994
Problem	WebObjects 5 does not provide utility classes to perform character set encoding conversion for strings or streams.
Description	Java 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.


Reference	2605569
Problem	WOApplication.setDebuggingEnabled has been removed from API.
Description	This functionality is now handled by NSLog.
Workaround	See the NSLog documentation.


Reference	2607502
Problem	Some dynamic elements are deprecated.
Description	WOQuicktime, 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


Reference	2608778
Problem	Cc'ed mail recipients appear in the To field as well as the cc field in messages sent using WOMailDelivery.
Description	The 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.


Reference	2661559
Problem	Project 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.
Description	For 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.


Reference	2678075
Problem	If 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.
Description	WebObjects 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

Reference	2369994
Problem	WOTable WebObjects Extension specification is missing the cellWidth and tableWidth bindings.
Description	The 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.


Reference	2395684
Problem	JSValidatedField WOExtensions component fails to check the validity of fields if the user does not tab through them.
Description	The 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.


Reference	2593451
Problem	Previously, WOKeyValueConditional has lacked the negate binding.
Description	In 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.


Reference	2635508
Problem	WOApplescript behaves incorrectly.
Description	The WOAppleScript component is deprecated. You should not use this component.
Workaround	None.

Direct to Web

Reference	2201189
Problem	DirectToWeb does not handle queries custom data types
Description	If 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.


Reference	2274611
Problem	DirectToWeb raises on custom or non-existent keys
Description	Either 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.


Reference	2424172
Problem	Direct to Web applications can hang.
Description	An 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);


Reference	2427535
Problem	The Direct to Web Assistant in Netscape 4.7 on Windows throws up an alert panel when I click Update.
Description	The 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.


Reference	2458195
Problem	Rules from d2w.d2wmodel files are merged into the user.d2wmodel file when saving
Description	DirectToWeb 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


Reference	2465051
Problem	If you edit the display of the WOLMasterDetailPage in the Web Assistant, it will not have any effect.
Description	The 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.


Reference	2477438
Problem	Shared entities do not appear in Direct to Web applications
Description	By 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.


Reference	2504035
Problem	In Direct to Web, some properties in a tab panel unexpectedly appear above the tabs.
Description	Using 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.


Reference	2507444
Problem	DirectToWeb does not find attributes in relationships that use inheritance
Description	Consider 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


Reference	2517806
Problem	Direct To Web's EditRelationship pages don't handle mandatory to-one relationships very well
Description	Direct 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.


Reference	2565612
Problem	Netscape 4.xx is slow to render an uncollapsed WORadioButtonMatrix component.
Description	For 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.


Reference	2628707
Problem	JavaConverter doesn't convert 4.5 DirectToWeb apps completely correctly.
Description	After 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.


Reference	2666929
Problem	Changing primary keys that are class properties causes an exception to be thrown. This was not a problem in previous releases.
Description	While 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.


Reference	2684724
Problem	D2WDisplayLargeString won't allow me to scroll over the data.
Description	When 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

Reference	2281716
Problem	Java Client applets can use the wrong session on the application server
Description	Web 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.


Reference	2370377
Problem	It isn't documented that locking operations aren't supported in the client side of a Java Client application are no-ops.
Description	Locking 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.


Reference	2397380
Problem	Java beans embedded in a Java Client application in 4.5 don't run out of a jar/zip file.
Description	The 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.


Reference	2688576
Problem	Projects containing Java Client interface files fail to compile correctly.
Description	When 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

Reference	2367086
Problem	Java Client windows do not become visible on Windows.
Description	There 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.


Reference	2481832
Problem	Reverting form windows in Direct to Java Client can leave windows unusable.
Description	This 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

Reference	2176526
Problem	Applying a qualifier with key path to top of horizontally mapped inheritance hierarchy generates invalid SQL.
Description	Enterprise 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.


Reference	2177181
Problem	Qualifying across a to-many relationship using the '"=" operator does not give the expected results.
Description	The "=" 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.


Reference	2177631
Problem	An EORelationship can return nil for its inverseRelationship after the inverse is added
Description	The 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.


Reference	2182008
Problem	An NSNumber primary key with a value of 0 is assumed to mean NULL, invoking EOF's primary key generation (perhaps erroneously).
Description	Starting 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; }


Reference	2280881
Problem	Concurrent multithreaded saves may bypass optimistic locking check
Description	Although 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.


Reference	2329635
Problem	EOF can generate incorrect SQL for disjunctions of qualifiers where one of the qualifiers involves an optional relationship.
Description	The 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.


Reference	2359723
Problem	The 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.
Description	EOF 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.


Reference	2417236
Problem	Using InvalidateAllObjects or InvalidateObjectsWithGlobalIDs directly on an object store coordinator or database context can cause deadlocking problems with shared editing contexts.
Description	When 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();


Reference	2431180
Problem	After calling myEODatabaseContext.invalidateAllObjects(), subsequent saves either fail to save changes or just raise.
Description	If 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())


Reference	2450687
Problem	EOF does not automatically generate special 12 byte primary keys.
Description	In 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
Problem	The application does not reflect changes in the model until the project is rebuilt.
Description	Currently, 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.


Reference	2577100
Problem	EOSQLQualifier does not behave correctly.
Description	EOSQLQualifier is deprecated. Do not use, subclass, or replace this class.
Workaround	Use EOQualifier in EOControl.


Reference	2604493
Problem	EOAdaptorChannel and EOAdaptorContext no longer have setDebugEnabled methods.
Description	These 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.


Reference	2663960
Problem	EnterpriseObjects in an "Owns Destination" relationship are not automatically inserted/deleted if the relationship is altered several times rapidly.
Description	Objects 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

Reference	2520093
Problem	Corrupted JDBC type information is not detected gracefully.
Description	The 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.


Reference	2526957
Problem	Trailing spaces are not always trimmed from CHAR attributes.
Description	A 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".


Reference	2562635
Problem	The JDBC adaptor does not support the use of Oracle REF CURSOR or custom types in stored procedures.
Description	The 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

Reference	2421581
Problem	The "cache-control: no-cache" http header causes Internet Explorer 5 to hang when using a proxy server.
Description	By 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.


Reference	2505603
Problem	Using %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.
Description	Due 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.


Reference	2662230
Problem	Projects created with the beta version of WebObjects 5 need to include the JavaXML framework to function properly
Description	After 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.


Reference	2668027
Problem	NSTimestamp returns values that are off by an hour after 2037 and before 1902.
Description	NSTimestamp 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


Reference	2679121
Problem	NSNumberFormatter cannot be both shared and changed in a multithreaded environment.
Description	NSNumberFormatter 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.


Reference	2685345
Problem	NSValidation and validation method semantics have changed.
Description	Developers 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.


Reference	2687367
Problem	NSTimestamp is not fully compatible with java.util.Date.
Description	The 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

Reference	2180253
Problem	WebObjects Builder does not validate keys and values in the bindings inspector
Description	WebObjects 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.


Reference	2256367
Problem	Configuration of WODisplayGroups in WebObjects Builder is not undoable.
Description	WebObjects 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.


Reference	2269932
Problem	Adding a subproject of type EOJavaClientSubproject does not add the EOJavaClient.framework to the project's frameworks.
Description	If 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.


Reference	2274651
Problem	In WebObjects Builder, opening a file for which you do not have read permission presents a blank document; no warning is generated
Description	Attempting 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.


Reference	2275826
Problem	EOPalette won't parse keys from the source code of client-side Java classes
Description	If 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.


Reference	2327908
Problem	Java Client applications need the Java Plugin from Sun.
Description	We 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.


Reference	2330551
Problem	WebObjects Builder deletes two keys when they are defined on the same line in the source file.
Description	If 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.


Reference	2370222
Problem	Opening a WebObjects 4.0 component can generate errors in WebObjects Builder.
Description	In 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.


Reference	2415737
Problem	Deploying WebObjects book images show a File Transfer button that doesn't appear in the final version of Monitor.
Description	Due 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.


Reference	2418323
Problem	Subprojects deeper than two levels do not render html in rapid turnaround mode
Description	In 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.


Reference	2425256
Problem	On Windows 2000, some of the fonts used by tools such as ProjectBuilder, FileMerge, WebObjectsBuilder are hard to read
Description	Windows 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.


Reference	2555382
Problem	Java Virtual Machine can't find classes in third party .jar files.
Description	If 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.


Reference	2644150
Problem	Compiled 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.
Description	This 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.


Reference	2650631
Problem	When 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.
Description	Interface 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).


Reference	2662018
Problem	A 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.
Description	An 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=/


Reference	2673052
Problem	WebObjects 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.
Description	Several 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.


Reference	2674710
Problem	Specifying the flavor of Sun JVM to use by adding the appropriate switch (-server, -client, -classic) as a launch argument does not work.
Description	The 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.


Reference	2675174
Problem	Deployment testing and configuration should include Java vm options.
Description	The 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.


Reference	2676249
Problem	A project imported from ProjectBuilderWO into Project Builder on Mac OS X looks or behaves differently from brand new projects created using Project Builder.
Description	There 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.


Reference	2677023
Problem	Launching 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.
Description	The 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.


Reference	2681948
Problem	If Project Builder crashes, rapid turnaround stops working.
Description	If 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

Reference	2173679
Problem	Can't run two WebObjects adaptors on the same machine with two different web servers.
Description	If 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.


Reference	2389605
Problem	Why does WebObjects use an HTTP success status code when a WebObjects app returns an error?
Description	When 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.


Reference	2420040
Problem	Security warning: asking Apache for a non-existent application can generate an application listing
Description	When 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.


Reference	2455171
Problem	WOHTTPConnections cannot be shared between worker threads.
Description	Due 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.


Reference	2670515
Problem	Adaptor uses default configuration if no wotaskd responding to multicast found
Description	If 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

Reference	2282569
Problem	Applications with dynamic images may leak them.
Description	If 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.


Reference	2340057
Problem	Requests to a WebObjects application cause stat calls in Netscape servers
Description	When 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.


Reference	2359284
Problem	"Disabling or Protecting Administrator Access" in "What's New in WebObjects 4.5" isn't quite correct for CGI.
Description	In 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.


Reference	2394552
Problem	wotaskd writes out a usable WOConfig.xml file.
Description	wotaskd 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.


Reference	2404574
Problem	Windows: wotaskd crashed and will not restart
Description	On 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.


Reference	2408559
Problem	Applications that launch from a terminal shell fail to launch under wotaskd.
Description	This 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.


Reference	2418131
Problem	It isn't always clear which port you need to connect to for Monitor and the WOInfoCenter.
Description	Much 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


Reference	2424573
Problem	A POST request to a WebObjects application via Apache 1.3 or later using the CGI adaptor results in null form values.
Description	The 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.


Reference	2424576
Problem	NSAPI adaptor fails to build on Windows
Description	On 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


Reference	2425106
Problem	WebObjects applications launched by wotaskd have logging redirected to /dev/null
Description	When 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).


Reference	2425742
Problem	Monitor's Path Wizard can be confused by the back button
Description	If 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.


Reference	2659527
Problem	Sessions don't time out according to the setting of the WOSessionTimeOut user default.
Description	The 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.


Reference	2665595
Problem	tcsh runs out of memory when executing WebObjects applications.
Description	This shell limits the stack size and data size of the applications that run within it.
Workaround	execute the unlimit command before executing the applications.


Reference	2673699
Problem	I need to know the command line arguments for WOServices.
Description	On 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

Reference	2676784
Problem	Strange behavior when running multiple webservers on a single host using Apache or CGI adaptors.
Description	For 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.


Reference	2678094
Problem	The Mac OS X Server WebServices Performance Cache actually lowers WebObjects performance.
Description	Mac 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.


Reference	2685595
Problem	wotaskd quits when I log out of Windows 2000.
Description	Because 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

Reference	2271407
Problem	Netscape does not send "en" language choice if any other languages are chosen.
Description	The 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

Reference	2659899
Problem	Clicking a PDF documentation link in HelpViewer on Mac OS X doesn't work.
Description	HelpViewer 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.