Server-Side Communication ActionScript > SharedObject.get

SharedObject.get

Availability

Flash Communication Server MX.

Usage

SharedObject.get(name, persistence [, netConnection])

Parameters

name Name of the shared object instance to return.

persistence A Boolean value: true for a persistent shared object; false for a nonpersistent shared object. If no value is specified, the default value is false.

netConnection A NetConnection object that represents a connection to an application instance. You can pass this parameter to get a reference to a shared object on another server or a shared object that is owned by another application instance. All update notifications for the shared object specified by the name parameter are proxied to this instance, and the remote instance notifies the local instance when a persistent shared object changes. The NetConnection object that is used as the netConnection parameter does not need to be connected when you call SharedObject.get. The server connects to the remote shared object when the NetConnection state changes to connected. This parameter is optional.

Returns

A reference to a shared object instance.

Description

Static method; returns a reference to a shared object instance. To perform any operation on a shared object, the server-side script must get a reference to the named shared object using the SharedObject.get method. If the object requested is not found, a new instance is created.

There are two types of shared objects, persistent and nonpersistent, and they are in separate name spaces. This means that a persistent and a local shared object can have the same name, but they are two distinct shared objects. Shared objects are scoped to the name space of the application instance and are identified by a string name. The shared object names should conform to the URI specification.

You can also call SharedObject.get to get a reference to a shared object that is in a name space of another application instance. This instance can be on the same server or on a different server and is called a proxied shared object. To get a reference to a shared object from another instance, create a NetConnection object and use the NetConnection.connect method to connect to the application instance that owns the shared object. Pass the NetConnection object as the netConnection parameter of the SharedObject.get method. The server-side script must get a reference to a proxied shared object before there is a request for the shared object from any client. To do this, call SharedObject.get in the application.onAppStart handler.

If you call SharedObject.get with a netConnection parameter and the local application instance already has a shared object with the same name, the shared object converts to a proxied shared object. All shared object messages for clients connected to a proxied shared object are sent to the master instance.

If the connection state of the NetConnection object that was used as the netConnection parameter changes state from connected to disconnected, the proxied shared object is set to idle and any messages received from subscribers are discarded. The NetConnection.onStatus handler is called when a connection is lost. You can then re-establish a connection to the remote instance and call SharedObject.get, which changes the state of the proxied shared object from idle to connected.

If you call SharedObject.get with a new NetConnection object on a proxied shared object that is already connected and if the URI of the new NetConnection object doesn't match the current NetConnection object, the proxied shared object unsubscribes from the previous shared object, sends a "clear" event to all subscribers, and subscribes to the new shared object instance. When a subscribe to a proxied shared object is successful, all subscribers are reinitialized to the new state. This process lets you migrate a shared object from one application instance to another without disconnecting the clients.

Updates received by proxied shared objects from subscribers are checked to see if the update can be rejected based on the current state of the proxied shared object version and the version of the subscriber. If the change can be rejected, the proxied shared object doesn't forward the message to the remote instance; the reject message is sent to the subscriber.

The corresponding client-side ActionScript method is SharedObject.getRemote.

Example

This example creates a shared object named foo inside the function onProcessCmd. The function is passed a parameter, cmd, that is assigned to a property in the shared object.

function onProcessCmd(cmd){
	// insert code here
	var shObj = SharedObject.get("foo", true);
	propName = cmd.name;
	shObj.getProperty (propName, cmd.newAddress);
} 

The following example uses a proxied shared object. A proxied shared object resides on a server or in an application instance (called master) that is different than the server or application instance that the client connects to (called proxy). When the client connects to the proxy and gets a remote shared object, the proxy connects to the master and gives the client a reference to this shared object. The following code is in the main.asc file:

application.appStart = function() {
     nc = new NetConnection();
     nc.connect("rtmp://" + master_server + "/" + master_instance);
     proxySO = SharedObject.get("myProxy",true,nc);   
		// Now, whenever the client asks for a persistent 
		// shared object called myProxy they will receive myProxy
		// shared object from the master_server/master_instance
};