Apple WebObjects Serving Service Manual

Serving WebObjects

To a large extent, WebObjects needs little attention once it is installed.
However, there are certain basic administrative tasks that you’ll need to
know, such as how to install applications and start them up. In addition,
you’ll probably be concerned about your site’s performance somewhere
along the line, and you’ll need to know how to determine an application’s
response times and what you can do to improve the response times.

This document contains information that a WebObjects system
administrator needs to know. It begins by providing essential background
information on WebObjects HTTP adaptors and how they are used to start
WebObjects applications. Then it describes how to perform one-time setup
of an application called Monitor, which you use to perform many of the
necessary administrative tasks. After you read these first two sections, you
can learn what the basic administrative tasks are and how to perform them.

Table of Contents

WebObjects HTTP Adaptors

Configuration Files
Adaptor Modes
Installed HTTP Adaptors

Setting Up the Monitor Application

Starting Up Monitor
Initial Monitor Setup

Administrative Tasks

Installing Applications
Starting WebObjects Applications
Monitoring Application Activity
Performance Testing
Improving Performance
Periodically Shutting Down the Application
Load Balancing
Increasing the Listen Queue Depth
Installing and Configuring NSAPI Adaptors
Installing and Configuring the ISAPI Adaptor
Starting Up Multiple Monitor Instances

Related T opics

Other WebObjects documents might be of interest to system
administrators:

• Installation Guide: Includes system requirements, compatibility
information, and location of the WebObjects Home Page. (The

3

Serving WebObjects

Installation Guide is printed and included with the WebObjects CD-ROM or
can be downloaded from NeXTanswers; it is not online).

• Post-Installation Instructions: Describes how to verify the installation and
troubleshoot if WebObjects applications do not run.

WebObjects HTTP Adaptors

A key part of WebObjects administration is dealing with adaptors. This section
provides a little background material on what a WebObjects HTTP adaptor is,
how it works, and how you can configure it to suit your needs.

A WebObjects HTTP adaptor (called

) routes client requests processed by an HTTP server to WebObjects

adaptor

WebObjects adaptor or sometimes HTTP

applications and returns the response to the server, which sends it back to the
client. WebObjects makes available several adaptors, of which only one can be
active with a particular server at a time. Every transaction with a WebObjects
application uses the currently active adaptor.

However, the relationships between adaptor and application are (potentially)
many-to-many. Multiple instances of the same WebObjects application can run
on the same machine or a variety of machines and communicate with the same
adaptor. In addition, multiple HTTP servers can be running on the same
machine or on different machines; each server can have its own adaptor, each
with its own constellation of application instances. Although there can be only
one active HTTP adaptor per HTTP server, an application can concurrently
communicate with other types of adaptors, such as an adaptor that uses
Distributed Objects or a secure-socket adaptor.

There are two general types of HTTP adaptors:

• The CGI adaptor, an executable file named

WebObjects

or

WebObjects.exe

which
resides in the host HTTP server's “cgi-bin” directory. This adaptor is
available on all supported platforms. It is generic in that it works with any
HTTP server conforming to the Common Gateway Interface (CGI).

• API-based adaptors, that is, adaptors based on APIs specific to particular
web server. Three NSAPI adaptors, all based on the Netscape Server API
(2.0, 2.0.1, and 3.0), are available on all supported platforms except Mach. A
WebObjects adaptor based on Microsoft’s Internet Information Server API
(ISAPI) is also supported. The API-based adaptors have a performance
advantage over CGI adaptors in that the associated server can dynamically

4

WebObjects HTTP Adaptors

load the adaptor; servers using CGI adaptors, on the other hand, spawn
a new adaptor process for each request and kill the process after the
response is provided.

When WebObjects is installed, the CGI adaptor is made active by default.
To use an API-based adaptor, you must specifically activate it. Activating
the API-based adaptor deactivates the CGI adaptor for a particular server.
See “Installing and Configuring NSAPI Adaptors” and “Installing and
Configuring the ISAPI Adaptor” for further details.

