Table of Contents | Previous | Next | Index


Chapter 3
Mechanics of Developing JavaScript Applications

This chapter describes the process of developing your application, such as how to use the JavaScript application compiler and how to use the Application Manager of Netscape servers to install or debug your application. For information on using only client-side JavaScript, see the JavaScript Guide.

This chapter contains these sections:


Basic Steps in Building an Application

Normally, HTML is static: after you write an HTML page, its content is fixed. The fixed content is transmitted from the server to the client when the client accesses the page's URL. With JavaScript, you can create HTML pages that change based on changing data and user actions. Figure 3.1 shows the basic procedure for creating and running a JavaScript application.

Figure 3.1    Creating and running a JavaScript application

You take these basic steps to build a JavaScript application:

  1. Create the source files. The source files can be HTML files with embedded JavaScript, files containing only JavaScript, or Java source files. (See "Creating Application Source Files".)
  2. Note that the JavaScript VM used in Netscape Enterprise Server 4.0 implements significant improvements in the processing of local variables (that is, variables that are declared inside a function) as compared to NES 3.6. Therefore it is suggested that use of global variables (that is, variables that are declared between the <server> and </server> tags) be minimized and applications be rewritten to use functions as much as possible. This can improve the application performance significantly.

  3. Build the application by using the JavaScript application compiler to create the bytecode executable (.web file). (See "Compiling an Application".) Compile Java source files into class files.
  4. Publish the web file, any needed uncompiled HTML, image, and client-side JavaScript files, and compiled Java class files in appropriate directories on the server. You can use the Netscape Web Publisher to publish your files, as described in the Web Publisher User's Guide.
  5. Install the application for the first time (see "Installing a New Application") using the JavaScript Application Manager. You also use the Application Manager to restart an application after rebuilding it (see "Starting, Stopping, and Restarting an Application"). Installing or restarting the application enables the JavaScript runtime engine to run it.
  6. After installing an application, you may want to protect it. See "Deploying an Application". You do not need to restart an application after you initially install it.

  7. Run the application by clicking Run in the Application Manager or loading the application URL in your browser. (See "Running an Application" and "Application URLs".) For example, to run Hello World, load http://server.domain/world/. You can also debug the application by clicking Debug in the Application Manager. (See "Debugging an Application".)
  8. After you have completed developing and testing your application, you need to deploy it to make it available to users. Deploying generally involves installing it on a production server and changing access restrictions. (See "Deploying an Application".)
Before you can develop JavaScript applications, you need to enable the runtime engine on the server and should protect the JavaScript Application Manager from unauthorized access. For more information, see "Configuration Information" and Chapter 2, "Getting Started."


JavaScript Application Manager Overview

Before learning how to create JavaScript applications, you should become familiar with the JavaScript Application Manager. You can use the Application Manager to accomplish these tasks:

Add a new JavaScript application.

Modify any of the attributes of an installed application.

Stop, start, and restart an installed application.

Run and debug an active application.

Remove an installed application.

The Application Manager is itself a JavaScript application that demonstrates the power and flexibility of JavaScript. You start the JavaScript Application Manager from the following URL in Navigator:

http://server.domain/appmgr
In response, the Application Manager displays the page shown in Figure 3.2 for Netscape Enterprise Server 3.x and Figure 3.3 for Enterprise Server 4.0.

Figure 3.2    Application Manager in Enterprise Server 3.x

Figure 3.3    Application Manager in Enterprise Server 4.0

The Application Manager displays, in a scrolling list in the left frame, all JavaScript applications currently installed on the server. Select an application by clicking its name in the scrolling list.

For the selected application, the right frame displays the following information:

For a description of these fields, see "Installing a New Application".

Click the Add Application button at the top to add a new application.

Click Configure (in Enteprise Server 3.x) or Preferences (in Enterprise Server 4.0) to configure the default settings for the Application Manager.

Click Documentation to reach Netscape's technical support page for server-side JavaScript, including links to all sorts of documentation about it. Click Help for more instructions on using the Application Manager.


Creating Application Source Files

The first step in building a JavaScript application is to create and edit the source files. The web file for a JavaScript application can contain two kinds of source files:

When you use JavaScript in an HTML file, you must follow the rules outlined in "Embedding JavaScript in HTML".

