Preface


This book describes creating Server-Side JavaScript (SSJS) applications. JavaScript is Netscape's cross-platform, object-based scripting language for client and server applications.

This chapter contains these sections:

• What's New in this Release

• What You Should Already Know

• JavaScript Versions

• Where to Find JavaScript Information

• Upgrading from an Earlier Release

• Backward Compatibility with Earlier Releases

• Document Conventions

What's New in this Release

---

With the release of the 3.x and 4.x versions of the server, LiveWire is fully integrated into the server. Since LiveWire database connectivity is now integrated as the LiveWire Database Service portion of server-side JavaScript, developers do not have to install LiveWire as a separate product. Simply turn on the JavaScript support in the Administration Server to make the necessary components available.

---

Note	The difference between SSJS in Netscape Enterprise Server (NES) 3.x and iPlanetTM Web Server 4.1 is that version 4.1 now uses a JavaScript Runtime from Mozilla.org which supports JavaScript 1.4. Previous versions of SSJS supported JavaScript 1.0, JavaScript 1.1, and JavaScript 1.2.

---

Support for JavaScript 1.4

JavaScript version 1.4 provides several new features and enhancements, which are discussed in the online manual Core JavaScript Reference v1.4 at:

http://www.iplanet.com/docs/

The following list summarizes the new features:

• Exception handling.

  You can throw and catch exceptions using the throw and try...catch statements.

• New operators in and instanceof.

  The in operator returns true if the specified property is in the specified object. The instanceof operator returns true if the specified object is of the specified object type.

• Changes to LiveConnect.

  Several changes to LiveConnect improve the way Java and JavaScript code communicate:

  • The methods of java.lang.Object are inherited by JavaArray. In addition, the JavaArrary.toString method now calls the method java.lang.Object.toString.

  • You can pass a JavaClass object to a Java method which requires an argument of type java.lang.Class instead of creating a wrapper around an instance of java.lang.Class.

  • You cannot construct an instance of JSException with a detail message.

  • The three original public constructors for the Java class netscape.javascript.JSException that supported this feature are deprecated.

  • You cannot use the == operator to compare two instances of JSObject. Use JSObject.equals.

• Changes to the eval method.
  • The top-level eval method cannot be called indirectly. In previous versions, it was recommended that this method not be called indirectly; starting with JavaScript 1.4, calling eval indirectly could result in a runtime error. This change improves performance.

  • The eval method is no longer available as a method of Object; use the top-level eval function instead.

• Changes to the Function object.
  • You should no longer specify a function name when using the arguments array; the arguments array is a variable and is no longer a property of Function objects. This change improves performance.

  • Deprecated the Function.arity property. It has been replaced by the Function.length property.

Changes to the JavaScript Application Manager

The functionality of the JavaScript Application Manager has not changed in iPlanet Web Server 4.1 compared to Enterprise Server 3.x. However, it uses the same new color scheme as the Server Manager and it has some minor layout rearrangements.

Figure 1 shows the JavaScript Application Manager in iPlanet Web Server 4.1.

Figure 1    The JavaScript Application Manager in iPlanet Web Server 4.1

The JavaScript Application Manager now has three tabs:

• Applications

  Lists the installed applications and displays buttons for Start, Stop, Restart, Run, Debug, Modify and Remove on the left. The right panel displays information about the application selected in the applications list. If you click Modify, the right panel displays fields that let you modify the selected application.

• Add Application.

  Lets you add a new application.

• Preferences.

  Lets you specify the default values when adding a new application.

Although the names and layout of the tabs and buttons are slightly different in the JavaScript Application Manager in iPlanet Web Server 4.1 than in Enterprise Server 3.6, the underlying functionality is unchanged.

What You Should Already Know

---

This book assumes you have this basic background:

• A general understanding of the Internet and the World Wide Web (WWW).

• A general understanding of client-side JavaScript. This book does not duplicate core or client-side language information.

• Good working knowledge of Hypertext Markup Language (HTML). Experience with forms and the Common Gateway Interface (CGI) is also useful.

• Some programming experience in Pascal, C, Perl, Visual Basic, or a similar language.

• If you're going to use the LiveWire Database Service, familiarity with relational databases and a working knowledge of Structured Query Language (SQL).

JavaScript Versions

---

Each version of the server supports a different version of JavaScript. To help you write scripts that are compatible with multiple versions of the server, this manual uses an abbreviation to indicate the server version in which each feature was implemented.

Table 1    JavaScript and Server versions

JavaScript Version	Server version
JavaScript 1.2	Netscape Enterprise Server 3.6 (NES 3.6)
JavaScript 1.4	Netscape Enterprise Server 4.0 (NES 4.0)
JavaScript 1.4	iPlanet Web Server 4.1 (iWS 4.1)