Configuration Files

WebObjects HTTP adaptors use configuration files to locate WebObjects
application processes. There are two types of configuration files: public and
private.

• The

public configuration file is

NeXT_ROOT

/NextLibrary/WOAdaptors/Configuration/WebObjects.conf

. (NeXT_ROOT

is defined at system installation time.) This file tells the adaptor what
applications are (or should be) running and allows the adaptor to
balance transactions among different instances of the same application.
You create the public configuration file using the Monitor application as
described in the section “Initial Monitor Setup” in this guide.

In general, you want one public configuration file per site. That means
if you have multiple machines running WebObjects, you should access
all WebObjects applications through a single machine that is running
the HTTP server and that contains the public configuration file.

If you have multiple HTTP servers running on a single machine, they
all share the public configuration file. If you want each server to have
its own configuration file, you can install one

WebObjects.conf

file in each

server’s configuration directory.

•A private configuration file is also named

the temporary directory of the system (

WebObjects.conf

for Mach, Solaris, and HP-

/tmp

and is located in

UX platforms or the directory specified by the TEMP environment
variable on the Windows NT platform). If the WebObjects adaptor
cannot find the public configuration file or if it cannot find the
requested WebObjects application in the public configuration file, it
searches the private configuration file.

A new private configuration file is created automatically any time a
WebObjects application is started and a private configuration file
doesn’t exist. The adaptor contacts only one instance of an application

5

Serving WebObjects

in the private configuration file; if you manually start HelloWorld and it’s
already been started, the entry for HelloWorld in the file is overwritten.
(The old process will continue to run, but cannot be contacted.) The
adaptor also cannot contact a remote instance of an application using the
private configuration file.

The contents of the private configuration file are essentially the same as
those of the public configuration file, except that the contents are stored as
C structures and so cannot be directly modified. This file should only be
modified by the WebObjects adaptor itself.

Adaptor Modes

All WebObjects adaptors route incoming requests to WebObjects applications
in one of three modes:

1. Load-balancing between concurrent instances of the same application
specified in the public configuration file

2. Choosing an application from the private configuration file

3. Autostarting an application

The active adaptor tries to contact the requested application by going through
the modes in the preceding order.

Load Balancing

: When the client request tries to contact an application, the active
WebObjects adaptor first checks the public configuration file for an application
matching the specification in the URL. Load balancing typically occurs only for
the first request of a session if the application stores state in the server.
Afterwards, the application resolves the URL so that page navigation will always
occur in the context of the same application. But if the application stores state
on the page or in cookies, true load balancing will be performed for

Private Configuration File

: If the adaptor cannot find a public configuration file, it

each request.

attempts to resolve the URL against entries in the private configuration file. If
the adaptor finds a matching entry but cannot contact it (for example, the
application has been stopped), the adaptor deletes the “dangling” entry from
the private configuration file and autostarts the application.

Autostarting: If there is no public configuration file and the adaptor fails to find an

application matching the client’s request in the private configuration file, it tries
to start the application itself. The adaptor first searches in specific locations in
the document root of the HTTP server and then in
for a WebObjects application (one with a

.woa

NeXT_ROOT

extension) that matches the

specification in the request URL. If it finds one, it invokes the

6

/NextLibrary/WOApps

WODefaultApp

WebObjects HTTP Adaptors

executable, or if the application is compiled, it invokes the executable in
the application wrapper itself. This invocation starts the application on the
HTTP server machine and registers it in the private configuration file,
thereby allowing the adaptor to contact the new application instance. If the
adaptor cannot find the requested application (for example, there’s a typo in
the URL), it returns a list of the applications it can find.

Note that if the public configuration file

NeXT_ROOT

/NextLibrary/WOAdaptors/Configuration/WebObjects.conf