Do not use any special tags in .js files; the JavaScript application compiler on the server and the JavaScript interpreter on the client assume everything in the file is JavaScript. While an HTML file is used on both the client and the server, a single JavaScript file must be either for use on the server or on the client; it cannot be used on both. Consequently, a JavaScript file can contain either client-side JavaScript or server-side JavaScript, but a single file cannot contain both client-side and server-side objects or functions.

The JavaScript application compiler compiles and links the HTML and JavaScript files that contain server-side JavaScript into a single platform-independent bytecode web file, with the file extension .web, as described in "Compiling an Application".

You install a web file to be run with the JavaScript runtime engine, as described in "Installing a New Application".


Compiling an Application

You compile a JavaScript application using the JavaScript application compiler, jsac. The compiler creates a web file from HTML and JavaScript source files.

NOTE: Netscape Enterprise Server 4.0 supports JavaScript Application Compiler version 24.13. Note that compiled applications using "=" as the Equal operator will fail using the new compiler. You must use "==" as the Equal (==) operator.

For ease of accessing the compiler, you may want to add the directory in which it is installed to your PATH environment variable. For information on how to do so, see "Locating the Compiler" in Chapter 3, "Mechanics of Developing JavaScript Applications."

You also need to add the <server_root>/bin/httpd/lib directory to LD_LIBRARY_PATH (or LIBPATH or SHLIB_PATH on Unix platforms), and <server_root>/bin/https/bin to PATH on Windows NT platforms.

You only need to compile those pages containing server-side JavaScript or both client-side and server-side JavaScript. You do not need to compile pages that contain only client-side JavaScript. You can do so, but runtime performance is better if you leave them uncompiled.
The compiler is available from any command prompt. Use the following command-line syntax to compile and link JavaScript applications on the server:

jsac [-h] [-c] [-v] [-d] [-l]
   [-o outfile.web]
   [-i inputFile]
   [-p pathName]
   [-f includeFile]
   [-r errorFile]
   [-a 1.2]
   script1.html [...scriptN.html]
   [funct1.js ... functN.js]
Items enclosed in square brackets are optional. The syntax is shown on multiple lines for clarity. The scriptN.html and functN.js files are the input files to the compiler. There must be at least one HTML file. By default, the HTML and JavaScript files are relative to the current directory. Files you specify must be either JavaScript files or HTML files; you cannot specify other files, such as GIF files.

On all platforms, you may use either the dash (-) or the forward slash (/) to indicate a command-line option. That is, the following lines are equivalent:

jsac -h
jsac /h
Note that because the forward slash indicates a command-line option, an input file cannot start with a forward slash to indicate that it is an absolute pathname. That is, the following call is illegal:

jsac -o myapp.web /usr/vpg/myapp.html
This restriction does not apply to any of the pathnames you supply as arguments to command-line options; only to the input files. On NT, you can instead use backslash (\) to indicate an absolute pathname in an input file, as in the following call:

jsac -o myapp.web \usr\vpg\myapp.html
On Unix, you must use the -i command-line option to specify an absolute pathname, as described below.

The following command-line options are available:

For example, the following command compiles and links two JavaScript-enhanced HTML pages, main.html and hello.html, and a server-side JavaScript file, support.js, creating a binary executable named myapp.web. In addition, during compilation, the compiler prints progress information to the command line.

jsac -v -o myapp.web main.html hello.html support.js
As a second example, the following command compiles the files listed in the file looksee.txt into a binary executable called looksee.web:

jsac -f looksee.txt -o looksee.web
Here, looksee.txt might contain the following:

looksee1.html
looksee2.html
\myapps\jsplace\common.js
looksee3.html

Installing a New Application

You cannot run an application and clients cannot access it until you install it. Installing an application identifies it to the server. After you have installed the application, you can rebuild and run it any number of times. You need to reinstall it only if you subsequently remove it. You can install up to 120 JavaScript applications on one server.

Before you install, you must move all application-related files to the correct directory, by publishing the files. Otherwise, you'll get an error when you install the application. For security reasons, you may not want to publish your JavaScript source files on your deployment server. See "Application URLs" for restrictions on where you can place your files.

To install a new application with the Application Manager, click Add Application. In response, the Application Manager displays, in its right frame, the form shown in Figure 3.4. (The color scheme is different in Enterprise Server 4.0.)

Figure 3.4    Add Application form

