WebObjects Server Adaptor

This adaptor is intended to be used as a server plugin where state information can be maintained from request to request. CGI is supported, but there's no real benefit over the default adaptor (though CGI is easier to debug than the plug ins). Because web servers differ in their architecture, we have a different adaptor for each web server that we support. It could be an Apache, NSAPI or IIS adaptor. Of course, as mentioned before, it could well be a CGI adaptor.

This document describes how to build the adaptor. It also describes briefly how the adaptor works so that developers can modify it to suit their own needs. For information on installing the adaptor, see the installation files for CGI, Apache, Microsoft ISAPI, or Netscape NSAPI.

Building the adaptor

Source files including makefiles are located in $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors. Build flags and configuration changes that are specific to OS platforms and/or related to other installed software, like Netscape Web Server, are found in make.config or the makefiles.

To build the adaptor,

1. Select the platform you wish to build on by editing the ADAPTOR_OS variable in make.config.
2. 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.
3. Modify any necessary compile time parameters in Adaptor/config.h. Most features are configurable at initialization time. Some are decided at compile time and can be changed by editing config.h. The comments in the file will guide you along. The defaults are good enough most of the time.
4. For Apache, you'll need to modify the APXS variable in make.config. If you are on Solaris or Windows NT/2000, first download the latest Apache server at The Apache Group. For more building instructions, see the Apache installation instructions.
5. For NSAPI, you'll need to modify the NS_ROOT variable in make.config. It should point to the iPlanet plugin directory.
6. For IIS, the Makefile assumes that you have WebObjects Developer package installed since it makes use of a linker ld.exe supplied by WebObjects. Otherwise, you'll have to modify the Makefile.
7. For CGI, you might need to customize CFLAGS or LDFLAGS in CGI/Makefile. For example, for Solaris, we need LDFLAGS to be defined as -lsocket -lnsl since we are using Berkeley sockets. Also, you don't need to have -nopdolib defined if you are not using Apple PDO C compiler.
8. Ensure that you have defined the variable CC in make.config to point at the compiler you wish to use. The compiler must be an ANSI C compiler. CC is defined to be gcc by default.
9. Type make in the directory $NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors.

Note: The Windows version of WebObjects includes an older C compiler and linker. There are known compatibility issues which make it impossible to build the plugin adaptor on Windows using the supplied compiler and linker with current third party libraries, including the current iPlanet. It is possible to build the plugin adaptors on Windows using older versions of the Netscape, although the Netscape plugin may not work with iPlanet 6.0. It may also be possible to port the adaptor source to a non-WebObjects build environment to build using current Netscape.

Developing with Eclipse

The project contains an Eclipse project. You can install the C language plugin by going to Eclipse and choosing:
Help -> Install New Software -> Helios (or your eclipse version) -> Program Languages -> C/C++ Development Tools (CDT)

Then import the project by choosing File -> Import -> General -> Existing Projects into Workspace. Select the Root Directory as:
<wonder>/Utilities/Adaptors
where <wonder> is the root of your wonder source tree.

Code roadmap

The adaptor processes a single transaction at a time (from the programming point of view; multi-threaded servers can process more than one but the sole difference is that we need to protect certain code sections in those cases). A transaction is a single request plus a response. The request is normally forwarded to a single application instance and the request is normally obtained from the same application instance. Exceptions would include error conditions or a request for an application that does not exist. Here is what the adaptor does to service a typical request:

1. Read the request from the server: check the URL, collect the headers and form data (if any).
2. Find an application to service the request. This is the part of the process which involves load-balancing between instances.
3. Use an existing socket connection to the application or connect a new socket to the application, and forward the request to the application.
4. Wait for and read the response (status, headers, and content).
5. Return the connection to the connection pool or (if transitory) close the connection
6. Sends the response to the client, via the server.