Mechanics of Developing JavaScript Applications

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:

-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 Enterprise Server 4.0.)

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\js\samples\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. JavaScript code can override what you specify in this setting when it calls the database.connect method.

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

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:

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:

Select the application name in the list of applications, and then click Debug, as described in "Using the Application Manager for Debugging".

Load the application's debug URL, as described in "Using Debug URLs".

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:

Close any windows running the debugger.

Close any windows running the affected application.

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

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.

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.

In addition, you can specify these preferences:

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.6 Default Settings form

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

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.

Table of Contents | Previous | Next | Index

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

Chapter 3 Mechanics of Developing JavaScript Applications

Chapter 3
Mechanics of Developing JavaScript Applications