Programmer's Guide to Enterprise Server 4.0
Table of Contents | Previous | Next | Index | Bookshelf

Programmer's Guide to Enterprise Server 4.0


Chapter 1. Overview

Enterprise Server 4.0 supports a variety of application programming interfaces (APIs) and programming technologies that enable you to do the following:

This chapter discusses the changes in the APIs that are provided with the server from Enterprise Server 3.x to 4.0. It also summarizes the various APIs and programming technologies supported by the server. More information on each API or programming technology is provided either in a chapter in this book, or in a separate book.

The sections in this chapter are:

API Changes in Enterprise Server 4.0

Configuration Files

You can configure the Enterprise Server using the Server Manager interface, or by editing configuration files. The configuration files are in the config directory in the https-server_id directory in the installation directory. For example, if Enterprise Server is installed on a Windows NT machine in D:\Netscape\server4\, the configuration files for the server boots.mcom.com are in:

D:\Netscape\server4\https-boots.mcom.com\config
The main configuration files are magnus.conf, obj.conf, and mime.types, but there are other configuration files as well. See Chapter 2, "Configuration Files," for an overview of these configuration files.

For more detailed information about the files magnus.conf, obj.conf, and mime.types, see the "NSAPI Programmer's Guide" at

http://developer.netscape.com/docs/manuals/enterprise/4.0/nsapi/index.htm
The "NSAPI Programmer's Guide " is also shipped in the Enterprise Server 4.0 build in the manuals/nsapi directory.

Enterprise Server 4.0 APIs

This section summarizes the various APIs and programming technologies supported by Enterprise Server 4.0, discusses how to enable the functionality in Enterprise Server 4.0, and mentions where to get more information about them.

The main categories of extensions and modifications you can make to the Enterprise Server are:

Server-Parsed HTML Tags

Enterprise Server 4.0 provides a C API for defining your own server-side tags. These tags can be used in addition to the standard server-side tags, such as config, include and so on, in HTML files.

Enabling Server-Parsed Tags

To activate and deactivate the parsing of server-side tags, use the Parse HTML page in the Programs tab of the Server Manager. This page enables you to switch off parsing of server-side HTML tags, or enable it with or without also enabling the exec tag. The page also allows you to specify whether to parse all files or just those with a .shtml extension.

The directive in obj.conf that enables the parsing of server-side tags is:

Service fn="shtml_send" type="magnus-internal/parsed-html" method="(GET|HEAD)"
To enable parsing of server-side tags for files with extensions other than .shtml, add the extension to the appropriate line in the mime.types file. For example, the following line in mime.types indicates that files with either a .shtml or .jbhtml extension will be parsed for server-side tags.

type=magnus-internal/parsed-html exts=shtml,jbhtml
After making changes to mime.types, restart the Enterprise Server to update its table of MIME type mappings, since the mime.types file is only loaded when the server is initialized.

For More Information

See Chapter 3, "Server-Parsed HTML Tags," for more information about defining and using server-parsed tags.

Server-Side JavaScript

Enterprise Server 4.0 supports JavaScript version 1.4.

Using JavaScript, you can create dynamic HTML pages that process user input and maintain persistent data using special objects, files, and relational databases. Through JavaScript's LiveConnect functionality, your applications can access Java and CORBA distributed-object applications.

LiveConnect allows you to access Java objects from a JavaScript application. With LiveConnect, you can create an instance of a Java class from within a JavaScript script. You can also access JavaScript objects from within Java.

Some developers choose to use JavaScript solely on the client (such as Netscape browsers). Larger-scale applications frequently have more complex needs, such as communicating with a relational database, providing continuity of information from one invocation to another of the application, or performing file manipulations on a server. For these more demanding situations, Netscape web servers contain server-side JavaScript, which has extra JavaScript objects to support server-side capabilities.

Some aspects of the core language act differently when run on a server. In addition, to supporting the increased performance demands in these situations, server-side JavaScript is compiled before installation, whereas the runtime engine compiles each client-side JavaScript script at runtime.