Where to Find JavaScript Information

---

Because JavaScript can be approached on several levels, its documentation has been split across several books to facilitate your introduction. The suite of online JavaScript books includes:

The server-side JavaScript documentation includes the following books:

• The <Italic>Server-Side JavaScript Guide (this book) provides information about the JavaScript language and its objects. This book contains information for both core and server-side JavaScript. Some core language features work differently on the client than on the server; these differences are discussed in this book.

• The Server-Side JavaScript Reference provides reference material for the JavaScript language, including both core and server-side JavaScript.

If you are new to JavaScript, start with Chapter 1 "JavaScript Overview" then continue with the rest of the book. Once you have a firm grasp of the fundamentals, you can use the Server-Side JavaScript Reference to get more details on individual objects and statements.

Use the material in this book to familiarize yourself with core and server-side JavaScript. Use the Client-Side JavaScript Guide and Client-Side JavaScript Reference for information on scripting HTML pages.

iPlanet Web Server 4.1 Release Notes provides late-breaking information on iPlanet Web Server 4.1, including some information relevant to server-side JavaScript for iPlanet Web Server 4.1.

The Programmer's Guide for iPlanet Web Server summarizes the different programming interfaces available with the 4.x versions of Netscape web servers. Use this guide as a roadmap or starting point for exploring the iPlanet Web Server documentation for developers.

In addition, other Netscape books discuss certain aspects of JavaScript particularly relevant to their topic area. These books are mentioned where relevant throughout this book.

The Netscape web site contains much information that can be useful when you're creating JavaScript applications. Some areas of particular interest include:

• Netscape's technical support page for information on the LiveWire Database Service. It contains lots of useful pointers to information on using LiveWire in your JavaScript applications.

• Netscape's support page for information on server-side JavaScript.

• View Source Magazine, Netscape's online technical magazine for developers. It is updated every other week and frequently contains articles of interest to JavaScript developers.

All of these pages are accessible from:

http://www.iplanet.com/docs/

Upgrading from an Earlier Release

---

If you have previously installed an earlier version of a Netscape web server, you should migrate the server settings when you install the iPlanet Web Server 4.1. For information on how to install the server and migrate settings, see the iPlanet Web Server Installation and Migration Guide.

If you have previously created JavaScript applications using Server-Side JavaScript 3.x, you should be aware of these changes that occur when you upgrade to 4.x and migrate old server settings:

• If the previous server had LiveWire turned on, the 3.x server will have server-side JavaScript turned on. Whether or not the Application Manager requires a password is also preserved. For more information, see "Configuration Information" in Chapter 2 "Getting Started."

• However, upgrading server settings does not move your applications nor does it recompile them for use with the 4.x web server. You must manually recompile user-defined applications before you can use them with a 4.x web server, as described in "Backward Compatibility with Earlier Releases." Be aware that older applications may not work with their original version of the server after recompiling. If you want to use an application with both servers, you should copy the application instead of moving it.

• For information on changes you may have to make in your code when upgrading, see the next section.

Backward Compatibility with Earlier Releases

---

You must also be aware of these changes in the behavior of server-side JavaScript applications relative to Netscape Enterprise Server 3.x:

• You must recompile all of your existing JavaScript applications. For information on using the compiler, see "Compiling an Application." Once you recompile your applications, they will not work under old SSJS installations.

Document Conventions

---

JavaScript applications run on many operating systems; the information here applies to all versions. File and directory paths are given in Windows format (with backslashes separating directory names). For Unix versions, the directory paths are the same, except that you use slashes instead of backslashes to separate directories.

This book uses uniform resource locators (URLs) of the form

http://server.domain/path/file.html

In these URLs, server represents the name of the server on which you run your application, such as research1 or www; domain represents your Internet domain name, such as netscape.com or uiuc.edu; path represents the directory structure on the server; and file.html represents an individual filename. In general, items in italics in URLs are placeholders and items in normal monospace font are literals. If your server has Secure Sockets Layer (SSL) enabled, you would use https instead of http in the URL.

This book uses the following font conventions:

• The monospace font is used for sample code and code listings, API and language elements (such as function names and class names), filenames, pathnames, directory names, HTML tags, and any text that must be typed on the screen. (Monospace italic font is used for placeholders embedded in code.)

• Italic type is used for book titles, emphasis, variables and placeholders, and words used in the literal sense.

• Boldface type is used for glossary terms.

  
  

  ---

  Note	Throughout this manual, all Unix-specific descriptions apply to the Linux operating system as well, except where Linux is specifically mentioned.

  ---