Writing Web Applications With WAI: Netscape Enterprise Server/FastTrack Server, Version 3.0/3.01

[Contents] [Previous] [Next] [Index]

Chapter 3
Using WAI

This chapter provides an overview for writing WAI applications. Read this chapter for general information on using WAI, including:

To see working examples of WAI applications and to get a better understanding of how the material in this chapter applies to WAI, read Chapter 2, "Quick Start: Running the Examples".

System Requirements

C++ Requirements: If you are writing a C++ application in WAI, you must use the following:

Java Requirements: If you are writing a Java application in WAI, you must use the following:

You can also use Java development tools that are compliant with the JDK 1.1.x.

Overview

You can use WAI to write a web application service in C, C++, or Java that receives a request from a client, processes the request, and returns data back to the client. You can:

You can use WAI to write, compile, and run the following:

Before You Use WAI

 Before you begin to set up your server to use WAI, you should read through the following sections.

Understanding Security Issues

Before you begin implementing WAI applications at your site, you should read the discussion on security-related issues in Chapter 8, "Security Guidelines for Using WAI".

In general, Netscape recommends that you restrict WAI applications to run only on the local host machine (where the web server runs). You should also restrict login access to this machine to prevent unauthorized users from executing WAI applications.

Read the material in Chapter 8, "Security Guidelines for Using WAI" for a complete explanation of these recommendations.

Understanding Version Differences

The process for setting up and running WAI applications differs between versions 3.0 and 3.01 of the Netscape web servers:

In general, features or instructions specific to a release are noted in the manual.

Converting CGI Applications to WAI

If you have existing programs or modules in CGI, convert them to WAI modules or services to improve performance. CGI starts a new session every time you access it, increasing performance times. Because WAI modules (or WAI services) are persistent, they reduce performance times. You have the option of running applications externally or calling functions from an internal library.

A fundamental difference between CGI and WAI is that CGI programs are written to exist while WAI modules persist. Additionally, WAI modules are inherently multi-threaded so creating additional processes is unnecessary.

Table 3.1 describes the structure of a CGI program alongside the structure of a WAI service:

Table 3.1 Comparison of CGI program structure to WAI program structure
CGI Structure WAI Structure
Read data from POST data input stream.

 Collect data using the methods of the netscape::WAI::HttpServerRequest and netscape::WAI::HttpServerContext objects.

Process, using CGI variables as necessary.

 Process using the methods in the WAIWebApplicationService class.

Writes HTML output to the browser.

 Sends response back to the client using the methods in the netscape::WAI::HttpServerRequest object.

Table 3.2 lists the getRequestInfo variables with CGI equivalents.

Table 3.2 WAI getRequestInfo variables with corresponding CGI functions
WAI variable name Description
CLIENT_CERT

 Authentication scheme for the request (found from the auth-scheme token in the request).

HOST

 Name of the client's host machine

HTTPS

 Specifies whether or not SSL is "ON" or "OFF".

HTTPS_KEYSIZE

 Number of bits in the sesion key used to encrypt the session (if SSL is enabled).

HTTPS_SECRETKEYSIZE

 Number of bits used to generate the server;s private key (if SSL is enabled).

URI

 URI requested by the client

URL

 Complete URL requested by the client.

Most of the CGI variables are the same as the getRequestInfo variables in WAI. The other CGI variables are retrieved out of the netscape::WAI::HttpServerContext object. Table 3.3 lists the CGI variables that correspond to the netscape::WAI::HttpServerContext variables:

Table 3.3 WAIServerContext methods with corresponding CGI functions
HttpServerContext method Description
getName

 SERVER_NAME. The name for the server, as used in the host part of the script URI. Either a fully qualified domain name or an IP address.

getPort

 SERVER_PORT. The port on which this request was received, as used in the port part of the script URI.

getServerSoftware

 SERVER_SOFTWARE. The name and version of the information server software answereing the request and running the gateway.

The CGI functions in Table 3.4 lists the CGI functions that have no equivalent in WAI.

Table 3.4 CGI variables that do not correspond to getRequestInfo or WAIServerContext variables
CGI variable name Description
GATEWAY_INTERFACE

 The version of the CGI specification to which the server complies.

REMOTE_IDENT

 The identity information reported about the connection by an RFC 931[10] request to the remote agent, if available.

Setting Up the Web Server

