Wikibooks

WebObjects/Web Applications/Deployment/Windows

< WebObjects | Web Applications/Deployment

Overview

edit

(rev 1.3; 2002-08-29, see full revision list) The latest version of this document can be found at http://www.tetlabors.de/wo/setup_webobjects_on_windows.html.

edit

You can do with this how-to whatever you want but do it at your own risk. I WILL TAKE NO RESPONSIBILITIES WHATSOEVER. If you are not an expert in these things, I suggest setting up a new system just for test purposes first and then use your newly gained knowledge on a real world system.

Preface

edit

This how-to discusses installation of WebObjects 5.1 on Windows. It started as a email-help to install WebObjects 5.x on WinNT and has evolved since. It covers most gotchas for installation and configuration of both Development and Deployment of WebObjects 5.1 on the following versions of Windows:

  • Windows NT, both Workstation and Server
  • Windows 2000, both Professional or Server
  • Windows XP Professional

The main course of this how-to is directed to a development installation on Win2000 Server. Differences to other configurations will be described in short throughout the text. This still is much harder than Linux/WO Deployment, where you have exactly one configuration.

This how-to is not about deployment issues that occur after WebObjects is installed. It ends with a start of Monitor. There are, however, a lot of issues that can be solved be installing WebObjects in one of the right ways :-) , so you may read this how-to anyhow.

If you have found an error or want to make suggestions, improvements etc, you can contact me here.

Before you start

edit

To minimze delays, have the following things at hand:

If you plan to install on a new, empty machine, you additionally need:

  • Windows CD (either WinNT, Win2000 or WinXP)
  • Driver CDs or updated drivers from the internet (if you have to use special hardware)
  • Windows NT Option Pack CD (if you plan to install IIS on WinNT)
  • Windows 2000/XP CD (if you want to install the recovery console)
  • the latest service pack/rollup package and hotfixes for your version of Windows (too numerous to count, start search at http://www.microsoft.com/)

Throughout this how-to you will see the term 'open a shell' several times. This means you should go to the 'Start' menu, click on 'Run...', enter cmd and press the Return key. A new, empty window with a command prompt should open. Of course, if there is already an open shell, just use that instead...

Setup Windows and the web server

edit

This how-to follows the installation of Windows at the example of Windows 2000 server but should be usable for all versions of Windows mentioned above. If something is really different, there will be some short notes in the text. Installation is mostly self-explanatory, I will only mention the steps that require some caution.

If you plan to do real world deployment on Windows, forget about the non Server variants of Windows. Because of Windows license restrictions, the Workstation/Professional versions allow only 10 concurrent connections to the machine - files opened over network shares count as connections, too. Setting up a deployment will of course work but performance will be very bad, you should consider buying a Windows Server version or use Linux/Apache as the web server and deploy only applications on Windows.

First comes what I call the 'Basic Setup': insert Windows CD and boot. If you have boot diskettes, a network folder or whatever as source for the installation files, use that. On some OEM versions or with unattended setup, only some or no input will be required - just skip the appropriate sections then.

<nt4 server only> If setup asks for the role of the server, select 'Single-Server'. Don't select one of the 'Domain Controller' roles, unless you know what you are doing. During network setup, you can choose to install Internet Information Server (IIS). Don't do this, because it is an outdated version. Be sure to _uncheck_ that checkbox! Don't use DHCP! See 'Network settings' below for an explanation. </nt4 server only>

Install only World Wide Web Server, Internet Information Services Snap-In and all required files. Don't install FTP, NNTP, SMTP unless you really need it. If not configured correctly, these services provide execellent hooks for an attacker.

If you have more than operating system installed, disable daylight saving for all but the first one or you will have much fun twice a year...

Choose custom network settings and enter IP/address, subnet mask, gateway and DNS server settings. Using DHCP on servers is not recommended because some services rely on a permanent IP address. If you have to use DHCP (it's a cool service, after all), configure the DHCP server so that your WebObjects machines always get the same address (address reservation, IP-to-MAC address mapping).

To be able to view other computers around, the WORKGROUP name entered must match the workgroup name of the other systems. If you do a domain based setup, there are no problems, just add the machine to your domain.

Win2000/XP has the embarrassing habit of releasing a network adaptor's configuration when it has no connection to the network. So always make sure the network cable is connected to an active station (other machine or hub/switch) before starting any services, especially while booting. If this is not the case, some services will run on localhost (127.0.0.1) and you will experience weird errors when you try to connect.

<win2000 server only> When you first log in to Windows, you will see the 'Configure Your Server' dialog. Unless you know what you are doing I suggest you choose 'I will configure this server later.' and click 'Next'. On the next page, uncheck 'Show this screen at startup' and close the dialog window. If you want, you can come back later via 'Start, Programs, Administrative Tools, Configure Your Server'. </win2000 server only>

After basic Windows Setup

edit

If you have to install additional drivers (e.g. graphics card) do so now. Otherwise, you are done with basic Windows setup. Here are some things you might want to do now:

Single-CPU support
edit

If you have a multiprocessor system, you should be able to start Windows with only one processor enabled (Single CPU HAL), This can be incredibly helpful if you run into hardware issues later and have to do an emergency boot on a motherboard that supports only one CPU. Also, some applications don't run on multiprocessor systems. To get single CPU support, add a new entry to c:\boot.ini with a '/onecpu' switch at the end. Don't copy-and-paste from this how-to, as disk and partition numbers may vary for your installation, just duplicate the entry that is already there. 

 [operating systems]
 multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows 2000 Server" /fastdetect
 multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows 2000 Server (one CPU)" /fastdetect /onecpu

You might have to remove write protection from c:\boot.ini to be able to add entries. Open a shell and enter this command: 

 attrib -r -s c:\boot.ini

There is no need to add write protection afterwards.

Recovery console
edit

Another helpful tool is the Windows recovery console, especially when Windows crashes during startup (bluescreens, bad drivers, bad config, cannot boot after adding a new hard disk etc.). The Win2000 version of the recovery console can be used on all versions of Windows while the WinXP version cannot be used on a machine that runs WinNT only. To add it, insert your Windows2000/XP CD, open a shell and enter the following: 

 cd /d <cdrom>:\i386
 winnt32 /cmdcons

A new entry is added to c:\boot.ini that can be choosen from the list of installed operating systems.

Install Windows Service Pack
edit

As of the time of this writing, no service pack is available for WinXP. Install hotfixes as needed. For Win2000, install service pack 2 and all hotfixes needed. For NT4, install service pack 6, and then the past-sp6 rollup package. This should give you 128 bit encryption strength.

Install IIS on WinNT from the Windows Option Pack CD

edit

Insert the Windows NT Option Pack CD and install Internet Explorer 4.01 (or a newer version).

After this is done:

Launch <cdrom>:\setup.exe

Setup warns that the option pack was not tested with service packs newer than SP4. Click 'Yes' to proceed anyway.

Choose 'Custom' as the installation type.

On the next window, uncheck _all_ components, answering 'Yes' to possible warnings.

Then go to 'Internet Information Server (IIS)' and click on 'Show Subcomponents...'

Move to the end of the new selection list and check 'World Wide Web Server'. You might want to check 'Documentation' (at the beginning of the list). All dependent software components are selected automatically.

To avoid security issues, don't install the following unless you need it and know what you are doing:

  • FTP, SMTP, NNTP servers
  • Index Server
  • FrontPage 98 Server Extensions
  • Certificate Server
  • Microsoft Script Debugger
  • Windows Scripting Host

If setup asks you to specify to specify a folder for the WWW service, you can use the suggestion 'c:\inetpub\wwwroot'.

For Microsoft Transaction Server, just click 'Next' twice. Option Pack Setup should eventually complete. After that, you may have to re-install all service packs/updates for WinNT as some files may have been overwritten by Option Pack Setup.

Securing the Windows/IIS installation

edit

Running NT / IIS out of the box is quite dangerous, so I suggest you take one of security how-to's that are available in this area. A secure IIS installation is not needed for simple in-house testing but it should be considered harakiri if you connect an unprotected machine to the Internet. You have been warned. Here are some links that might help: www.microsoft.com/security/ (then dive in from there) http://www.intersectalliance.com/projects/WinNTConfig/index.html (securing WinNT) http://www.intersectalliance.com/projects/Win2kConfig/index.html (securing Win2000) http://www.shebeen.com/iis4_nt4sec.htm (securing IIS on NT) http://www.intersectalliance.com/projects/IIS4Config/index.html (securing IIS) For more information, look for 'hardening+iis+against+attack' at Google.

Prepare Windows for WebObjects installation

edit

Now that you have a running Windows box - hopefully secure :), we can prepare it for WebObjects installation. The stuff in this section works for both WebObjects 5.0 and 5.1.

Uninstall a previous version of WebObjects

edit

In case you are using an existing machine with an older version of WebObjects, you have to uninstall it before installing WebObjects 5.1. On the WebObjects 4.5 CD, under <cdrom>:\development\Windows\Uninstall you will find several directories:

  • UninstallWO3.51
  • UninstallWO4.0
  • UninstallWO4.5

Use the appropriate one for your version. To uninstall WebObjects 5.0, use 'Start, Control panel, Add/Remove Programs'.

Replacing the shell

edit

The shell built in to WinNT does not work with WebObjects at all. For the Win2000 version, there are some issues if the command line gets longer than 2000 characters due to heavy use of frameworks. Because of this, you will have to replace the shell. The good news is that you can use each version of CMD.EXE on every version of Windows, so the basic idea is to get a CMD.EXE from a WinXP installation and use it to replace your default shell - unless you run WinXP :).