Fill in the fields in the Add Application form, as follows:

After you have provided all the required information, click Enter to install the application, Reset to clear all the fields, or Cancel to cancel the operation.

You must stop and restart your server after you add or change the external libraries for an application. You can restart a server from your Server Manager; see the administrator's guide for your web server for more information.

Application URLs

When you install an application, you must supply a name for it. This name determines the base application URL, the URL that clients use to access the default page of a JavaScript application. The base application URL is of the form

http://server.domain/appName
Here, server is the name of the HTTP server, domain is the Internet domain (including any subdomains), and appName is the application name you enter when you install it. Individual pages within the application are accessed by application URLs of the form

http://server.domain/appName/page.html
Here, page is the name of a page in the application. For example, if your server is named coyote and your domain name is royalairways.com, the base application URL for the hangman sample application is

http://coyote.royalairways.com/hangman
When a client requests this URL, the server generates HTML for the default page in the application and sends it to the client. The application URL for the winning page in this application is

http://coyote.royalairways.com/hangman/youwon.html
Important Before you install an application, be sure the application name you choose does not usurp an existing URL on your server. The JavaScript runtime engine routes all client requests for URLs that match the application URL to the directory specified for the web file. This circumvents the server's normal document root.
For instance, suppose a client requests a URL that starts with this prefix from the previous example:

http://coyote.royalairways.com/hangman
In this case, the runtime engine on the server looks for a document in the samples\hangman directory and not in your server's normal document root. The server also serves pages in the directory that are not compiled into the application.

You can place your source (uncompiled) server-side JavaScript files in the same directory as the web file; however, you should do so only for debugging purposes. When you deploy your application to the public, for security reasons, you should not publish uncompiled server-side JavaScript files.

Controlling Access to an Application

When you install an application, you may want to restrict the users who can access it, particularly if the application provides access to sensitive information or capabilities.

If you work on a development server inside a firewall, then you may not need to worry about restricting access while developing the application. It is convenient to have unrestricted access during development, and you may be able to assume that the application is safe from attack inside the firewall. If you use sample data during the development phase, then the risk is even less. However, if you leave your application open, you should be aware that anyone who knows or guesses the application URL can use the application.

When you finish development and are ready to deploy your application, you should reconsider how you want to protect it. You can restrict access by applying a server configuration style to the application. For information on configuration styles, see the administrator's guide for your web server.


Modifying an Application

To modify an application, select the application name in the list of applications and click Modify.

You can change any of the fields defined when you installed the application, except the application name. To change the name of an application, you must remove the application and then reinstall it.

If you modify the fields of a stopped application, the Application Manager automatically starts it. When you modify fields of an active application, the Application Manager automatically stops and restarts it.


Removing an Application

To remove an application, select it in the list of applications and click Remove. The Application Manager removes the application so that it cannot be run on the server. Clients are no longer able to access the application. If you delete an application and subsequently want to run it, you must install it again.

Although clients can no longer use the application, removing it with the Application Manager does not delete the application's files from the server. If you want to delete them as well, you must do so manually.


Starting, Stopping, and Restarting an Application

After you first install an application, you must start it to run it. Select the application in the list of applications and click Start. If the application successfully starts, its status changes from Stopped to Active.

You can also start an application by loading the following URL:

http://server.domain/appmgr/control.html?name=appName&cmd=start
Here, appName is the application name. You cannot use this URL unless you have access privileges for the Application Manager.

To stop an application and thereby make it inaccessible to users, select the application name in the list of applications and click Stop. The application's status changes to Stopped and clients can no longer run the application. You must stop an application if you want to move the web file or update an application from a development server to a deployment server.

You can also stop an application by loading the following URL:

http://server.domain/appmgr/control.html?name=appName&cmd=stop
Here, appName is the application name. You cannot use this URL unless you have access privileges for the Application Manager.

You must restart an application each time you rebuild it. To restart an active application, select it in the list of applications and click Restart. Restarting essentially reinstalls the application; the software looks for the specified web file. If there is not a valid web file, then the Application Manager generates an error.

You can also restart an application by loading the following URL:

http://server.domain/appmgr/control.html?name=appName&cmd=restart
Here, appName is the application name. You cannot use this URL unless you have access privileges for the Application Manager.


Running an Application

Once you have compiled and installed an application, you can run it in one of two ways:

The server then generates HTML for the specified application page and sends it to the client.


Debugging an Application

To debug an application, do one of the following:

You can use the debug function to display debugging information, as described in "Using the debug Function".

Once you've started debugging a JavaScript application in this way, you may not be able to stop or restart it. In this situation, the Application Manager displays the warning "Trace is active." If this occurs, do the following:

  1. Close any windows running the debugger.
  2. Close any windows running the affected application.
  3. In the Application Manager, select the affect application and click Run.
You can now stop or restart the application.

Using the Application Manager for Debugging

To debug an application, select it in the list of applications and then click Debug. In response, the Application Manger opens a new Navigator window in which the application runs. The trace utility also appears, either in a separate frame of the window containing the application or in another window altogether. (You can determine the appearance of the debug window when you configure the default settings for the Application Manager, as described in "Configuring Default Settings".)

The trace utility displays this debugging information:

Figure 3.5 shows what you might see if you debug the Hangman application.

Figure 3.5    Debugging Hangman

Using Debug URLs

Instead of using the Application Manager, you may find it more convenient to use an application's debug URL. To display an application's trace utility in a separate window, enter the following URL:

http://server.domain/appmgr/trace.html?name=appName
Here, appName is the name of the application. To display the trace utility in the same window as the application (but in a separate frame), enter this URL:

http://server.domain/appmgr/debug.html?name=appName
You cannot use these two URLs unless you have access privileges to run the Application Manager. You may want to bookmark the debug URL for convenience during development.

Using the debug Function

You can use the debug function in your JavaScript application to help trace problems with the application. The debug function displays values to the application trace utility. For example, the following statement displays the value of the guess property of the request object in the trace window along with some identifying text:

debug ("Current Guess is ", request.guess); 

Deploying an Application

After you have finished developing and testing your application, you are ready to deploy it so that it is available to its intended users. This involves two steps:

You should move the application web file to the deployment server, along with any images and uncompiled HTML and JavaScript files that are needed. For more information on how to deploy your application files, see the Netshare and Web Publisher User's Guide.

NOTE: In general, for security reasons, you should not deploy source files.
Depending on the application, you might want to restrict access to certain groups or individuals. In some cases, you might want anyone to be able to run the application; in these cases you don't need to apply any restrictions at all. If the application displays sensitive information or provides access to the server file system, you should restrict access to authorized users who have the proper user name and password.

You restrict access to an application by applying a server configuration style from your Server Manager. For information on using Server Manager and configuration styles, see the Enterprise Server 4.0 Administrator's Guide.


Application Manager Details

This section shows how to change default settings for the Application Manager. In addition, it talks about the format of the underlying file in which the Application Manager stores information.

Configuring Default Settings

To configure default settings for the Application Manager, click Configure (in Enteprise Server 3.x) or Preferences (in Enterprise Server 4.0) in the Application Manager's top frame. In response, the Application Manager displays the form shown in Figure 3.6.

You can specify these default values:

When you install a new application, the default installation fields are used for the initial settings.

In addition, you can specify these preferences:

Under the Hood

The Application Manager is a convenient interface for modifying the configuration file $NSHOME\https-serverID\config\jsa.conf, where $NSHOME is the directory in which you installed the server and serverID is the server's ID. In case of catastrophic errors, you may need to edit this file yourself. In general, this is not recommended, but the information is provided here for troubleshooting purposes.

Each line in jsa.conf corresponds to an application. The first item on each line is the application name. The remaining items are in the format name=value, where name is the name of the installation field, and value is its value. The possible values for name are:

The jsa.conf file is limited to 1024 lines, and each line is limited to 1024 characters. If the fields entered in the Application Manager cause a line to exceed this limit, the line is truncated. This usually results in loss of the last item, external library files. If this occurs, reduce the number of external libraries entered for the application, and add the libraries to other applications. Because installed libraries are accessible to all applications, the application can still use them.

A line that starts with # indicates a comment. That entire line is ignored. You can also include empty lines in the file.

Do not include multiple lines specifying the same application name. Doing so causes errors in the Application Manager.


Table of Contents | Previous | Next | Index

Last Updated: 09/29/99 18:01:49

© Copyright 1999 Sun Microsystems, Inc. Some preexisting portions Copyright 1999 Netscape Communications Corp. All rights reserved.