Previous     Contents     Index     Next     
iPlanet Web Server, Enterprise Edition Server-Side JavaScript Guide



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 <BookName>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.")

    Note that the JavaScript VM used in iPlanet Web Server 4.1 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.

  2. 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.

  3. 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.

  4. 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.

    • 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.

  5. 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.")

  6. 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 iPlanet Web Server 4.1.

Figure 3-2    Application Manager

in Enterprise Server 3.x

Figure 3-3    Application Manager

in iPlanet Web Server 4.1

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:

  • application name at the top of the frame

  • path of the application web file on the server

  • default and initial pages for the application

  • maximum number of database connections allowed for the predefined database object. (This is provided for backward compatibility with applications that use database objects; for new applications that use a dbpool, ignore this field. See "Database Connection Pools."See for how to set this parameter for a dbpool.)

  • external libraries (if any)

  • client object maintenance technique

  • status of the application: active or stopped (Users can run only active applications. Stopped applications are not accessible.)

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 Enterprise Server 3.x) or Preferences (in iPlanet Web Server 4.1) 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:

  • Files with standard HTML or JavaScript embedded in HTML. These files have the file extension (suffix) .html or .htm.

  • Files with JavaScript functions only. These files have the file extension .js.

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 iPlanet Web Server 4.1 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:

   [-o outfile.web]
   [-i inputFile]
   [-p pathName]
   [-f includeFile]

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:

  • -h: Displays compiler syntax help. If you supply this option, don't use any other options.

  • -c: Checks syntax only; does not generate a web file. If you supply this option, you do not need to supply the -o option.

  • -v: (Verbose) Displays information about the running of the compiler.

  • -d: Displays generated JavaScript contents.

  • -l: Specifies the character set to use when compiling (such as iso-8859-1, x-sjis, or euc-kr)

  • -o outfile: Creates a bytecode-format web file, named outfile.web. If you do not supply this option, the compiler does not generate a web file. (Omit this option only if you're using the -c option to check syntax or -h to get help.)

  • -i inputFile: Allows you to specify an input file using its full pathname instead of a relative pathname. You can provide only one filename to this option. If you need to specify multiple filenames using full pathnames, use the -f option.

  • -p pathName: Specifies a directory to be the root of all relative pathnames used during compilation. (Use before the -f option.) You can provide only one pathname to this option.

  • -f includeFile: Specifies a file that is actually a list of input files, allowing you to circumvent the character limit for a command line. You can provide only one filename to this option. The list of input files in includeFile is white-space delimited. If a filename contains a space, you must enclose the filename in double quotes.

  • -r errorFile: Redirects standard output (including error messages) to the specified file. You can provide only one filename to this option.

  • -a 1.2: Sets language version to 1.2 for backward compatibility.

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 iPlanet Web Server 4.1.)

Figure 3-4    Add Application form


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

  • Name: the name of the application. This name defines the application URL. For example, the name of the Hello World application is "world," and its application URL is http://server.domain/world. This is a required field, and the name you type must be different from all other application names on the server. See "Application URLs."

  • Web File Path: the full pathname of the application web file. This is a required field. For example, if you installed the Netscape server in c:\nshome, the web file path for the Hello World application is c:\nshome\plugins\samples\js\world\hello.web.

  • Default Page: the page that the JavaScript runtime engine serves if the user does not indicate a specific page in the application. This page is analogous to index.html for a standard URL.

  • Initial Page: the page that the JavaScript runtime engine executes when you start the application in the Application Manager. This page is executed exactly once per running of the application. It is generally used to initialize values, create locks, and establish database connections. Any JavaScript source on this page cannot use either of the predefined request or client objects. This is an optional field.

  • Built-in Maximum Database Connections: the default value for the maximum number of database connections that this application can have at one time using the predefined database object. (This is provided for backward compatibility with applications that use database objects; for new applications that use a dbpool object, ignore this field. See "Database Connection Pools for how to set this parameter for a dbpool object.)

  • External Libraries: the pathnames of external libraries to be used with the application. If you specify multiple libraries, delimit the names with either commas or semicolons. This is an optional field. Libraries installed for one application can be used by all applications on the server. See "Working with External Libraries."

  • Client Object Maintenance: the technique used to save the properties of the client object. This can be client cookie, client URL, server IP, server cookie, or server URL. See "Techniques for Maintaining the client Object."

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


Note 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:

  • Select the application name in the list of applications, and then click Run. In response, the Application Manager opens a new Navigator window to access the application.

  • Load the base application URL in Navigator by typing it in the Location field.

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:

  • values of object properties and arguments of debug functions called by the application

  • property values of the request and client objects, before and after generating HTML for the page

  • property values of the project and server objects

  • indication of when the application assigns new values to properties

  • indication of when the runtime engine sends content to the client

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:

  • moving the application from the development server to the deployment (production) server that is accessible to end users

  • applying or changing access restrictions to the application, as appropriate

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 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 iPlanet Web Server 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 Enterprise Server 3.x) or Preferences (in iPlanet Web Server 4.1) 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:

  • Web File Path: A default directory path for your development area.

  • Default Page: A default name for the default page of a new application.

  • Initial Page: A default name for the initial page of a new application.

  • Built-in Maximum Database Connections: A default value for the maximum number of database connections you can make for the predefined database object. (This is provided for backward compatibility with applications that use database objects; for new applications that use a dbpool object, ignore this field. See "Database Connection Pools" for how to set this parameter for a dbpool object.)

  • External Libraries: A default directory path for native executables libraries.

  • Client Object Maintenance: A default maintenance technique for the client object properties.

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

Figure 3-6    Default Settings form

In addition, you can specify these preferences, shown in Figure 3-7:

  • Confirm on: Whether you are prompted to confirm your action when you remove, start, stop, or restart an application.

  • Debug Output: Whether, when debugging an application, the application trace appears in the same window as the application but in another frame, or in a window separate from the application.

Figure 3-7    Default Settings form with Preferences shown


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:

  • uri: the application name portion of the base application URL

  • object: path to the application web file

  • home: application default page

  • start: application initial page

  • maxdbconnect: default maximum number of database connections allowed for the predefined database object. (This is provided for backward compatibility with applications that use database objects; for new applications that use a dbpool object, ignore this field. See "Database Connection Pools"" for how to set this parameter for a dbpool object.)

  • library: paths to external libraries, separated by commas or semicolons

  • client-mode: technique for maintaining the client object

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.


Previous     Contents     Index     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated August 09, 2000