If you do not have a Win2000/XP CD, you can at least download Win2000 Service Pack 2 (or Windows XP service pack 1 as it becomes available) and extract CMD.EXE from there. There should be no legal issues since you can download service packs freely.

Before attempting to replace the shell, be sure to cut access to the installation files or Windows File Protection will restore the old version within a few seconds. In case you installed from a CD, remove the Windows installation CD. If you installed over a network, unplug the network cable before starting the replacement. Windows File Protection does not exist on WinNT, you don't have to worry there.

Within the additional files package (download it here), there is a script that does the replacement for you. Feel free to get your own version of CMD.EXE if you don't feel comfortable with the supplied one.

  • Close all open shell windows, as CMD.EXE cannot be replaced if it is running.
  • Double-click on CMD.EXE that came with the script; this opens a new (local) shell that can be used to replace the default shell.
  • In the open window, enter: shellReplace
  • The script will backup the original version of CMD.EXE to CMD.EXE.ORIGINAL and then replace it with the new version. A second later, Windows File Protection will open a dialog, requiring you to insert the Windows installation CD. Press 'Cancel' here and answer 'Yes' in the next windows that pops up.

Now close the shell and open a new one, via 'Start, Run..., enter cmd and press Return'. Look what it says on the first line:

With the original versions, the first line in a shell should look like this:

  • WinNT: Microsoft(R) Windows NT(TM)
  • Win2000: Microsoft Windows 2000 [Version 5.00.2195]
  • WinXP: Microsoft Windows XP [Version 5.1.2600]

When you get this instead: Microsoft Windows XP [Version 4.0.1381] it means that you actually run CMD.EXE from WinXP on a WinNT 4.0 installation (4.0.1381). Other possible combinations are left as an excercise to the reader.  :-)it is the good is great and all of slove

Set up Dr. Watson

edit

Now you should change the configuration of Dr.Watson, Windows' integrated crash logger and debugger, so it runs without user interaction. Open a shell and enter: 

 drwtsn32 -i

This installs Dr. Watson as the default application debugger, which can be useful if you have installed Visual Studio Debugger and this beast shows its ugly head after each application crash.

After this, enter: 

 drwtsn32

and a dialog window pops up. Here you should use the following settings:

Enable (check):

  • 'Dump Symbol Table'
  • 'Dump All Thread Contexts'
  • 'Append To Existing Log File'

Disable (uncheck):

  • 'Create Crash Dump File'
  • 'Visual Notification'
  • 'Sound Notification'

These settings instruct Dr. Watson to collect as much information as possible and to finish without user interaction. Otherwise, a crashed application will not terminate until the user clicks 'OK'.

  • 'Number of Instructions': 20
  • 'Number of Errors To Save': 50

This saves the last 50 errors with the last 20 instructions for each error.

  • 'Log File Path': Set this to something short and easy to remember. Maybe you already have a folder for log files; I always use the TEMP folder for this.

SDK installation

edit

