| Server-side object | |
| Implemented in | LiveWire 1.0 |
Created by
The JavaScript runtime engine on the server automatically creates a client object for each client/application pair.
Description
The JavaScript runtime engine on the server constructs a client object for every client/application pair. A browser client connected to one application has a different client object than the same browser client connected to a different application. The runtime engine constructs a new client object each time a user accesses an application; there can be hundreds or thousands of client objects active at the same time.
You cannot use the client object on your application's initial page. This page is run when the application is started on the server. At this time, there is not a client request, so there is no available client object.
The runtime engine constructs and destroys the client object for each client request. However, at the end of a request, the runtime engine saves the names and values of the client object's properties so that when the same user returns to the application with a subsequent request, the runtime engine can construct a new client object with the saved data. Thus, conceptually you can think of the client object as remaining for the duration of a client's session with the application. There are several different ways to maintain client property values; for more information, see Writing Server-Side JavaScript Applications.
All requests by one client use the same
client object, as long as those requests occur within the lifetime of that client object. By default, a client object persists until the associated client has been inactive for 10 minutes. You can use the expiration method to change this default lifetime or the destroy method to explicitly destroy the client object.
Use the client object to maintain data that is specific to an individual client. Although many clients can access an application simultaneously, the individual client objects keep their data separate. Each client object can track the progress of an individual client across multiple requests to the same application.
Method Summary
| Destroys a client object. |
|
Specifies the duration of a client object.
|
Examples
Example 1. This example dynamically assigns a customer ID number that is used for the lifetime of an application session. The assignId function creates an ID based on the user's IP address, and the customerId property saves the ID.
<SERVER>client.customerId = assignId(request.ip)</SERVER>
See also the examples for the project object for a way to sequentially assign a customer ID.
Example 2. This example creates a customerId property to store a customer ID that a user enters into a form. The form is defined as follows:
<FORM NAME="getCustomerInfo" METHOD="post">
The following code assigns the value entered in the
<P>Enter your customer ID:
<INPUT TYPE="text" NAME="customerNumber">
</FORM>customerNumber field from the temporary request.clientNumber to the more permanent client.customerId:
<SERVER>client.customerId=request.customerNumber</SERVER>
See also
project, request, server
Properties
The client object has no predefined properties. You create custom properties to contain any client-specific data that is required by an application. The runtime engine does not save client objects that have no property values.
You can create a property for the client object by assigning it a name and a value. For example, you can create a client property to store a customer ID at the beginning of an application so a user does not have to enter it with each request.
Because of the techniques used to maintain client properties across multiple client requests, there is one major restriction on client property values. The JavaScript runtime engine on the server converts the values of all of the client object's properties to strings.
The runtime engine cannot convert an object to a string. For this reason, you cannot assign an object as the value of a client property. If a client property value represents another data type, such as a number, you must convert the value from a string before using it. The core JavaScript parseInt and parseFloat functions are useful for converting to integer and floating point values.
Methods
destroy
Destroys a client object.
| Method of |
client
|
| Implemented in | LiveWire 1.0 |
Syntax
destroy()
Description
The destroy method explicitly destroys the client object that issues it and removes all properties from the client object. If you do not explicitly issue a destroy method, the JavaScript runtime engine on the server automatically destroys the client object when its lifetime expires. The expiration method sets the lifetime of a client object; by default, the lifetime is 10 minutes.
If you are using client-cookies to maintain the client object, destroy eliminates all client property values, but it does not affect what is stored in Navigator cookie file. Use expiration with an argument of 0 seconds to remove all client properties stored in the cookie file.
When using client URL encoding to maintain the client object, destroy removes all client properties after the method call. However, any links in a page before the call to destroy retain properties in their URLs. Therefore, you should generally call destroy either at the top or bottom of the page when using client URL maintenance.
client object that calls it:
<server>client.destroy()</server>
client.expiration
expiration
Specifies the duration of a client object.
| Method of |
client
|
| Implemented in | LiveWire 1.0 |
Syntax
expiration(seconds)
Parameters
seconds |
An integer representing the number of seconds of client inactivity before the client object expires.
|
Description
By default, the JavaScript runtime engine on the server destroys the client object after the client has been inactive for 10 minutes. This default lifetime lets the runtime engine clean up client objects that are no longer necessary.
Use the expiration method to explicitly control the expiration of a client object, making it longer or shorter than the default. You must use expiration in each page of an application for which you want a client expiration other than the default. Any page that does not specify an expiration will use the default of 10 minutes.
Client expiration does not apply if using client URL encoding to maintain the client object. In this case, client properties are stored solely in URLs on HTML pages. The runtime engine cannot remove those properties.
Examples
The following example extends the amount of client inactivity before expiration to 1 hour. This code is issued when an application is first launched.
<SERVER>client.expiration(3600)</SERVER>
See also
client.destroy
Last Updated: 10/31/97 12:33:29