exists, no
applications are ever autostarted. Also note that adding applications to the
Monitor as described in the section “Initial Monitor Setup” creates the
public configuration file. Thus, if you are using the Monitor application,
autostarting is disabled.

Installed HTTP Adaptors

When WebObjects is installed, the following adaptors are put in

NeXT_ROOT

CGI adaptor is installed on Mach, since neither Netscape’s nor Microsoft’s
servers have been ported to this platform. Also, no ISAPI binary file is
installed on Solaris or HP-UX platforms (only source code).

The following table summarizes the adaptors provided with WebObjects.

/NextLibrary/WOAdaptors

along with source code. Note that only the

Server NextLibrary Location Executable

CGI many WOAdaptors/CGI WebObjects[.exe]
NSAPI2 Netscape 2.0

FastTrack (httpd)
Enterprise (https)

NSAPI2.0.1 Netscape 2.0.1

FastTrack (httpd)
Enterprise (https)

NSAPI3 Netscape 3.0

FastTrack (httpd)
Enterprise (https)

ISAPI Microsoft Internet

Information Server

IIS 1.0
IIS 2.0 (NT Server 4.0)
IIS 3.0 (NT Server 4.0)
Peer Web (NT WS 4.0)

WOAdaptors/NSAPI/2.0 WebObjects-NSAPI.dll

or
WebObjects-NSAPI.so

WOAdaptors/NSAPI/2.0.1 WebObjects-NSAPI.dll

or
WebObjects-NSAPI.so

WOAdaptors/NSAPI/2.0 WebObjects-NSAPI.dll

or
WebObjects-NSAPI.so

WOAdaptors/ISAPI WebObjects-ISAPI.dll

7

Serving WebObjects

Setting Up the Monitor Application

You can perform many essential administrative tasks using a WebObjects
application named Monitor. Monitor helps you create a public configuration file,
start and stop applications, perform load balancing, and set up applications for
optimal performance. Before you can use Monitor, you need to perform some
initial setup. After that, you can use it to easily administer your own WebObjects
applications.

Note:

Previous versions of WebObjects distributed Monitor as an example
application. To use Monitor, you had to recompile your applications using a
special version of WOApplication. This WOApplication class is incompatible
with the Monitor application distributed in WebObjects 3.5. If you want to be
able to Monitor these existing applications, you’ll have to recompile them on
WebObjects 3.5.

Starting Up Monitor

To start up Monitor on Windows NT, choose Monitor from the WebObjects
program group in the Start menu.

To start up Monitor on any other system, do the following:

1. Open a command shell window.

2. Enter these commands:

> cd /NextLibrary/WOApps/Monitor.woa
> Monitor

The Monitor application launches in your default web browser and
displays this screen:

8

Setting Up the Monitor Application

Which Copy of Monitor Should I Use?

If you have multiple machines running WebObjects, you can administer
them all from a single instance of Monitor on a single machine. It’s
recommended that you use the copy of Monitor that’s installed on the same
machine as your HTTP server and WebObjects adaptor. This is because
the main purpose of the Monitor is to maintain the public configuration file

WebObjects.conf

(
instances of WebObjects applications. The best way to achieve sharing of

WebObjects.conf

the
same machine. The alternative—having Monitor on a separate machine—
would require that the two machines share a file system through network
access.

), which the WebObjects adaptor uses to find running

file is to have your HTTP server and Monitor run on the

Monitor can communicate with WebObjects applications running on
remote hosts; however to launch applications on remote hosts it uses a
lightweight daemon named

MonitorProxy

. For example, the following figure
shows a WebObjects site spread across four machines. One machine
contains the HTTP server, and the other three machines contain
WebObjects applications. You would run the Monitor application on the
machine containing the HTTP server. That Monitor application would use
the

MonitorProxy

daemons on the other three machines to launch applications.
All other communication goes directly between Monitor and the
WebObjects application.

9

Serving WebObjects

Starting Up MonitorProxy

As mentioned in the previous section, if you have a multiple machine
configuration, you need to run Monitor on one machine and run
daemons on the other machines. You can start up