Next thing is to install a Java-SDK. The version of the SDK must be greater or equal to 1.3.1, SDK 1.3.0 will not work. Also, you have to install a SDK, installing only a runtime environment (JRE) will not work.

I would suggest using SDK 1.4.0 or higher unless you experience problems with it (someone mentioned issues with Timestamp's) . Especially on multiprocessor systems, 1.4.0's concurrent garbage collection is a big plus. If you do cross-platform development (OSX/Windows) be sure to download the full international SDK from Sun (the biggest package), as only this version contains all the font encodings from the Mac. Else, you will get exceptions stating that NSMacOSRomanStringEncoding could not be found.

Run the SDK installer.

Use the path suggested (i.e. c:\j2sdk1.4.0).

You can deselect 'sources' and 'examples', they are not needed for WO deployment. Install the Java plugin if you need it.

After SDK setup has finished, open a shell and enter: 

 java -version

You should see an output like this: 

 java version "1.4.0"
 Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
 Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)

Good job! You are now ready to install WebObjects.

Install WebObjects

edit

With everything set up and running properly, you can now install WebObjects. Be sure to log in as user with Administrator privileges. This section also works for both WebObjects 5.0 and 5.1.

Copy CD contents to local hard disk

edit

Create a new folder on your hard disk and copy the contents of the WebObjects installation CD there. Don't use a shared folder on the network, as Setup needs to restart when it is half way done and fails if it cannot find the contents of the CD; bad karma arises and you will be left with an unusable WO installation ... an empty folder like c:\cdrom would be just fine.

Choose the right version of NMServer.reg

edit

The supporting files package contains several versions of NMServer.reg. Choose the one you need:

  • NMServer.reg.deployment - use for all version of Windows if you install WO deployment (the original one has a bug)
  • NMServer.reg.nt4-devel - use for WO development on NT4 (the original one only runs on Win2000/XP)
  • NMServer.reg.win2k-devel - use for WO development on Win2000/XP (the one included with WO by default)

Rename the appropriate file to NMServer.reg and copy it to

  • c:\cdrom\Deployment\Windows\Install\NMServer.reg (for deployment) or
  • c:\cdrom\Developer\Windows\Install\NMServer.reg (for development).

Depending on the type of setup, run

  • for Development install: c:\cdrom\Developer\Windows\Setup.exe
  • for Deployment install: c:\cdrom\Deployment\Windows\Setup.exe

To complete all steps in this how-to (like compiling the adaptor), development setup is necessary. As someone put it nicely:

Development = Deployment + Developer Tools

If you want to install Deployment only, just skip the steps you don't need. Notice that you will not be able to compile the ISAPI adaptor (which has an ugly bug) if you install Deployment only. Be sure to set up a Development installation (maybe on another machine), too.

Accept the license agreement.

Enter User Name, Company Name and the appropriate serial number for your setup (development, in this case).

No JRE found during setup

edit

I have seen this only on WinNT but it may happen on other versions as well: Although you have installed Java2-SDK 1.4.0, Setup complains that there is no JRE and that you should install Sun Java 1.3 or greater. In this case, quit Setup and import the file jresettings.reg from the supporting files package (just double-click it). You may have to open it first with a text editor (notepad would be fine) and change the path settings in there. By default, it points to c:\j2skd1.4.0. If you have installed the SDK there, no changes to jresettings.reg are necessary.

Choose 'Custom Setup'.

Select C:\Apple as the destination folder. You may specify another drive letter but don't put the Apple folder anywhere else but into the root folder. Great frustration with long paths will manifest itself if you do. Also, under no circumstances put spaces in the path!

On the 'Select Components' don't change anything; simply click 'Next'.

<winnt only> After this dialog, an 'ComponentAddItemError' dialog box may pop up. Simply click 'Ok' there and select 'Other' from the web server list; then click 'Next'. </winnt only>

'CGI-BIN Directory': Specify the path to the IIS scripts folder, which is typically located at c:\inetpub\scripts. You can use the 'Browse...' button to avoid typos.

'Document Root Directory': The path to the IIS wwwroot folder, typically c:\inetpub\wwwroot.

Click 'Next' on all further dialog windows. Setup should start copying all files needed to the right locations. Then it asks you to reboot. Do so and log in again using the same user name as before. Setup will continue with the installation and eventually finish. Don't interrupt it before, this will render the installation useless!