For information about server-side JavaScript, see the book "Writing Server-Side JavaScript Applications" at:

http://developer.netscape.com/docs/manuals/enterprise/4.0/wrijsap/index.htm

Enabling Server-side JavaScript

To enable or disable server-side JavaScript, use the Server-Side JavaScript page in the Programs tab in the Server Manager interface.

When server-side JavaScript is enabled, the obj.conf file has the following directives:

Compiling Server-side JavaScript Applications

Before you can deploy a server-side JavaScript application, you must compile it into a.web file. You will find several sample JavaScript applications, including the source files, the .web files, and the make files in the directory server-root/plugins/samples/js. One of the easiest ways to compile a new application is to copy a make file for an existing application and modify it to suit your needs.

For information about compiling server-side JavaScript Applications, see the section "Compiling an application" in "Chapter 3, Mechanics of Developing JavaScript Applications" in the book "Writing Server-Side JavaScript Applications" at:

http://developer.netscape.com/docs/manuals/enterprise/4.0/wrijsap/index.htm

Installing Server-side JavaScript Applications

After compiling the application, use the JavaScript Application Manager to register it with the Enterprise Server.

To access the JavaScript Manager in a browser, open the URL http://server_name/appmgr/, for example http://poppy.mcom.com/appmgr/.

To access the JavaScript Application Manager from the Server Manager interface, go to the Server-side JavaScript page in the Programs tab. At the top of the page, you see a line saying something like:

The Server side Javascript Application Manager is at http://poppy.mcom.com/appmgr/
Click on the location for the application manager. The application manager opens in another browser window. You can use the application manager to add JavaScript applications, run them, stop them, start them, and debug them.

For information about using the JavaScript Application Manager, see:

For More Information

For information about JavaScript, you can view the following online books on DevEdge:

CGI

Common Gateway Interface (CGI) programs run on the server and generate a response to return to the requesting client. CGI programs can be written in various languages, including C, C++, Java, Perl and as shell scripts. CGI programs are invoked through URL invocation.

Since the server starts up a process each time the CGI script or program runs, this is an expensive method of programming the server.

Enabling CGI

Enterprise Server provides two ways to identify CGI programs:

Specifying CGI Directories
To specify directories that contain CGI programs (and only CGI programs) use the CGI Directory page in the Programs tab of the Server Manager. The server treats all files in these directories as CGI programs.

For each CGI directory, the file obj.conf contains a NameTrans directive that associates the name cgi with each request for a resource in that directory. These directives are automatically added to obj.conf when you specify CGI directories in the Server Manager interface, or you can manually add them to obj.conf if desired.

For example, the following instruction interprets all requests for resources in http://server-name/cgi-local as requests to invoke CGI programs in the directory D:/Netscape/Server4/docs/mycgi.

NameTrans fn="pfx2dir" from="/cgi-local" 
dir="D:/Netscape/Server4/docs/mycgi" name="cgi"
The obj.conf file must contain the following named object:

<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>
Do not remove this object from obj.conf. If you do, the server will never recognize CGI directories, regardless of whether you specify them in the Server Manager interface or manually add more NameTrans directives to obj.conf.

Specifying CGI File Extensions
Use the CGI File Type page in the Programs tab of the Server Manager to instruct the the server to treat all files with certain extensions as CGI programs, regardless of which directory they reside in. The default CGI extensions are .cgi, .bat and.exe.

To change which extensions indicate CGI programs, modify the following line in mime.types to specify the desired extensions. Be sure to restart the server after editing mime.types.

type=magnus-internal/cgi exts=cgi,exe,bat
When the server is enabled to treat all files with an appropriate extensions as CGI programs, the obj.conf file contains the following Service directive:

Service fn="send-cgi" type="magnus-internal/cgi"

Adding CGI Programs to the Server

To add CGI programs to the Enterprise Server, simply do one of the following:

For More Information

A myriad of information about writing CGI programs is available. A good starting point is "The Common Gateway Interface" at:

http://hoohoo.ncsa.uiuc.edu/cgi/overview.html

