Building the Adaptors

Building the Adaptors

If you want to use a different HTTP adaptor from the one installed by default on your platform, you need to build and install it. This section discusses building HTTP adaptors from the source code in /Developer/Examples/WebObjects/Source/Adaptors.

Before building an adaptor, make sure that you have the following installed:

WebObjects Deployment
ANSI-C compliant compiler (e.g. gcc-2.7.2 or later)
gnumake (3.74 or later)
a Web server

On platforms other than Mac OS X Server, make sure that you have defined and exported an environment variable called NEXT_ROOT that contains the path to your WebObjects installation (/opt/Apple by default). On Mac OS X Server, this is equivalent to the root (/) directory of your boot volume. With these prerequisites satisfied, use the following steps to build your adaptor:

Select the platform you wish to build on by editing the ADAPTOR_OS variable in make.config.
Select the adaptor that you want to build by editing the ADAPTORS variable in make.config. You can build multiple adaptors for different Web servers at the same time.
Modify necessary compile-time parameters in Adaptor/config.h. Most features can be configured at initialization time. Some, however, are determined during compilation; these are changed by editing config.h.
Depending on the adaptor you want to build, you may need to make additional changes:
- For Apache, modify the APXS variable in make.config. The default settings should work for Mac OS X Server and Solaris.
- For NSAPI, modify the NS_ROOT variable in make.config. It should point to the iPlanet plugin directory.
- For IIS, if you do not have WebObjects Developer installed, modify the makefile reference to the linker, ld.exe, as appropriate.
- For CGI, you might need to customize CFLAGS or LDFLAGS in CGI/Makefile. For example, Solaris requires LDFLAGS to be defined as -lsocket -lnsl to use Berkeley sockets. Also, you don't need to have -nopdolib defined when you are not using the Apple PDO C compiler.
Defined the variable CC in make.config to point at the compiler you are using. The compiler must be an ANSI C compiler. CC is defined to be gcc by default.
Type make in the directory NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors.

In case you need to modify the default adaptors, Table 3-3 identifies the purpose of the source files in /Developer/Examples/WebObjects/Source/Adaptors/.

Table 3-3 Adaptor source description

Source file	Description
`Apache/mod_WebObjects.c`	Interface modules that interact directly with the Web server.
`CGI/WebObjects.c`	Interface modules that interact directly with the Web server.
`IIS/WebObjects.c`	Interface modules that interact directly with the Web server.
`NSAPI/WebObjects.c`	Interface modules that interact directly with the Web server.
`Adaptor/config.h`	Configuration-parameters file.
`Adaptor/config.c`	Operating system–specific configuration items.
`Adaptor/transaction.c`	Implements request/response processing.
`Adaptor/request.c`	Includes structs and routines to collect headers and form data. Also includes functions support for sending requests to applications.
`Adaptor/response.c`	Structs and routines to collect response headers and content.
`Adaptor/hostlookup.c`	Gets `hostent` structure for an application host using `gethostbyname` and caches the result.
`Adaptor/transport.h`	Declaration of application IPC API.
`Adaptor/nbsocket.c`	Transport is implemented with nonblocking sockets. This file provides timeouts and user-space buffering.
`Adaptor/loadbalancing.h`	Declaration of functions to provide load balancing. Load balancing implementations need to define these functions.
`Adaptor/random.c`	Load-balancing routine that randomly selects any available application instance.
`Adaptor/roundrobin.c`	Load-balancing routine that selects an instance using a round robin algorithm.
`Adaptor/loadaverage.c`	Load-balancing routine that selects an instance using the load average returned by each instance in its headers.
`Adaptor/log.c`	`printf` style logging to `/tmp/WebObjects.log` (`C:\TEMP\WebObjects.log`). Checks for existence of `/tmp/logWebObjects` (`C:\TEMP\logWebObjects`), an empty file that must be owned by root on UNIX platforms. This file should not be present in deployment mode.
`Adaptor/xmlparse.c`	Parses the configuration information supplied in an XML document. This is either supplied from `wotaskd`, a URL or a file.
`Adaptor/WOURLCUtilities.c`	WebObjects URL-parsing routines.
`Adaptor/MoreURLCUtilities.c`	Additional utility functions to augment `WOURLCUtilities.c`.
`Adaptor/strdict.c`	String key–based dictionary.
`Adaptor/strtbl.c`	String key/value lookup data structure.
`Adaptor/list.c`	Data structure used to collect pointers.

The following sections contain additional details about the specific adaptors, including installation instructions.

Apache Adaptor

A successful build of the Apache adaptor yields a file named mod_WebObjects.so. This file should be copied into /System/Library/WebObjects/Adaptors/Apache on Mac OS X and NEXT_ROOT/Library/WebObjects/Adaptors/Apache on other platforms. In order for the adaptor to work, Apache must be configured to accept Dynamic Shared Objects (DSOs). Refer to the Apache Web server documentation available at http://www.apache.org for more information on building Apache to accept DSOs. If the adaptor fails to build, it is probably because Apache is not built to accept DSOs; rebuild the Apache Web server.

Once you have built the adaptor and server, you need to configure the Web server to handle WebObjects requests. See “Customizing HTTP Adaptors” for more information on configuring Apache.