After setup has finished, install the latest update for your version of WebObjects. Reboot when asked to do so.

Congratulations! WO Setup is complete.

Post WebObjects installation steps

edit

Having all the WebObjects files on you disk does not mean sunshine immediately. Here comes what I call the 'post WebObjects setup'.

WebObjects base installation

edit

Open 'Services':

  • on WinNT: 'Start, Control Panel, Services'
  • on Win2000/XP: Open a shell and enter:

%systemroot%\system32\services.msc /s You will find the following WebObjects related services. The name of the service is written into brackets - you can use that name to start/stop these services from the command line.

These two are installed in both Development and Deployment:

  • Apple WebObjects Task Daemon 5 (wotaskd5)

This service manages all running application instances. It should be set to run automatically at startup on both Development and Deployment.

  • Apple WebObjects Monitor 5 (womonitor5)

This service provides a user interface to create new and manage existing application instances, sort of a frontend to wotaskd. It is not needed to start and manage application instances and should (for security reasons) be set to run manually. To start it, open a shell and enter: 

 net start womonitor5

After the time it takes to start (usually only some seconds), you can open a browser and point to http://<myhost>:56789 to see the first page. To improve security, go to the 'Preferences' tab and set a password for accessing Monitor. Then use it like you normally would. To stop it after use, enter: 

 net stop womonitor5

In WebObjects 5.0, wotaskd and Monitor are not installed as services by default. To change this, you will need the instsrv and srvany tools from the supporting files package. Here comes a quick step-by-step guide to install wotaskd and Monitor as services, for more information see srvany.doc that comes with srvany.exe

  • Right-click on the Start menu button and choose 'Explore all users'. In the Explorer window that opens, go to 'Programs, Startup'.

Move the 'Start Task Daemon' shortcut out of the Startup folder to stop wotaskd from starting when you log in. I always put it into the 'WebObjects' folder but you can delete it as well.

  • Copy srvany.exe to an easy to remember place like C:\Apple (or C:\WinNT).

Open a shell and enter instsrv wotaskd c:\apple\srvany.exe

  • Open RegEdit and go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\wotaskd

Change the DisplayName property to 'Apple WebObjects Task Daemon' Change the Start property to '2' if it is not already 2. This means that the service should start automatically.

  • Under the wotaskd key, add a new subkey and name it Parameters.

Under this subkey, create a new Application property (type string) with the following value: C:\Apple\Library\WebObjects\JavaApplications\wotaskd.woa\StartWOTaskD.exe Do not use %NEXT_ROOT% here - this may not yet be available when the service is about to be started resulting in a failure. Use the absolute path name to your WebObjects root folder instead.

  • Create a second string value property, AppDirectory, with the following value C:\Apple\Library\WebObjects\JavaApplications\wotaskd.woa
  • Reboot your system

After reboot, you should be able to view http://<myhost>:1085 from another machine without logging in to the Windows box. If this works you have done everything correctly.

If you want to install Monitor as a service, too, do the following.

  • Open a shell and enter: instsrv womonitor c:\apple\srvany.exe
  • Open RegEdit and go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\womonitor

Change DisplayName to 'Apple WebObjects Monitor' Change Start to '3' which means 'manual startup'. If you do not have to care about security, you can set it to '2' (automatic startup).

  • Under the womonitor key, add a new subkey and name it Parameters.

Under this subkey, create a new Application property (type string) with the following value: C:\Apple\Library\WebObjects\JavaApplications\JavaMonitor.woa\JavaMonitor.cmd

  • Create a second string property, AppDirectory, with the following value

C:\Apple\Library\WebObjects\JavaApplications\JavaMonitor.woa

  • To start Monitor on port 56789 every time, add a third string property, AppParameters, with the following value
 -WOPort 56789

You can specify more command line arguments here if you like. Now, try to start Monitor. Open a shell and enter net start womonitor After a few seconds, open your browser and go to http://<myhost>:56789. You should see Monitor's starting page.

If you have WO Development installed, there are some more services

edit
  • Apple Mach Daemon (Apple_Mach_Daemon) and Apple Netname Server (Apple_Netname_Server)

