Introducing Shared Objects

Whether you decide to persist data on the client or on the server depends largely on the type of data you have and its purpose. Data that needs to be stored permanently for business reasons, such as contact information for a customer, should be stored on the server. Information that is persisted primarily as a convenience for users, such as application preferences or a shopping cart the user wants to save for later, should be stored on the client to save the overhead of transmitting the data back to the server and putting it in a database.

Shared objects are the Flex equivalent of web cookies, but are much more powerful. Using ActionScript, you can write code to store data as a shared object on a user's machine. Properties assigned to a shared object are stored in the file as soon as the SWF file is removed from Flash Player by exiting the browser or moving onto a different web page or application. It is also possible to manually store the information at run time; for example, when an event occurs.

Data in a local shared object can be referenced from within the Flex application just like any other object.

Shared objects have the following characteristics:

• They are stored on the end user's machine in a location that varies depending on the platform.

• They have the extension .sol.

• By default, they can be up to 100 KB in size. The user can adjust the size limit and can deny or approve storage of larger objects.

• They can contain complex data structures.

• They cannot contain methods or functions.

• The end user must manually delete them or write code to delete them programmatically. Clearing cookies from the browser does not delete Flex shared objects.

• Like cookies, shared objects cannot be read from different domains. Flash Player has the capability of reading shared objects only if the shared object was created from the same domain as the SWF file.

Note

When you test applications within the Flex Builder authoring environment, you can access only shared objects created by the same application because testing an application opens it as a local file and does not establish a domain.

Creating Shared Objects

The static getLocal() method of the SharedObject class retrieves an existing shared object; if a shared object does not exist, it creates a new one. All shared objects are written as soon as the SWF file is removed from Flash Player. If you need to write a shared object sooner, you can use the static flush() method.

The following ActionScript code creates a shared object:

var soMy:SharedObject = SharedObject.getLocal("myCookie"); 

A file called myCookie.sol is created on the user's machine. The shared object is manipulated in ActionScript as soMy.

To populate the shared object with data, you assign your variables as properties of the data property of the shared object. This is the shared object's only built-in property. The following ActionScript code stores the user Jeff in a shared object:

soMy.data.user = "Jeff"; 

To store complex data structures in a shared object, that object must be instantiated within the shared object. The following code creates an array inside a shared object and places an existing and populated array, employees,into that object:

soMy.data.aUsers = new Array(); soMy.data.aUsers = employees; 

Although shared objects are automatically written as soon as the SWF file is removed from Flash Player, you can write shared objects to disk at other times; for example, using the flush() method in response to an event such as a user clicking a button. The syntax is as follows:

mySharedObject.flush(minimumDiskSpace); 

The minimumDiskSpace parameter specifies the size of the .sol file to be created, instead of simply letting the file size be set by the actual size of the data being written. Using this technique to create an .sol file larger than the current data being written builds in the flexibility for the data size of the shared object to fluctuate without the user being prompted for approval at every slight change.

For example, if a shared object is currently 100 bytes but you expect it to grow to a maximum size of 500 bytes, create it with a value of 500 for the minimumDiskSpace parameter:

soMy.flush(500); 

After the user responds to the dialog box, this method is called again and returns either TRue or false.

Because local objects are persisted on the client, you need to consider disk space constraints. By default, Flex can save shared objects up to 100 KB in size. Each application can have an unlimited number of shared objects, and the 100 KB limit is per shared object. When you try to save a larger object, Flash Player displays the Local Storage dialog box, which enables the user to allow or deny storage for the domain that is requesting access.

The user can also specify permanent local storage settings for a particular domain. Although Flash Player application is playing, right-click, choose Settings, and then open the Local Storage panel. The panel that opens is shown here.

Additionally, if the user selects a value that is less than the amount of disk space currently being used for locally persistent data, Flash Player warns the user that any locally saved shared objects will be deleted.

Reading Shared Objects

When Flash Player tries to read the shared object, one of two possible outcomes occurs:

• A new shared object is created if one with the same name does not already exist (from the same domain).

• If the shared object does exist, the contents are read into the data property of the shared object.

Just as with cookies, it is a best practice to test for the existence of a shared object before referencing it. The following code snippet shows how to test for the existence of a user property:

if (soMy.data.user != undefined){    //statements } 

After you know that the object exists, you can reference its properties as you can those of any other object in ActionScript. For example, to populate a Text control with the ID of txtUserName from a shared object, you can use the following code:

var soMy = sharedObject.getLocal("myCookie"); if (soMy.data.user != undefined){    txtUserName.text = soMy.data.user; } 

All object properties can be referenced from a shared object just as you can do with any other object. However, you cannot store methods in a shared object. For example, to reference the length property of the Array object contained in the shared object, you can use the following code:

for (var i:int = 0; i < soCart.data.aCart.length; i++){    //statements }