After you have built and configured the server with the linked adaptor, you should start it and confirm that it's working by moving aside the WebObjects CGI adaptor in the cgi-bin directory and making a few requests.You can determine whether the CGI or Apache adaptor is handling requests by turning on the logging feature of the adaptor as follows:

As root, touch /tmp/logWebObjects
Make a request to a WebObjects application to initialize the log file.
From the shell, tail -f /tmp/WebObjects.log
If the Apache Web server is configured to use the CGI adaptor, each request is logged as
```
Info: <CGI> new request: /cgi-bin/WebObjects/MyApp
```
If the Apache Web server is configured to use the WebObjects Apache module, each request is logged as
```
Info: <WebObjects Apache Module> new request: /cgi-bin/WebObjects/MyApp
```

Microsoft IIS ISAPI

To install the ISAPI adaptor, copy the WebObjects.dll file to your HTTP server’s scripts directory. The ISAPI adaptor is loaded into the HTTP server the first time a request of the form http://.../scripts/WebObjects.dll/ is received. It then remains active until the server is stopped.

ISAPI does not provide any specific way to pass information into the adaptor, so the Registry is used. Modifying the Registry should only be done by an experienced Windows 2000 Administrator. To do so, from the Start Menu, choose Run and enter regedit.

The WebObjects adaptor entries are found in the HKEY_LOCAL_MACHINE panel under SOFTWARE\Apple\WebObjects\Configuration. “Customizing HTTP Adaptors” discusses some of the most common modifications you need to make. In addition the following registry entries are recognized by the ISAPI adaptor:

WOUSERNAME

WOPASSWORD

CONF_INTERVAL

CONF_URL

SEND_TIMEOUT

RECV_TIMEOUT

CONNECT_TIMEOUT

TIMEOUT

POOL_SIZE

RETRIES

DORMANT_INTERVAL

ERROR_REDIRECT

LOG_PATH

SCHEDULER

DOCUMENT_ROOT

The values are as described in /Developer/Examples/WebObjects/Source/Adaptors/woadaptor.xml.

Netscape iPlanet NSAPI Adaptor

To install the iPlanet adaptor copy libWebObjects.so to NEXT_ROOT/Library/WebObjects/Adaptors/NSAPI. To use the adaptor, modify the magnus.conf file to use WebObjects. (By default, this file is in /opt/iplanet/servers/https-hostname/config/magnus.conf.)

At the end of the block of configuration items that are prefixed with Init, add the following two lines:

Init fn="load-modules" funcs="WebObjects_init,WebObjectsNameTrans,WebObjectsRequest" shlib=pathToNSAPIadaptor

Init fn="WebObjects_init" root=pathToWebServer'sDocRoot config=woconfigurl

Set pathToNSAPIadaptor to the path to the NSAPI shared library. This is /opt/Apple/Library/WebObjects/Adaptors/NSAPI/libWebObjects.so on Solaris and C:/Apple/Library/WebObjects/Adaptors/NSAPI/WebObjects.dll on Windows.

Set pathToWebServer'sDocRoot to the path to the document root of your Web server (/opt/iplanet/servers/docs).

Set woconfigurl to the URL used to access wotaskd on the local machine, for example http://localhost:1085.

CGI Adaptors

The default CGI adaptor is a generic CGI adaptor designed to be used with all Web servers that supports CGI. There is a performance disadvantage when using CGI adaptors; therefore, you should consider using a server plug-in adaptor whenever possible.

To install this adaptor, copy the file WebObjects, WebObjects.exe on Windows, to your Web server's cgi-bin or scripts directory. This is done for you if you install WebObjects on to a system with a Web server installed.

In Windows 2000 the CGI adaptor normally contacts the instance of wotaskd on localhost for adaptor configuration information including the list of instances. For deployment you normally want to use a different mechanism that is less expensive. Set up the CGI adaptor to use either a static file on the Web server or a static URL for this information. For examples of this see “Customizing HTTP Adaptors”.

If there are problems executing the CGI adaptor on MacOS X

make sure that the WebObjects CGI executable is installed in /Library/WebServer/CGI-Executables/
verify that it is owned by root:admin
make it executable by everyone

Although generally not the best for production level deployment, there is a good reason to use the CGI adaptor. It is useful for exercising the underlying request handler and debugging any customizations you may have made to the source code. Since all input to any CGI program is provided in the environment variables and stdin, the WebObjects CGI program can be conveniently run under a debugger.

To do this, set the following environment variables and values as shown in Table 3-4.

Table 3-4 CGI debugging variable settings

Environment variable	Value
`REQUEST_METHOD`	`GET`
`SERVER_PROTOCOL`	`HTTP/1.0`
`QUERY_STRING`	`\?foo=bar`
`SCRIPT_NAME`	`/cgi-bin/WebObjects`
`PATH_INFO`	`/MyApps/MyCoolApp`

If you want to include form data, set a CONTENT_LENGTH header and type the form as stdin. An alternative is to edit execute the TestCGI.sh or Env.csh files provided in /Developer/Examples/WebObjects/Source/Adaptors/CGI.