These two services - together with Pasteboard Server and Window Server - provide the base to run YellowBox applications (most of the WebObjects Developer Tools) on Windows. You don't have to care about them, just set them to start automatically.

  • openexec (openexec):

This service starts the Openbase database engine and provides several sample databases. If you don't want to use OpenBase, you can save memory by setting the startup type to 'Manual' which prevents this service from starting automatically. To get rid of the Openbase processes that are running at the moment, you can either reboot or kill all relevant processes using the 'kill' tool (included in the supporting files package). Open a shell and enter: 

 kill OpenBase.exe
 
 kill pgroup.exe
 
 kill databackup.exe
 
 kill openinfo.exe

Important notice for all services

edit

Never set the startup type of an entry to 'Disabled' unless you are dead sure what you are doing! 'Manual' services can be started from the system as needed while 'disabled' services cannot be started at all (unless you select a different startup type). Disabling the wrong services may prevent the system from booting and is not considered to be a good idea.

Besides all those services, for a Development installation there are two shortcuts with the following settings in the 'All Users' Startup folder:

  • Pasteboard Server
       Target: %NEXT_ROOT%\Library\Frameworks\AppKit.framework\Resources\pbs.exe
       Start in: %NEXT_ROOT%\Library\Frameworks\AppKit.framework\Resources
       Run: Minimized
  • Window Server
       Target: %NEXT_ROOT%\Library\System\WindowServer.exe
       Start in: %NEXT_ROOT%\Library\System
       Run: Minimized

WinXP Fast User Switching

edit

'Pasteboard Server' and 'Window Server' are started everytime a new user logs on. With Fast User Switching, more than one user can be logged in at the same time, causing Pasteboard Server and Window Server to be started more than once. Both programs don't like it and stop working which in turn causes the developer tools (ProjectBuilder, EOModeler, WOBuilder) to stop working, too.  ;-(

Workaround: If only one user on the machine is developing with WebObjects, move the shortcuts for Pasteboard Server and Window Server from the 'All Users' Startup folder to the personal Startup folder of the áppropriate user. If more than one user on the machine is developing with WebObjects, make sure they are not logged in at the same time. If nothing else helps, you can disable Fast User Switching.

WebObjects Update program

edit

There are at least two bugs when installing WebObjects Updates:

  • Files that you have changed yourself are not updated, the updater just silently skips them. Because of this, if you want to be sure that a given file is updated, rename it - for example, to <filename.extension.OLD> - and then run the update again.
  • Everytime the update is run, the WebObjects relevant folders are added to the PATH variable. Depending on how often updates are installed, this can result in an extremely long path. After the update has finished, clean the PATH variable manually.

Changes to environment variables

edit

Open 'System' in Control Panel. On the 'Advanced' tab, click 'Environment Variables', then click the name of the user variable or system variable you want to change, as follows: Click New/Edit/Delete to add/change/remove a new variable name and value. You may have to close and reopen running programs for the new settings to take effect. To update all running services with the new values, it may be easier (and less error prone) if you just reboot the machine once more.

The following environment variables should exist after WO setup:

  • LIB:

one contains the path to several libraries used be the WebObjects developer tools and should point to C:\Apple\Developer\Libraries. You usually don't have to change anything here, it is just mentioned for completeness.

  • NEXT_ROOT:

New: Don't change the slash in NEXT_ROOT into a backslash! Just leave it as it is. The compilation of the adaptor sources will fail, if you do this. It's all my fault, that I suggested otherwise in a previous version.

  • PATH:

The following three entries are the only ones needed by WebObjects but they are usually duplicated by running the WebObjects Update. This does not harm except that it makes the PATH variable unnecessary long. Be sure to include the following only once (this assumes that you have installed WebObjects to C:\Apple): C:\Apple\Library\Executables; C:\Apple\Library\JDK\bin; C:\Apple\bin;

  • TEMP:

For the user accounts used to develop and run WebObjects applications, remove both TMP and TEMP from the user variables section and add them to the all users section. Change TEMP and TMP to a path without spaces, like c:\temp. You may have to create c:\temp if it does not exist yet. IMHO, that makes finding launch script zombies, log files and other WebObjects temporary stuff much easier.

