Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
This chapter addresses WebObjects Deployment installation issues, including what elements of the software need to be installed on a computer, taking the computer’s purpose into account.
The chapter contains these sections:
Choosing What to Install explains which files need to be installed on a computer, based on the purpose of the computer within a deployment.
HTTP Adaptors covers the various HTTP adaptors that can be used in a deployment. It explains which adaptors are appropriate for your platform as well as how to build an adaptor from the source files included with WebObjects.
Data-Store Adaptor Installation describes the JDBC and JNDI adaptors that WebObjects applications can use to interact with data stores, such as databases and directory-services servers.
Choosing What to Install
When you perform a complete installation of WebObjects Deployment on a computer, two types of files are copied to its hard disk: adaptor files and deployment files.
HTTP Adaptor Files
HTTP adaptors allow your web server to communicate with WebObjects application instances. The adaptor processes a single transaction, a request and its response, at a time. Normally, the request is forwarded to a single application instance, which, in turn, generates the response. Exceptions include error conditions or a request for an application that does not exist.
Typically an HTTP adaptor performs the following actions for each request:
Reads the request from the server, checks the URL, and collects header data and form data.
Finds an application to service the request. This is the part of the process that involves load balancing between instances.
Uses an existing socket connection to the application or connects a new socket to the application and forwards the request to the application.
Waits for and reads the response (status, headers, and content).
Returns the connection to the connection pool or—if the connection is transitory—closes the connection.
Sends the response to the client through the web server.
The executable files of the HTTP adaptors are placed in
/System/Library/WebObjects/Adaptors. You can build your own adaptors using the source files for the default adaptors as a starting point. These source files are installed in
In addition to the HTTP adaptors, WebObjects applications that access a data store need to have an appropriate adaptor for that data store. Two types of data stores are supported, databases and directory services; these use JDBC and JNDI (Java Naming and Directory Interface), respectively.
Deployment files are divided into two groups:
Runtime environment. The runtime environment of WebObjects is implemented in JAR (Java archive) files contained within framework (
.framework) bundles. WebObjects frameworks are installed in
/System/Library/Frameworks. These frameworks are used by any WebObjects application, including the deployment tools of WebObjects.
Deployment tools. WebObjects Deployment includes two deployment tools you use to configure and monitor your site. The files that make up these tools are placed in
/System/Library/WebObjects/JavaApplications. Table 2-1 shows the purpose of each tool. For more information on the deployment tools, see Managing Application Instances.
Types of WebObjects Deployment Installations
Depending on the purpose of the computer you’re installing the software on, there are three types of WebObjects Deployment installations you can perform:
Web server only: On a computer that you want to use as the web server but on which you do not intend to run application instances (including the deployment tools), you need to install only the HTTP adaptor files.
Application host only: On computers that you intend to use only as application hosts, you need to install only the deployment tools. (If you do not plan to run JavaMonitor on that computer, you can delete its files.)
Web server and application host: When one computer can satisfy all your deployment needs or when you want a web server to also run application instances, you need to install the adaptor files and the deployment tools.
WebObjects uses a variety of HTTP adaptors to enable access to applications through a web server. Depending on your deployment platform, particular HTTP adaptors are installed by default.
Mac OS X Server supports Apache and CGI. The Apache adaptor is active by default. Requests in the form
http://.../cgi-bin/WebObjects/ are handled by the Apache adaptor. If you disable the Apache module, such requests are handled by the CGI adaptor.
General Adaptor Building Issues
If you want to use an HTTP adaptor other than the one installed by default on your platform, you need to build it and install it. This section discusses building HTTP adaptors from the source code in
Before building an adaptor, make sure that you have the following installed:
ANSI-C compliant compiler—for example,
gccversion 2.7.2 or later
gnumakeversion 3.74 or later
Web server software
Follow these steps to build your adaptor:
Select the platform you want to build on by editing the
Select the adaptor that you want to build by editing the
make.config. You can build multiple adaptors for different web servers at the same time.
Modify the appropriate compile-time parameters in
Adaptor/config.h. Most features can be configured at initialization time. Some, however, are determined during compilation; you change these by editing
Depending on the adaptor you want to build, you may need to make additional changes:
For Apache, modify the
make.config. The default settings should work for Mac OS X Server.
For CGI, you might need to customize
CGI/Makefile. For example, you don’t need to define
-nopdolibwhen you are not using the Apple PDO C compiler.
make.configto point at the compiler you want to use. The compiler must be an ANSI C compiler. The
CCvariable is set to
In case you need to modify the default adaptors, Table 2-2 identifies the purpose of the source files in
Interface modules that interact directly with the web server.
Interface modules that interact directly with the web server.
Operating system–specific configuration items.
Implements request/response processing.
Structures and routines to collect headers and form data. Also function support for sending requests to applications.
Structures and routines to collect response headers and content.
Declaration of application IPC API.
Transport is implemented with nonblocking sockets. This file provides timeouts and user-space buffering.
Declaration of functions to provide load balancing. Load-balancing implementations need to define these functions.
Load-balancing routine that randomly selects any available application instance.
Load-balancing routine that selects an instance using a round-robin algorithm.
Load-balancing routine that selects an instance using the load average returned by each instance in its headers.
Parses the configuration information supplied in an XML document. This is either supplied from wotaskd, a URL, or a file.
WebObjects URL-parsing routines.
Additional utility functions to augment
String key–based dictionary.
String key/value lookup data structure.
Data structure used to collect pointers.
Building the 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.
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, execute the following command:
Make a request to a WebObjects application to initialize the log file.
Execute the following command:
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
Building the CGI Adaptor
The default CGI adaptor is a generic CGI adaptor designed to be used with all web servers that support 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 to your web server’s
scripts directory. This is done for you if you install WebObjects on a system with a web server installed.
It is possible to configure the CGI adaptor to contact 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, do the following:
Make sure that the
WebObjectsCGI executable is installed in
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 2-3.
If you want to include form data, set a
CONTENT_LENGTH header and type the form as
stdin. An alternative is to edit and execute the
Env.csh files provided in
Data-Store Adaptor Installation
This section provides resources that help you obtain and install the two types of data-store adaptors that WebObjects applications may require: database adaptors and adaptors for directory-services servers.
To ensure that your JDBC driver works with your database, you should get the latest JDBC driver that matches the version of your database and the version of Java JDK installed on your machine.
Directory Services Adaptors
WebObjects provides access to directory services through the use of the JNDI adaptor in conjunction with a service provider. WebObjects has been tested with connections to the following Lightweight Directory Access Protocol (LDAP) servers:
OpenLDAP Directory Server
To use this LDAP JNDI adaptor, you need to have the JNDI class libraries and the LDAP service provider from Sun Microsystems installed. These are both available from http://java.sun.com/products/jndi. On Mac OS X these are installed by default.