Persistent Data1:Client-side Persistent Data

[kino]

How do we keep data around to access it later? Or perhaps keep data for another invocation of the same program? To maximize usability and effectiveness, an application must be able to store relevant client data to disk. Depending on the type of application, client data can contain information such as:

•User preferences

•Visual displays

•Game scores

•Application settings





This data can be retrieved at a later time and further processed. Depending on the application, the data can be stored either locally or remotely. In either case, when the application exits, information regarding the state is written. When the user accesses the application at a later time, that same information is read to return the user to the previous state.


Persistent data is data that a Web application should 'remember' as the user moves between pages. There are different approaches to storing information. The approaches depend on the architecture of the system, i.e. whether the program needs to communicate with the server or not.


Instead of explicitly writing to a file, small amounts of data can be stored on a client machine using:

•Client-side persistent data (CSPD)

•HTTP Cookies





In this Curl Cue, we will concentrate on CSPD in which data is stored in a separate repository on the local machine. The Curl runtime environment handles that process of data storage and retrieval automatically. Thus, this provides a consistent method of data storage and retrieval.


Client-side Persistent Data


Curl's Client-side Persistent Data system allows you to store small amounts of data on the client without explicitly writing to a file. Data is stored in a Curl-specific repository in which the data can:

•Handle multiple formats of data

•Be set to expire

•Limit the amount of data stored

•Share data between two or more related applets

Why should you use CSPD?


Applets written in the Curl language cannot read from or write to the file system unless they are privileged. This restriction poses problems if your application needs to store applet data. Applets that have been run from a Web site could transmit data back to the host system, but this can be slow and could put a strain on the server. In addition, the data involved may be specific to the user or the client machine, such as the user name. Instead, you can use the persistent data system to store small amounts of data on the client.


CSPD stores and retrieves data using key/value pairs. The steps are as follows:

1.Define a private persistent data repository

2.Write key/value pairs to the repository

3.Commit the repository

4.At a later time, use the key name to retrieve data from the repository



Creating the Repository


Create the private persistent data repository using the persistent-data procedure. This procedure call needs to occur at the top-level of your file (outside of any code block). It must appear before any attempt to read or store data in the repository.


In the following code, we are defining a repository that will store values for up to 180 days (if not accessed) and that has a maximum size of 1024 bytes. The "Date storage" argument is a required comment that describes what is stored in the repository.

Code:

{persistent-data
Date storage,
duration = 180days,
max-size = 1024
}

Setting and Committing Persistent Data


Each item stored in a repository is identified by a key (or name). Each key has a datatype of String in which it cannot contain slashes (/) (otherwise there are no restrictions). To store data in the repository, call the set-persistent-data procedure, passing it a key and the associated data.


In the following example, the key is visit data and the data will be the current time (stored as a string).

Code:

{set-persistent-data visit date, {String {DateTime}}}

After you have added all of the data you want to store in the repository, you need to call commit-persistent-data to store the data to disk.

Code:

{commit-persistent-data}

Retrieving CSPD Values


Use the get-persistent-data procedure to get data from the repository. You specify the key, and the procedure returns the value associated with the key. Returned values have the same data type as the stored data.


If the key does not match an entry in the repository, a KeyNotFoundException is thrown. Therefore, it is wise to use a try expression with a catch clause to handle any exceptions.

Code:

{try
set x = {get-persistent-data visit date}
catch not-found:KeyNotFoundException do
set x = You have not been here before
}

Putting it all together


Let's put the entire example together. Note that since CSPD is stored on each client machine, you will get a different time stamp than your neighbor!

Code:

{curl 6.0, 7.0 applet}
{curl-file-attributes
character-encoding = "utf8"
}

|| Defining the repository
{persistent-data
"Date storage",
duration = 180days,
max-size = 1024
}

{value

|| Retrieving persistent data
let x:#String
{try
set x = {get-persistent-data "visit date"}
catch not-found:KeyNotFoundException do
set x = "You have not been here before"
}


|| Setting and committing persistent data
{set-persistent-data "visit date",{String {DateTime}}}
{commit-persistent-data}


|| Returning the value of x
{text The last time you visited this site was: {value x}}

}

For more information regarding Curl's Client-side persistent data system, please refer to the Curl Developer's Guide under Interacting with External Resources/Client-side Persistent Data.