The WebObjects Adaptor provides a flexible interface between a variety of HTTP servers and WebObjects applications. The WebObjects Adaptor consists of two parts, a Web server-side part and a WebObjects application part.
- The application part consists of special classes that are part of every WebObjects application.
- The server-side part is a stand-alone CGI program named WebObjects. It should be installed under your Web server's cgi-bin directory.
Note: The WebObjects Adaptor must reside on the NEXTSTEP, Solaris, or Windows NT computer that hosts your Web server.
Note: On Windows NT, some Web servers (such as Microsoft's IIS server) require that you rename the WebObject Adaptor to WebObjects.exe.
The WebObjectsPro product provides additional WebObjects Adaptor products
- The NSAPI WebObjects Adaptor integrates with the Netscape Commerce Server, giving better security and faster performance.
- C source code for both the CGI WebObjects Adaptor and the NSAPI WebObjects Adaptor which lets you customize the WebObjects Adaptor to work with a Web server that resides on a platform that is not NEXTSTEP, Solaris, or Windows NT.
The WebObjects Adaptor is started by each new request coming into the server and exits as soon as it has transmitted the corresponding response back. Each time the WebObjects Adaptor wakes, it makes attempts to contact a WebObjects application.
The WebObjects Adaptor attempts to make a connection with a currently-running WebObjects application. If the WebObjects application is not running, the WebObjects Adaptor attempts to autostart the application. If the WebObjects Adaptor does not connect with the WebObjects application, the WebObjects Adaptor fails, returning an error message.
If the WebObjects Adaptor connects to the WebObjects application, it trades information with the WebObjects application using the HTTP protocol, passes HTTP responses containing HTML pages back to the Web server, then exits.
Whenever the Web server receives a URL with /cgi-bin/WebObjects... in it, it awakens the WebObjects Adaptor. (Note that you can change the name of the cgi-bin directory; for example, with the Microsoft IIS Server on NT, the URL contains /Scripts/WebObjects.exe in it.)
The Web server sends the WebObjects Adaptor information found in the URL requests, according to CGI protocol, using environment variables and the stdin() character string. The WebObjects Adaptor uses two configuration files as it begins the process of locating a particular WebObjects application:
- A private WebObjects.conf file, on UNIX systems located in the /tmp directory, on Windows NT systems located in whatever directory is specified by the TEMP environment variable. The first WebObjects application to start up after boot time creates the private WebObjects.conf file; as other WebObjects applications are started, they, too record their port and host information in the private WebObjects.conf file.
- A public WebObjects.conf file located in the cgi-bin directory, or in the ns-home/httpd-80/config directory in the case of the NSAPI WebObjects Adaptor. The public WebObjects.conf file is optional, but if it exists and if it lists WebObjects applications, then it overrides the private WebObjects.conf file for those particular applications.
If the WebObjects Adaptor fails to connect with a requested WebObjects application, it returns a single error message: "Did not received any response from application." The anonymity of this message helps protect the details of your site from unwanted user inspection. To get details on the cause of failure, you should inspect the WebObjects Adaptor's log file. The exceptions to this one-error-message rule are error messages related to URL syntax.
The WebObjects Adaptor inspects the information it gets from the Web server and attempts to connect with a WebObjects application in the following ways
- If the information specifies an instance number and host, the WebObjects Adaptor looks for the public WebObjects.conf file to find a particular port and instance number for the specified WebObjects application. If successful, the WebObjects Adaptor then tries to connect. If the WebObjects Adaptor cannot find the WebObjects.conf file, or if the requested WebObjects application is not listed, or if the connection attempt fails, the WebObjects Adaptor fails, returning its error message.
- If the information does not specify an instance number and a host, the WebObjects Adaptor looks first for the public WebObjects.conf file, then for the private WebObjects.conf file.
If there is a public WebObjects.conf file, the WebObjects Adaptor reads all the instances of application under the name requested and picks one randomly. Then it tries to connect. If the connection attempt fails, the WebObjects Adaptor fails, returning the standard error message.
If there is no public WebObjects.conf file, or if there is one but the application requested is not listed in it, the WebObjects Adaptor reads the private WebObjects.conf file. If the application is listed there, it tries to connect. If the application is not listed there, or if the connection failed, the WebObjects Adaptor will autostart the WebObjects application requested.
By design, when the connection process begins, the WebObjects Adaptor first assumes all WebObjects applications are currently running. If, in the connection process, the WebObjects Adaptor finds a particular WebObjects application is not running, the WebObjects Adaptor may try to automatically start up that application.
- The WebObjects Adaptor can only autostart a WebObjects application that resides on the computer hosting the Web server.
- There is no way to use a URL to force autostarting. If the WebObjects application requested is already runnning and accessible following the scheme described above, the WebObjects Adaptor will connect to it and won't autostart a new one.
- The WebObjects Adaptor is intelligent enough to autostart only the applications present on your system.
The WebObjects Adaptor responds to a URL in a sequence of steps, stopping when it makes a connection. For example, given a request that includes the string .../cgi-bin/WebObjects/Examples/myApp
WebObjects performs the following sequence:
- Look for the executable <NeXT_Root>/NextLibrary/WebObjects/Executables/Examples/myApp.app/myApp
- if not found, look for the executable <NeXT_Root>/NextLibrary/WebObjects/Executables/Examples/myApp.debug/myApp
- if not found, look for the executable <NeXT_Root>/NextLibrary/WebObjects/Executables/Examples/myApp/myApp
- if not found, look for the executable <NeXT_Root>/NextLibrary/WebObjects/Executables/Examples/myApp
- if not found, look for the executable <Document_Root>/WebObjects/Examples/myApp.app/myApp
- if not found, look for the executable <Document_Root>/WebObjects/Examples/myApp.debug/myApp
- if not found, look for the executable <Document_Root>/WebObjects/Examples/myApp/myApp
- if not found, look for the executable <NeXT_Root>/NextLibrary/WebObjects/Executables/EOFDefaultApp
- if not found, look for the executable <NeXT_Root>/NextLibrary/WebObjects/Executables/DefaultApp
- if not found, return the standard error message.
In the first eight cases, as soon as the executable is found, the application will be started with:
myApp -d <Document_Root> Examples/myApp (the last argument represents the path-to-the-application).
In the last two cases, the WebObjects Adaptor also tries to find the following directories
- Look for the resources directory <Document_Root>/WebObjects/Examples/myApp
- if not found, look for resources directory <NeXT_Root>/NextLibrary/WebObjects/Executables/myApp
- if not found, return the standard error message.
As soon as one of these directories is found, the application will be started with:
[EOF]DefaultApp -d <Document_Root>Examples/myApp
(the last argument represents the path to the application)
Generally, a WebObjects application responds to a URL placed in a Web page. The format for a WebObjects application URL is
protocol://<ServerHost>/cgi-bin/WebObjects/Application_subpath/AppName:33@<AppHost>
For example, the Web server may receive a URL requesting a WebObjects application of the form
http://localhost/cgi-bin/WebObjects/Examples/HelloWorld:33@rhino
which reads as
- Use the http: protocol.
- Look on this (localhost) computer.
- Run the WebObjects Adaptor program in the cgi-bin directory.
- Pass the application subpath (Examples/HelloWorld:33@rhino) to the WebObjects Adaptor.
The WebObjects Adaptor prepends the application subpath with the path to the Web server's DocumentRoot, which in this example is
<NeXT_Root>/NextLibrary/WebServer/htdocs/WebObjects/Examples/HelloWorld
The WebObjects Adaptor generates a /tmp/CGIMessenger.log file if you create /tmp/logWebObjects. Inspect this file to see a log of the WebObjects Adaptor activities.
- Lines beginning with INFO record normal activity.
- Lines beginning with WARNING record problems.