Java Servlets and JavaServerPages (JSP)

Enterprise Server 4.0 supports Java servlets and JavaServer Pages (JSP). The server supports Java Servlets API 2.1, and JSP API Level 0.92.

Java servlets are server-side Java programs that can be used to generate dynamic content in response to client requests in much the same way as CGI programs do. Servlets are invoked through URL invocation.

You create servlets using the Servlets API, which was created by Sun MicroSystems. Enterprise Server 4.0 includes all the files necessary for developing and running Java Servlets. You can compile servlets using any Java compiler you like, so long as the servlets.jar file is accessible to your Java compiler. The servlets.jar file is in the server installation directory at:

/bin/https/jar
For information on using the Servlet API see the "Java Servlet API" documentation from Sun Microsystems at:

http://www.javasoft.com/products/servlet/index.html
A JavaServer Page (JSP) is a page much like an HTML page that can be viewed in a web browser. However, as well as containing HTML tags, it can include a set of JSP tags that extend the ability of the web page designer to incorporate dynamic content in a page. These tags provide functionality such as displaying property values and using simple conditionals.

Enabling Java Servlets and JavaServer Pages

When you install Enterprise Server 4.0, you can choose to install the Java Runtime Environment (JRE) or you can specify a path to the Java Development Kit (JDK).

The server can run servlets using the JRE, but it needs the JDK to run JSP. The JDK is not bundled with the Enterprise Server, but you can download it for free from Sun Microsystems at:

http://www.javasoft.com/products/jdk/1.2/
Enterprise Server 4.0+ requires you to use an official version of JDK1.2 on Solaris and NT. On HP, AIX and IRIX use JDK 1.1.
Regardless of whether you choose to install the JRE or specify a path to the JDK during installation, you can tell the Enterprise Server to switch to using either the JRE or JDK at any time, by using the "Configure JRE/JDK Paths" page in the Servlets tab of the Server Manager.

Before the server can serve servlets and JSP, the servlet engine must be enabled. To enable servlets and JSP, use the Enable/Disable Servlets page in the Servlets tab of the Server Manager interface. If servlets are enabled, JSP can be enabled or disabled. If servlets are disabled, JSP is also disabled.

When servlets are enabled, the obj.conf file contains the following Init directives. The first one loads the servlets library and makes the servlet-related functions available to the Enterprise Server. The other two directives initialize the servlet engine.

Init shlib="d:/netscape/server4/bin/https/bin/NSServletPlugin.dll"
funcs="NSServletEarlyInit,NSServletLateInit,NSServletNameTrans,
NSServletService" shlib_flags="(global|now)" fn="load-modules"
Init EarlyInit="yes" fn="NSServletEarlyInit"
Init LateInit="yes" fn="NSServletLateInit"
The file obj.conf also has other directives that relate to servlets, and defines several additional objects for processing requests for servlets.

Adding Servlets and JavaServerPages to the Server

There are two ways to make a servlet accessible to clients once servlet activation has been enabled:

To add a JSP file to the server, simply give the file a .jsp extension, and put it on the server in a directory at or below the document root. So long as JSP is enabled, the Enterprise Server treats all files with a .jsp extension as JavaServer Pages.

NOTE: Do not put JSP files in a registered servlets directory, since the Enterprise Server expects all files in a registered servlet directory to be servlets.)

For More Information

For more information about using servlets in Enterprise Server 4.0, see the book "Programmer's Guide to Servlets in ES 4.0."

For more information about using the Servlets API to create servlets, see the "Java Servlet API" documentation from Sun Microsystems at:

http://www.javasoft.com/products/servlet/index.html
For information about creating JavaServer Pages, see Sun Microsystem's JavaServer Pages 0.92 spec in the build in the manuals/https/servlets/jsp092 subdirectory.

NSAPI

Netscape Server Application Programming Interface (NSAPI) is a set of C functions for implementing extensions to the server. These extensions are known as server plugins.