In order to enable the web server to use applications written in WAI, you need to do the following:

  1. (For 3.0 servers only) Start osagent.
    osagent is used to help operate the object request broker (ORB). See "Starting osagent (3.0 Servers Only)" for details. If you are running a 3.01 version of a web server, you can ignore this step.

  2. (For 3.0 servers only) Install the patch that allows you to run the 3.01 version of WAI.
    This patch release fixes and improves the WAI programming interface to the Enterprise Server in the following ways:
  3. osagent is no longer required to be running.
  4. WAI server plug-ins are officially supported.
  5. You can use OAD to activate your WAI applications.
    (Note that OAD will start only out-of-process WAI applications in C/C++ only and is not supported on Windows NT.)
    6. For more information on this patch and instructions on how to get it and install it, go to http://help.netscape.com/filelib.html#wai.

  6. From the administration server, set the option to enable WAI applications to run on your server.
    See "Setting the Option to Enable WAI" for details.

  7. Optionally, you can change any of the default settings for the web server's ORB.

  8. Optionally, you can configure the web server to log WAI status messages.
    Some of the WAI messages, such as the startup message, are only logged if the server is configured to log messages at the "verbose" level.
    For more information about logging WAI status messages, read "Logging Status Messages".

  9. If you are running an in-process server plug-in, edit the server's configuration files to specify your shared library or shared object and the function that you want to invoke.

Starting osagent (3.0 Servers Only)

 osagent, which is provided with 3.0 versions of Netscape web servers, is used to help operate the object request broker (ORB).

NOTE: osagent is not required for 3.01 versions of Netscape web servers and is no longer packaged with those versions of the server.
osagent is located in the server_root/wai/bin directory on UNIX and in the server_root\wai\bin directory on Windows NT. To run osagent, enter the following command: 

osagent -a 127.0.0.1
The -a flag specifies the address that osagent binds to. You should specify the localhost address (127.0.0.1) for security reasons. For details on these reasons, see Chapter 8, "Security Guidelines for Using WAI".

On Windows NT, you can create a shortcut or program item that runs this command. If you have the Windows NT Resource Kit, you can use the SrvAny command to create a service for osagent. You can set up this service to automatically when your machine starts up. For details, consult the documentation in the Windows NT Resource Kit.

Setting the Option to Enable WAI

You need to configure the web server to interact with WAI applications and server
plug-ins.

Configuring the Server

  1. In your web browser, go to the URL for the administration server.
    When prompted, enter the username and password of the server administrator.

  2. On the Server Selector page, click the button labelled with your server name.
    This brings you to the Server Manager page for your server.

  3. In the menu of categories in the top frame, click Programs.

  4. Under Programs in the left frame, click the WAI Management link.

  5. Under Enable WAI Services, select Yes, then click OK.

  6. Click Save and Apply to save your changes.

What Happens When You Enable WAI

 When you enable WAI, the following changes are made to your obj.conf file:

Configuring the Web Server's ORB

 In most cases, you can run the web server without specifying any additional configuration parameters for the server's object request broker (ORB). In certain situations, however, you might need to override the default configuration.

Changing the ORB Configuration Information

To change the web server's ORB configuration information, you need to edit the obj.conf file for your server (which is located in the server_root/server_id/config directory of your server).

In the Init directive that executes the IIOPinit function, add configuration parameters to specify changes to the ORB configuration.

After editing the obj.conf file, you need to stop and start your server so that the server can read in the updated file.

NOTE: Before changing the configuration, you should be aware of the security issues involved with running WAI applications on other machines. See Chapter 8, "Security Guidelines for Using WAI" for details.

Listing of Configurable Parameters

 You can add any of the parameters listed in Table 3.5 to the Init directive for the IIOPinit function.

The following table lists the parameters that you can specify in the Init directive for the IIOPinit function

Table 3.5 IIOPInit Parameters
Parameter Name Description 
ORBagentaddr
 (For 3.0 servers only) Specifies the IP address where osagent is running. The ORB uses this setting to find osagent.

If this parameter is not set, the ORB uses the localhost IP address (127.0.0.1) by default.

If you have configured osagent to use a different IP address than localhost, you need to include this parameter in the Init directive.

ORBagentport
 (For 3.0 servers only) Specifies the port number used by osagent. The ORB uses this setting to find osagent.

If you have configured osagent to use a port number other than the default port, you need to include this parameter in the Init directive.

ORBsendbufsize
 Specifies the size of the send buffer to be used by the network transport mechanism. If not specified, an appropriate default size will be used. 

ORBrcvbufsize
 Specifies the size of the receive buffer to be used by the network transport mechanism. If not specified, an appropriate default size will be used. 

ORBmbufsize
 Specifies the size of the intermediate buffer used by the ORB. If not specified, the ORB will maintain a pointer to the argument and will not make an intermediate copy. Using this parameter incorrectly can seriously affect performance. 

ORBshmsize
 Specifies the size of the shared memory buffer used by the ORB. If this is not specified, an appropriate size will be used. 

OAipaddr
 Specifies the IP address to be used for this BOA.

If this parameter is not set, the ORB uses the localhost IP address (127.0.0.1) by default. 

