The LiveWire objects represent a spectrum of lifetimes, with the request object being the shortest-lived, and the server object being the longest-lived. The request object persists only for a single client request from Navigator. The client object persists for the duration of a particular client's connection to an application. The project object persists for the lifetime of the application (until the application is stopped or re-started), and the server object persists for the lifetime of the server process (until the server is stopped).
Built-in LiveWire Objects
As illustrated in Figure 4.1, all applications on the server will share the same server object. All clients accessing the same application will share the same project object, and all requests by the same client will share the same client object.
client.answer = Substitute(request.guess, client.word, client.answer);Properties of LiveWire objects are always stored as strings. Therefore, if you want to store numeric or Boolean values, you must write your scripts to convert values accordingly. The parseInt and parseFloat functions are useful for this purposte. For more information on these functions, see the corresponding topics in Part 2, "LiveWire Reference." For example, you can create an integer client property as follows:
client.totalNumber = 17If you want to increment the value, use parseInt as follows:
client.totalNumber = parseInt(client.totalNumber)++Similarly, you can create a Boolean client property as follows:
client.bool = trueThen you can check it as follows
if (client.bool == "true") write("It's true!") else write("It's false!")Notice that the conditional expression compares bool to the string "true". You can use other techniques to handle Boolean expressions. For example, to negate a Boolean property, you can use something like this:
request.bool = (request.bool == "true") ? false : trueBecause of these limitations, it may be more convenient to perform application logic using top-level JavaScript variables, and then assign the final values to the appropriate object property afterwards.
LiveWire destroys the request object when the server has finished responding to the request (typically by providing the requested page). Therefore, the typical request object lifetime is less than one second.
var number = 42will persist during the current request only. In addition to the predefined properties and automatically initialized data, you can create request properties by using form elements and by URL encoding properties into the request.
<FORM METHOD="post" ACTION="hangman.html"> <P> What is your guess? <INPUT TYPE="text" NAME="guess" SIZE="1">
URL?varName=value[&varName=value...]where URL is the base URL, varName is a variable name, and value is its value. This scheme requires following the base URL by a question mark (?), that is then followed by pairs of variable names and their values. Separate each pair with an ampersand (&). This creates a request property named varName for each variable listed. For example, the following HTML defines a hyperlink to a page that instantiates the request properties i and j to 1 and 2, respectively. The JavaScript file refpage.html can then reference these variables as request.i and request.j.
<A HREF="refpage.html?i=1&j=2">Click Here</A>Values of URL-encoded request properties are not reset when the user reloads a page (for example, by clicking the Reload button). In the previous example, if the user reloaded refpage.html, then i and j would remain 1 and 2, respectively.
client.prop1 = "foo"This statement assigns the value "foo" to the client property named prop1. LiveWire automatically maintains these user-defined property values. LiveWire does not save client objects that have no property values. Therefore, if an application does not need client objects and does not assign any client object property values, it incurs no additional overhead. A good example of a client object property is a customer ID number. A user might enter the ID number when first accessing the application, or the application might assign a dynamic customer ID, for example,
client.custID = assignID(client.ip)Once the customer ID has been established, it would be inconvenient to require the user to re-enter the ID. However, without a facility like the client object, there would be no way to associate the correct customer ID with subsequent requests from a client.
An application can control the expiration of a client object to make it longer or shorter than the default. An application can change the expiration of a client object with the expiration method, as follows:
client.expiration(seconds)
where seconds is the number of seconds until the client object expires.
An application can explicitly destroy a client object with the destroy method, as follows:
client.destroy()
When an application calls destroy, LiveWire removes all properties from the client object and then destroys the client object that sent the request.
Techniques for maintaining the client object
A LiveWire application can use several techniques to maintain the client object. You select the technique to use when you install or modify the application with the LiveWire Application Manager. For information on using Application Manager, see "Using Application Manager" on page 20.
There are two basic approaches for maintaing the client object: maintain it on the client or use an addressing scheme to maintain it on the server. The client-side techniques use either cookies or URL-encoding to maintain client property values. The server-side techniques use either cookies, URL-encoding, or IP address to refer to a data structure on the server that contains client property values.
Client-side techniques
There are two client-side maintenance techniques:
Netscape cookies are a mechanism by which the client stores information in small files, called cookie files. In the client cookie technique, the server transfers all object information as name/value pairs to the client using the Netscape cookie protocol. This approach is most suitable for high-volume consumer applications. It works only with clients that support the Netscape cookie protocol. One of the advantages of this technique is that you can use it for client-server communication. For more information, see "Using cookies for client-server communication" on page 89.
Each client object property is encoded in the cookie file as follows:NETSCAPE_LIVEWIRE.propName=propValue;where propName is the name of the property and propValue is its value. The Netscape cookie protocol limits the number of property values that can be stored in the cookie file to twenty per directory. Every page in a directory will share the same cookie file. Each entry in the file is limited to 4096 characters. In the client URL encoding technique, the server transfers all object information to the client as name/value pairs appended to URLs that reference other portions of the application. This scheme requires that all URLs be dynamically generated by the server. The object information must be transmitted multiple times for pages that refer to multiple URLs. When using client URL encoding, be sure to use the writeURL function if you need to generate URLs dynamically. For more information on writeURL, see "The writeURL function" on page 84.
Preserving client properties
When using client-side maintenance techniques, properties of client are encoded into the server's response to a client request: either in the HEAD of the document (for client-cookies) or in server-generated URLs (for client URL encoding). Therefore, you cannot change client object properties after performing a flush. LiveWire performs an automatic flush after generating 64Kbytes of data. For more information on flush, see "The flush function" on page 85.
Important:
To prevent losing any information, you should assign all client property values early in the scripts on each page. In general, you should ensure that client properties are set before the application generates 64 Kbytes of content.
Server-side techniques
There are three server-side maintenance techniques:
The IP address technique uses a data structure on the server based on the client's IP address. This approach works well for internal applications that run on a single server when all clients have fixed IP addresses. This technique will not work reliably if the client is not guaranteed to have a fixed IP address (for example, if using DHCP or an Internet service provider that dynamically allocates IP addresses). This technique will also not work for clients that use a proxy server, since all users of the proxy will report the same IP address.
The short cookies technique uses a data structure on the server based on a generated name. The first time the client accesses the application, it stores the generated name in the cookie file. The client then uses the Netscape cookie protocol to store and return this name in subsequent requests.
The short URL encoding technique uses a data structure on the server based on a generated name. The server appends the name to URLs that reference the application. In this scheme, LiveWire dyntamically generates all URLs used in the application.
Advantages and disadvantages of techniques
Each of the different techniques has various advantages and disadvantages, as summarized in Table 4.2. You should select the technique that is most appropriate for your application.
Table 4.2 Client Object Maintenance Techniques
NoteSince locking the project object blocks other users from accessing it, potentially delaying execution of their tasks, it is good practice to lock project only as much as neccessary. The following script shows how to use lock and unlock to lock the project object while the application is modifying the customer ID property.
project.lock() project.next_id = 1 + project.next_id client.id = project.next_id project.unlock()In general, the lock and unlock methods should be balanced. However, LiveWire automatically unlocks the project object after the completion of each client request to prevent an accidental deadlock situation.