Using NSAPI, you can write plugins to extend the functionality of the Enterprise Server. an NSAPI plugin defines one or more Server Application Functions (SAFs). You can develop SAFs for implementing custom authorization, custom logging, or for other ways of modifying how the Enterprise Server handles requests.

The file obj.conf contains instructions (known as directives) that tell the server how to process requests received from clients. Each instruction is enacted either during server initialization or during a particular stage of the request-handling process. Each instruction invokes a server application function (SAF).

For example, the following instruction is invoked when the request method is GET and the requested resource is of type text/html. This instruction calls the append-trailer function with a trailer argument of <H4><font color=green>Served by 4.0</font></H4>. (The append-trailer function simply returns the requested resource -- in this case an HTML file -- to the client, and appends the given trailer to it.)

Service method=GET type="text/html" fn=append-trailer
trailer="<H4><font color=green>Served by 4.0</font></H4>"
Enterprise Server 4.0 comes with a set of pre-defined SAFs. It also comes with a library of NSAPI functions for developing your own SAFs to modify the way that the server handles requests.

Enabling NSAPI

You don't enable NSAPI as such. You use it to develop server application functions (SAFs) to use in the file obj.conf. The file obj.conf is essential for the operation of the server -- if it does not exist, the server cannot work, since it has nowhere to look for instructions on how to handle requests.

When defining new SAFs, include the header function nsapi.h (which is in server-root/plugins/include) to get access to all the NSAPI functions.

Installing NSAPI Plugins (SAFs)

To load new NSAPI plugins containing customized SAFs into the server, add an Init directive to obj.conf to load the shared library file that defines the new SAFs. This directive must call the load-modules function, which takes the following arguments:

For example, the following directive loads the shared library d:/netscape/server4/bin/https/bin/httpdlw.dll, (which enables server-side Javascript) and makes the functions livewireInit, livewireNameTrans, and livewireService available to the server.

Init fn="load-modules"
shlib="d:/netscape/server4/bin/https/bin/httpdlw.dll"
funcs="livewireInit,livewireNameTrans,livewireService"

For More Information

For information about changes to NSAPI in Enterprise Server 4.0, see Chapter 4, "NSAPI Changes."

For information about

see the "NSAPI Programmer's Guide" at

http://developer.netscape.com/docs/manuals/enterprise/4.0/nsapi/index.htm
The "NSAPI Programmer's Guide " is also shipped in the Enterprise Server 4.0 build in the manuals/nsapi directory.

Web Application Interface (WAI) API

WAI is supported in Enterprise Server 4.0, but is not guaranteed to be supported in future releases.

Using the Web Application Interface (WAI) API, you can write C, C++, and Java applications that process HTTP requests sent to the server. A WAI application runs within its own process. The Enterprise Server interacts with your application over Internet Inter-ORB Protocol (IIOP).

WAI is a CORBA-based programming interface that defines object interfaces to the HTTP request/response data and server information. Using WAI, you can write a web application in C, C++, or Java that accepts an HTTP request from a client, processes it, and returns a response to the client. You can also write your own server plugins for processing HTTP requests.

For more information on writing applications in WAI, see the online manual Writing Web Applications with WAI at:

http://developer.netscape.com/docs/manuals/enterprise/3.0/wai/index.htm

Enabling WAI

Before installing the WAI component of your Enterprise Server 4.0, you need to install Visibroker 3.3 or higher from Inprise. For information about Visibroker, see:

   http://www.inprise.com/visibroker/products/
After installing Visibroker, install the WAI component of Enterprise Server 4.0. After WAI is installed, you then need to enable WAI. Do this by using the WAI Management page in the Programs tab of the Server Manager. (If WAI is not installed, this button does not appear.)

Installing WAI Applications

You install a WAI application in the same way that you install other NSAPI plugins. The application must contain an initialization function that registers the application. You load it into the server in the usual manner, by adding the following directives to obj.conf:

Start your application on the host machine that runs the Enterprise server. Make sure that when the initialization function registers the application, it specifies the host name and port of the Enterprise 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" online manual Writing Web Applications with WAI.