OAport
 Specifies the port number to use for this BOA. If not specified, an unused port number is used. 

OAshm
 Enables the use of shared memory. 

OAnoshm
 Disables the use of shared memory for sending and receiving messages when the client and object implementation are located on the same host. 

OAsendbufsize
 Specifies the size in bytes of the network transport's send buffer. If this option is not specified, an appropriate buffer size is used. 

OArcvbufsize
 Specifies the size in bytes of the network transport's receive buffer. If this option is not specified, an appropriate buffer size is used.

Example of Configuring the ORB

For example, in a 3.0 version of a web server, suppose you are running the osagent from IP address 205.217.229.39 on port 15001. By default, the web server expects the osagent utility to run on the localhost IP address (127.0.0.1) under the default port.

In the obj.conf file, change the Init directive for the IIOPinit function from:

Init LateInit="yes" fn="IIOPinit"
to:

Init LateInit="yes" fn="IIOPinit" ORBagentaddr="205.217.229.39" ORBagentport="15001"
In your WAI application, you also need to specify this argument when initializing the ORB and BOA. For example:

int bargc = 0;
char **bargv = new char *[3];
 
bargv[bargc++] = "-OAipaddr";
 
bargv[bargc++] = "204.200.215.98";
 
bargv[bargc] = 0;
 
// Initialize the ORB.
 
ORB orb = org.omg.CORBA.ORB.init(bargc, bargv);
 
// Initialize the BOA.
 
BOA boa = orb.BOA_init(bargc, bargv);

Logging Status Messages

 Some of the status messages (such as the WAI initialization messages) are logged to the server's error log only if the server is running with the LogVerbose option turned on. These are messages that are logged with the severity level LOG_VERBOSE.

If you want these types of messages logged, edit the magnus.conf file and add the following directive:

LogVerbose on
The verbose log information is stored in server-root/https-serverID/logs/errors and server-root/https-serverID/logs/access.

After editing the magnus.conf file, you need to stop and start your server so that the server can read in the updated file. You can find the mangus.conf file in server-root/https-serverID/logs/config.

Compiling Applications and Server Plug-Ins

When compiling and linking your application or server plug-in, follow the tips in this section. (You can also look at the makefiles provided with the sample applications.)

Compiling C/C++ Applications

Follow these guidelines for compiling and linking C/C++ applications.

Include Directories

Add the following include directories to your makefile:

Libraries

 On UNIX, you can add the following library directories to your linker command. Specify that libraries should be searched for shared object during runtime to resolve symbols (on Solaris, use the -R flag; on IRIX, use the -rpath flag):

The following table lists the additional libraries that you need to link to:

Table 3.6 Libraries That You Need to Link to
Platform Libraries
Solaris

 
lib/libldap10.so
lib/liblcache10.so
wai/lib/libONEiiop.so
wai/lib/liborb_r.so
bin/https/ns-httpd.so
libthread.so
libposix4.so
libresolv.so
libnsl.so
lib/libnspr.so
wai/lib/libIIOPsec.a
Windows NT (in addition to the standard Windows libraries)

 
wai\lib\ONEiiop10.lib
WSOCK32.lib
IRIX

 
lib/libldap10.so
lib/liblcache10.so
wai/lib/libONEiiop.so
wai/lib/liborb_r.so
bin/https/ns-httpd.so
wai/lib/libIIOPsec.a
HP-UX

 
dce.sl
wai/lib/orb_r.sl
wai/lib/ONEiiop.sl
bin/https/nshttpd.sl
wai/lib/IIOPsec.sl
AIX

 
wai/lib/ONEiiop_shr
wai/lib/IIOPsec
bin/https/nshttpd_shr
lib/nspr_shr
wai/lib/orb_r
dcepthreads
C_r
Digital UNIX

 
lib/ldap10.so
lib/lcache10.so
wai/lib/ONEiiop.so
wai/lib/orb_r.so
bin/https/ns-httpd.so
wai/lib/IIOPsec.so

Compile Flags

The following table lists the flags and defines that you need to use:

Table 3.7 Compile Flags
Platform Flags/Defines
Solaris

 
-DXP_UNIX -D_REENTRANT -KPIC
Windows NT

 
-DXP_WIN32 -DWIN32 /MD
IRIX

 
-o32 -exceptions -DXP_UNIX -KPIC
HP-UX

 
-DXP_UNIX -D_REENTRANT -DHPUX
AIX

 
-DXP_UNIX -D_REENTRANT -DAIX  $(DEBUG)
Digital UNIX

 
-DXP_UNIX -KPIC

Compiling C/C++ Server Plug-Ins

In addition to the tips above, follow these tips when compiling server plug-ins (which are shared libraries or dynamic link libraries):

