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.
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,
ADAPTOR_OS
variable in make.config
.
ADAPTORS
variable in make.config
. You can build multiple adaptors for different web servers at the same time.
config.h
. The comments in the file will guide you along. The defaults are good enough most of the time.
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.
NS_ROOT
variable in make.config
. It should point to the iPlanet plugin directory.
ld.exe
supplied by WebObjects. Otherwise, you'll have to modify the Makefile.
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.
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.
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.
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.
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:
Apache/mod_WebObjects.c | |
CGI/WebObjects.c | |
IIS/WebObjects.c | |
NSAPI/WebObjects.c |
These are the adaptor interface modules that interact directly with the web server. They all perform steps 1 & 5, above as well as deal with the configuration pecularities of each server. |
Adaptor/config.h |
Configuration parameters file. |
Adaptor/config.c |
Covers some operating system specific configuration issues. |
Adaptor/transaction.c |
Implements the meat of the request/response handling. |
Adaptor/request.c |
Struct & routines to collect headers & form data. Functions support sending request to application. |
Adaptor/response.c |
Struct & routines to collect response headers & content. |
Adaptor/hostlookup.c |
Gets |
Adaptor/transport.h |
Declaration of application IPC api. |
Adaptor/nbsocket.c |
Transport implemented with non-blocking sockets. Works cross-platform and provides timeouts and user-space buffering. Good performance and the timeouts provide failover behaviour when machines crash or there is a network outage. |
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 |
|
Adaptor/xmlparse.c |
Parses the configuration information supplied in XML format. This is either supplied from wotaskd, a URL or a file. |
Adaptor/WOURLCUtilities.c |
WebObjects URL parsing routines provided with WOF distribution. Consider this file read-only. |
Adaptor/MoreURLCUtilities.c |
Additional utility functions to augment |
Adaptor/strdict.c |
string key based dictionary |
Adaptor/strtbl.c |
string key/value lookup data structure |
Adaptor/list.c |
data structure to collect pointers |