For More Information

For more information about Visibroker from Inprise see:

http://www.inprise.com/visibroker/products/
For more information about writing WAI applications, see:

http://developer.netscape.com/docs/manuals/enterprise/3.0/wai/index.htm

Access Control API

The Access Control API is a C API that lets you programmatically control who has access to what on the Enterprise Server.

Access control lists (ACLs) determine who has what kind of access privileges to which resources on the server. Each ACL contains a list of access control entries. The following access control entry, for example, says that all access is denied to everyone for any resource that contains the substring private.

acl "*private*";
deny (all)
(user = "anyone");
To create access control lists, use the Restrict Access page in the Programs tab of the Server Manager interface. You can also edit the files that contain the ACLs used by the server.

Access control lists reside in the directory server-installation-dir/httpacl. The server uses the default settings in the file server_root/httpacl/generated.https-serverid.acl. There is also a file called genwork.https-serverid.acl that is a working copy the server uses until you save and apply your changes when working with the user interface. When editing the ACL file, you might want to work in the genwork file and then use the Server Manager to load and apply the changes.

With the Access Control API, you can manipulate access control lists (ACLs), read and write ACL files, and evaluate and test access control to resources on the server. You can also define your own attributes for authentication. For example, you might want to authenticate users based on email address or on the URL that referred them to the resource. You can also authenticate the client based on your own authentication methods and databases.

Registering New Authentication Services

To tell the server to use your attributes for authentication, you need to define your own Loadable Authentication Service (LAS) which is an NSAPI plugin. You load it into the server in the usual manner, by adding the following directives to obj.conf:

For More Information

For information about using the ACL API, see the "Access Control Programmer's Guide" at:

http://developer.netscape.com/docs/manuals/enterprise/3.0/accessapi/index.htm
For information about the syntax for editing ACL files, see Appendix A in the same book.

Web Publishing API

The Web Publishing API provides a set of Java classes that allow client Java applications and applets to manipulate the resources, such as files and directories, on the server. With these classes, the client application can perform standard file system actions such as creating, deleting, and copying resources.

In addition, you can associate meta-information (attributes) with a resource to track arbitrary information about the resource, such as associating a project or a list of reviewers with the resource. You can use the locking facility to ensure that two users don't edit the same resource at the same time. You can also choose to track the history of a component resource by maintaining separate versions of it -- this is known as version control.

Enabling Web Publishing

To enable Web Publishing, use the Web Publishing State page in the Web Publishing tab of the Server Manager interface.

For More Information

For more information on using the Web Publishing Client API, see the "Web Publishing Client API Guide" at:

http://developer.netscape.com/docs/manuals/enterprise/3.0/webpub/index.htm

API Summary

The following table lists the APIs available in Enterprise Server 4.0.

Table 1.1 APIs available in Netscape Enterprise Server 3.0
API/Interface/Protocol Language Documentation

Interfaces for Generating Dynamic Content

Server-Parsed HTML Tags

C

Chapter 3, "Server-Parsed HTML Tags."

Server-Side JavaScript (LiveWire) and LiveConnect

JavaScript

JavaScript Reference

Writing Server-Side JavaScript Applications

Java Servlets

Java

Programmer's Guide to Servlets in Enterprise Server 4.0

JavaServerPages

HTML with additional JSP tags

Programmer's Guide to Servlets in Enterprise Server 4.0

CGI (one process per request)

C, C++, Perl, shell, and other languages

The Common Gateway Interface

API for Writing Server Plugins

NSAPI (in-process shared object/DLL)

C, C++

NSAPI Programmer's Guide

WAI (separate process)

C, C++, Java

Writing Web Applications with WAI

Access Control API

C, C++

Access Control Programmer's Guide

API For Modifying Server Resources

Web Publishing Interface

Java

Web Publishing Client API Guide


Table of Contents | Previous | Next | Index | Bookshelf

Last Updated: 08/12/99 12:35:13

Copyright ©1999 Netscape Communications Corp. All rights reserved.