MonitorProxy

way you start up Monitor:

MonitorProxy

daemons the same

To start up

MonitorProxy

1. Navigate to the directory

on Windows NT, do the following:

NeXT_ROOT

/NextLibrary/WOApps/Monitor.woa

in the

Explorer.

2. Double-click

To start up

MonitorProxy

MonitorProxy.exe

on any other system, do the following:

.

1. Open a command shell window.

2. Enter these commands:

> cd $NEXT_ROOT/NextLibrary/WOApps/Monitor.woa
> MonitorProxy

You probably want to set up your system so that

MonitorProxy

starts up at system

boot time.

Note:

If you’re running Monitor on a Solaris or HP-UX machine, you must start

MonitorProxy

up

MonitorProxy

local

10

on that machine as well. As you’ll learn later, Monitor requires the

to start up applications on Solaris and HP-UX.

Setting Up the Monitor Application

Initial Monitor Setup

In normal operation, when you start up Monitor, all of the WebObjects
applications on your site are displayed under the Declared Apps heading,
and the right frame shows information about the application you select. (Or
if you set it up properly, you’ll see a login panel and after you log in you’ll
see all of your WebObjects applications.) However, the first time you’ve
started the Monitor, no applications are displayed. You need to configure
the Monitor for use on your site.

Click here to configure the
Monitor application.

To configure the Monitor application, do the following:

1. Click the Options button.

The right frame shows configuration information.

2. Look at the first section of the Configuration options. They should look

like this:

Make sure each option has the appropriate setting as described below:

11

Serving WebObjects

Local host name

The name of the server Monitor is running on.

Admin user name

Protects the Monitor from being used by all users except the one specified here.
If you enter a user name in this field and that user’s password in the “Admin
password” and “Admin password again” fields, Monitor runs in a protected
mode. When you restart Monitor, it displays a login page instead of the typical
first page.

Admin password

If you entered an administrator name, enter the administrator account’s pass­word here.

Admin password again

Repeat the administrator password here.

The second set of options affects the configuration file. Make sure each
option has the appropriate setting as described below:

Primary WebObjects.conf path

The location of the public configuration file. Most of the time, this should be set

NeXT_ROOT

to

/NextLibrary/WOAdaptors/Configuration

. (You only need to change this if you

move the configuration file.)

Additional public paths

If you have more than one server and each server has its own public configura­tion file, click the Add Path button and specify the location of the other configu­ration file(s). Servers can share the configuration file in

NeXT_ROOT

/NextLibrary/WOAdaptors/Configuration

, so usually this setting is not necessary.

Dedicated Monitor WebObjects.conf path

The location of a configuration file used only by Monitor. This file is used only if
you want to start multiple instances of Monitor, which is rare. See “Starting Up
Multiple Monitor Instances.”

The third set of options displays default setting for each application that
you’ll add to the Monitor. Make sure each option has the appropriate
setting as described below:

12

Setting Up the Monitor Application

WebObjects executable name

The executable that you want to use as the default executable for all appli­cations you add to Monitor. By default, this is set to

.

App.exe

WODefaultApp

Path to executable

The path to the executable name you specified in the field above.

Application cycling

Default settings for the periodic shutdown of applications. For more infor­mation, see “Periodically Shutting Down the Application” in this guide.

The fourth set of options you rarely have to change. They are used to
build the WebObjects application URLs that you use when you click
an application’s hyperlink to access one of its running instances.

or

WODefault-

HTTP server host

The host name of your HTTP server.

Adaptor key

The name of your WebObjects adaptor. Usually, this is

jects.exe

. If you use the NSAPI adaptor or ISAPI adaptor, you may have to

WebObjects

or

change the name here.

Protocol name

Should normally be set to

http.

3. Click the Save Changes button at the bottom of the page to record your

changes.

4. In the Main Menu area, click the Add button.

WebOb-

13