Compiling Java Applications

 If you are compiling a Java application, make sure to include server_root/wai/java/nisb.zip and server_root/wai/java/WAI.zip in your CLASSPATH environment variable.

Running Applications

Start your application on the host machine that runs the web server. Make sure that when your application registers, you specify the host name and port of the web server.

Note that it is possible (but not recommended) to run WAI applications on other machines in the local network. For a complete explanation of the security concerns and instructions for configuring the server to recognize WAI applications on other machines, see Chapter 8, "Security Guidelines for Using WAI".

Setting Up Your Application with OAD

You can set up your WAI application with the Netscape Internet Service Broker's object activation daemon (OAD), a process which automatically starts up your application if it is not running.

For example, you may want to ensure that your application is always running and does not need to be started manually.

To set up your application with the OAD, follow these steps:

  1. Make sure to specify a name for your object in the WAIWebApplicationService constructor.

  2. Set the second argument (activateObject) to WAI_FALSE.

    At a point in your application where you are ready to launch your object, call the ActivateWAS method of WAIWebApplicationService.

    Compile and run your application at least once, in order to register your application with the web server's naming service.

    You need to register your application before setting it up with OAD. OAD expects your application to be registered with the web server.

  3. Set the following environment variables in the shells where the web server and OAD run:

    You also need to set the LD_LIBRARY_PATH (or SHLIB_PATH on HP-UX) environment variable to the paths that include all shared libraries linked to by your object server.

    For example, in C shell, you might enter the following commands before starting OAD and your webserver: 

    setenv NS_SERVER_ID https-gromit
    setenv NS_SERVER_ROOT /usr/netscape/suitespot
     
    setenv LD_LIBRARY_PATH /usr/netscape/suitespot/wai/lib:
                           /usr/netscape/suitespot/bin/https:
                           /usr/netscape/suitespot/lib:
                           /usr/local/java/lib 
    setenv ORBELINE_IMPL_NAME myfile
     
    setenv ORBELINE_IMPL_PATH /usr/tmp

    If you start OAD after setting these variables, the OAD will generate the file /usr/tmp/myfile to keep track of the object implementations.

  4. After starting your web server, start the OAD manually.
    For instructions on starting OAD, see the Netscape Internet Service Broker Reference Guide for C++ or the Netscape Internet Service Broker Reference Guide for Java.

  5. Run regobj to register your service with the OAD.
    regobj is located in the server_root/wai/bin directory. For details on the syntax for this command, see the Netscape Internet Service Broker Reference Guide for C++. You need to specify "*" as the interface name. You can pass arguments to the object server using the -a option.

    For example, to start up the object named WASP implemented by the WAI application /usr/local/ns-home/wai/bin/WASP, use the following command: 

    regobj -o "*,WASP" -f /usr/local/ns-home/wai/bin/WASP 
           -a httpServerName=bar:80

    The example above assumes that the web server is running on port 80 of the machine named bar.

Using osagent with Java (3.0 Only)

 In the 3.0 version of the web server, if you are running a Java application written with WAI, you should specify the -DDISABLE_ORB_LOCATOR flag. This minimizes potential problems with the osagent utility.

For example, if you have written the Java class WASP.class with WAI, use the following command to run your Java application: 

java -DDISABLE_ORB_LOCATOR WASP
Note that if you are specifying the DISABLE_ORB_LOCATOR option for osagent, you must force the web server's basic object adapter (BOA) to listen on a particular port. To do this, follow the instructions below.

  1. Edit the obj.conf file (located in the server_root/server_id/config directory on UNIX and the server_root\server_id\config directory on Windows NT), and change the following line: 
    Init LateInit="yes" fn="IIOPinit"
    to: 
    Init LateInit="yes" fn="IIOPinit" OAport="21000"

    The OAport option specifies the port selected where the web server's BOA listens. The example above sets up the BOA to listen to port 21000.

  2. Delete the files server_root/wai/NameService/server_id.* on UNIX or server_root\wai\NameService\server_id.* on Windows NT.
    For example, delete https-myhost.IOR, https-myhost.sav, and https- myhost.bak. These files are name service files for your currently registered objects.

  3. Register your objects with the web server again.
    For example, start any WAS object servers. You must complete this step. If you do not, you might not be able to register objects with the web server.

Running Applications on Remote Machines

 You can configure your WAI applications to run on separate machines other than the machine hosting the web server. Read through the information about security issues in Chapter 8, "Security Guidelines for Using WAI", for more information.

[Contents] [Previous] [Next] [Index]

Last Updated: 12/04/97 16:12:11

Copyright © 1997 Netscape Communications Corporation

Any sample code included above is provided for your use on an "AS IS" basis, under the Netscape License Agreement - Terms of Use