To clean the zombies, you alternatively can use any application you have written and start it in a shell with the 'clean' parameter: 

 cd myapp.woa
 
 myapp.cmd clean
  • WEBOBJECTS_JAVA_EXTENSIONS

This contains the path to the extensions folder for additional JAR files. A typical path is C:/PROGRA~1/Java/J2RE14~1.0/lib/ext. Be sure not to put spaces in here, either move your JRE to another folder or use short names (8dot3 notation like old MSDOS).

  • WEBOBJECTS_JAVA_HOME

This specifies the path to the SDK used by WebObjects applications you write. A typical path is C:/J2SDK1~1.0. Also like above, don't use spaces in the path name.

As opposed to the SDK you specify here, the WebObjects developer tools always use JDK 1.1.8 in %NEXT_ROOT%\Library\JDK - you don't have to care about that.

Upgrade the license

edit

If you have installed WebObjects Development but want to fully use its Deployment capabilities (like multiple instances, unlimited requests etc.) you have to upgrade your license to the Deployment version. There are two ways to do this. First one is to use the License Upgrader. Open a shell and enter: 

 %NEXT_ROOT%\Demos\JavaWebObjectsLicenseUpgrader.app\JavaWebObjectsLicenseUpgrader.exe

Alternatively, you can open it via 'Start, Programs, WebObjects, WebObjects 5 License Upgrader'. The second way (if the License Upgrader does not start) is to edit the key file with a text editor (Notepad would be okay). Just start the editor and open 

 %NEXT_ROOT%\Library\Frameworks\JavaWebObjects.framework\Resources\License.key

Delete the old license key and insert the new one.

You have to restart wotaskd and (if it is running) Monitor for the changes to take effect: 

 net stop wotaskd5
 
 net stop womonitor5
 
 net start wotaskd5
 
 net start womonitor5

Mess around with the adaptor

edit

There is a ugly bug in the IIS adaptor that extremely degrades performance when it is put under heavy load. You will reach about 3 to 5 requests per second and memory will be eaten at extreme speed, resulting in OutOfMemoryExceptions after just a few sessions have been created. This happens whenever you use the ISAPI adaptor, even when your applications run on another machine with a different OS.

Luckily, Karl Hsu found a fix to this which I am extremely grateful for. Thanks Karl! Karl states that you should incorporate this fix only if you are seeing massive performance problems, so do some test before patching. The Apache Benchmark tool ab (included in support files package) can be used for this.

Both files, request.h and request.c can be found at %NEXT_ROOT%\Developer\Examples\WebObjects\Source\Adaptors\Adaptor

Patched versions of request.h and request.c that include the code below are also included in the support files package. If you did not make changes to these two files yourself, you can copy them to %NEXT_ROOT%\Developer\Examples\WebObjects\Source\Adaptors\Adaptor and start compiling right away.

Else, in request.h, search for #include "WOURLCUtilities.h" and add the following line right below: 

 #include "wastring.h"

In request.c, search for the beginning of the method 'int req_sendRequest' (around line 217) and add the following code block _before_: 

 #ifdef WIN32
 static void req_appendHeader(const char *key, const char *val, String *headers)
 {
 int valLength = strlen(val);
 while (val[valLength - 1] == '\r' || val[valLength - 1] == '\n') {
 valLength--;
 }
 str_append(headers, key);
 str_appendLiteral(headers, ": ");
 str_appendLength(headers, val, valLength);
 str_appendLiteral(headers, "\r\n");
 }
 
 int req_sendRequest(HTTPRequest *req, net_fd socket)
 {
 struct iovec *buffers;
 int bufferCount, result;
 String *headersString;
 
 buffers = WOMALLOC(3 * sizeof(struct iovec));
 
 headersString = str_create(req->request_str, 0);
 if (headersString) {
   st_perform(req->headers, (st_perform_callback)req_appendHeader, headersString);
 }
 buffers[0].iov_base = headersString->text;
 buffers[0].iov_len = headersString->length;
 buffers[1].iov_base = "\r\n";
 buffers[1].iov_len = 2;
 bufferCount = 2;
 if (req->content_length > 0)
 {
 bufferCount++;
 buffers[2].iov_base = req->content;
 buffers[2].iov_len = req->content_length;
 }
 result = transport->sendBuffers(socket, buffers, bufferCount);
 str_free(headersString);
 WOFREE(buffers);
 if (result == 0)
 result = transport->flush_connection(socket);
 else
 WOLog(WO_ERR, "error sending request");
 
 return result;
 }
 #else

