SharedObject class

Availability

Flash Communication Server MX 1.0.

The SharedObject class lets you store data on the server and share data between multiple client applications in real time. Shared objects can be temporary, or they can persist on the server after an application has closed; you can consider shared objects as real-time data transfer devices.

NOTE

This entry explains the server-side SharedObject class. You can also create shared objects with the client-side SharedObject class. For more information, see "SharedObject class" in Client-Side ActionScript Language Reference for Flash Media Server 2.

The following list describes common ways to use shared objects in server-side ActionScript:

Storing and sharing data on a server
A shared object can store data on the server for other clients to retrieve. For example, you can open a remote shared object, such as a phone list, that is persistent on the server. Whenever a client makes a change to the shared object, the revised data is available to all clients that are currently connected to the object or that connect to it later. If the object is also persistent locally and a client changes the data while not connected to the server, the changes are copied to the remote shared object the next time the client connects to the object.
Sharing data in real time
A shared object can share data among multiple clients in real time. For example, you can open a remote shared object that stores real-time data that is visible to all clients connected to the object, such as a list of users connected to a chat room. When a user enters or leaves the chat room, the object is updated and all clients that are connected to the object see the revised list of chat room users.

It is important to understand the following information about using shared objects in server-side ActionScript:

The server-side ActionScript method SharedObject.get() creates remote shared objects (RSOs); there is no server-side method that creates local shared objects (LSOs).
The RSO file extension is .fso; RSOs are stored on the server in a subdirectory of the application that created them.
Server-side shared objects can be non-persistent (exist for the duration of an application instance) or persistent (stored on the server after an application closes).
To create a persistent shared object, set the persistence parameter of the SharedObject.get() method to true. Persistent shared objects let you maintain an application's state.
Every RSO is identified by a unique name and contains a list of name-value pairs, called properties, like any other ActionScript object. A name must be a unique string and a value can be any ActionScript data type.

NOTE

Unlike client-side shared objects, server-side shared objects do not have a data property.
To get the value of a server-side shared object property, call SharedObject.getProperty(). To set the value of a server-side shared object property, call SharedObject.setProperty().
To clear a shared object, call the SharedObject.clear()method; to delete multiple shared objects, call the Application.clearSharedObjects() method.
Server-side shared objects can be owned by the current application instance or by another application instance. The other application instance can be on the same server or on a different server. References to shared objects that are owned by a different application instance are called proxied shared objects.

If you write a server-side script that modifies multiple properties, you can prevent other clients from modifying the object during the update by calling the SharedObject.lock() method before updating the object. Then you can call SharedObject.unlock() to commit the changes and allow other changes to be made. Call SharedObject.mark() to deliver change events in groups within the lock() and unlock() methods.

When you get a reference to a proxied shared object, any changes made to the object are sent to the instance that owns the object. The success or failure of any changes are sent using the SharedObject.onSync event handler, if it is defined.

The SharedObject.lock() and SharedObject.unlock() methods cannot lock or unlock proxied shared objects.

NOTE

For more information on shared objects, see "About streams and shared objects", "Shared object flow", and "Shared object files" in Developing Media Applications.

Method summary for the SharedObject class

Method	Description
SharedObject.clear()	Deletes all the properties of a persistent shared object.
SharedObject.close()	Unsubscribes from a shared object.
SharedObject.commit()	Static; stores either a specific persistent shared object instance or all persistent shared object instances that are marked dirty.
`SharedObject.flush()`	Saves the current state of a persistent shared object.
`SharedObject.get()`	Static; creates a shared object or returns a reference to an existing shared object.
`SharedObject.getProperty()`	Gets the value of a shared object property.
`SharedObject.getPropertyNames()`	Returns an array of all the current valid properties in the shared object.
`SharedObject.lock()`	Locks the shared object instance. Prevents any changes to this object by clients until the SharedObject.unlock() method is called.
SharedObject.mark()	Delivers all change events to a subscribing client as a single message.
`SharedObject.purge()`	Causes the server to remove all deleted properties that are older than the specified version.
SharedObject.send()	Sends a message to the client subscribing to this shared object.
SharedObject.setProperty()	Sets a new value for a shared object property.
SharedObject.size()	Returns the number of valid properties in a shared object.
`SharedObject.unlock()`	Unlocks a shared object instance that was locked with SharedObject.lock().

Property summary for the SharedObject class

Property	Description
SharedObject.autoCommit	A Boolean value indicating whether the server periodically commits all persistent shared objects to be stored (`true`) or not (`false`).
SharedObject.isDirty	A Boolean value indicating whether the persistent SharedObject has been modified since the last time it was stored (`true`) or not (`false`).
`SharedObject.name`	The name of a shared object.
`SharedObject.resyncDepth`	The depth that indicates when the deleted values of a shared object should be permanently deleted.
`SharedObject.version`	The current version number of a shared object.

Event summary for the SharedObject class

Event	Description
`SharedObject.handlerName`	A placeholder for an event handler; the handler is invoked when a shared object receives a broadcast message with the same name.
SharedObject.onStatus	Reports errors, warnings, and status messages for a shared object.
`SharedObject.onSync`	Invoked when a shared object changes.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/fms/2/docs/00000747.html