Now, right after this #else comes the original req_sendRequest method. Go to the end of this method and insert a #endif in the next line. When you have successfully patched the source file, it is time to...

Compile the adaptor

edit

Next bug: The makefile expects the OS environment variable to be either empty or contain the string 'WINDOWS'. Unfortunately, the value of OS is WINDOWS_NT instead of WINDOWS so the make process will fail to compile the ISAPI adaptor. You could change the makefile so it works with WINDOWS_NT but you will have to do _a lot_ of changing then.

Instead, let's just change the OS variable. However, don't change this permanently via control panel, as I do not know if it is needed elsewhere. Just setting it to the proper value before compile is enough. Open a shell and enter: 

 cd /d %NEXT_ROOT%\Developer\Examples\WebObjects\Source\Adaptors
 
 set OS=WINDOWS
 
 make clean
 
 make

If compilation was successful (no error messages), we now should have the WebObjects adaptor as EXE (CGI) and DLL (ISAPI) file. These two should be copied to the proper location (change c:\inetpub to match your system). 

 net stop w3svc
 
 copy /y cgi\webobjects.exe c:\inetpub\scripts
 
 copy /y iis\webobjects.dll c:\inetpub\scripts
 
 net start w3svc

Stopping IIS before copying prevents possible sharing violations for the ISAPI adaptor as you cannot overwrite the file if it has already been loaded by IIS.

ISAPI Adaptor configuration settings

edit

Now that you have compiled the ISAPI adaptor, you have to configure it. For a single server deployment (IIS and wotaskd on the same machine), no further configuration is necessary. However, if you have wotaskd running on another machine, or want to use more than one application server, you have to tell the adaptor where to look for them. The way that always worked for me is via host list in the registry.

Open Regedit (open a shell and enter regedit) and go to: 

 HKEY_LOCAL_MACHINE\SOFTWARE\Apple\WebObjects\

If it does not exist yet, create a new subkey and name it 'Configuration'. Then go to: 

 HKEY_LOCAL_MACHINE\SOFTWARE\Apple\WebObjects\Configuration

and add the following two keys (type REG_SZ): 

 CONF_INTERVAL 10

This means that every 10 seconds, the ISAPI adaptor will talk to the wotaskd's and re-read the configuration. 

 CONF_URL http://host1:1085,http://host2:1085,http://host3:1085

This is a comma-separated list of all hosts, on which a wotaskd is running. 1085 is the default port. Just add all application servers and be sure not to put spaces after the commata - WO does not like spaces. If you have fixed IP-addresses, you can specify them, otherwise use hostnames and make sure the IIS machine can resolve hostnames to valid addresses. This should be no problem if all machines run Windows, otherwise you have to use a DNS server or a host file.

Testing the installation

edit

Now that everything should be set up properly, it is time for a small test. First, let's look if wotaskd is working.

Open a browser and go to http://<myhost>:1085 

If it works, you should see the host's configuration displayed in the browser. Now, open a shell and start Monitor if it is not already running:
 net start womonitor5

Wait a few seconds, then point the browser to http://<myhost>:56789

You should see Monitor's main window. Now you can start writing and deploying applications. Have fun!

Troubleshooting

edit

Q: I keep getting the following exception when running the WO applications: 

java.io.UnsupportedEncodingException: NSMacOSRomanStringEncoding

A: Make sure the charsets.jar library is in your Java runtime path. This is installed in the JDK but not always in the JRE.

Revision list

edit

1.3: 2002-08-29 - removed suggestion to change the slash in NEXT_ROOT into a backslash, because this breaks compilation of the adaptor sources

1.2: 2002-07-26 - added steps to install wotaskd and Monitor as services in WebObjects 5.0

1.1: 2002-07-10 - added two workarounds for errors during WebObjects setup on WinNT

1.0: 2002-07-09 - first public release

0.9: 2002-06-28 - work in progress

Retrieved from "https://en.wikibooks.org/w/index.php?title=WebObjects/Web_Applications/Deployment/Windows&oldid=4308224"