StateManager class

Methods Events

The StateManager lets you work with the state of a session or archive. You obtain a StateManager object by calling the getStateManager() method of a Session object or of an Archive object. You can use the StateManager object for a session to set the state of a session and to add event listeners for state changes. You can use the StateManager object for an archive to add event listeners for state changes. You cannot set state data in an archive; the archives state data is a recording of state data in the session it records.

Note: The Session and Archive State API is in beta testing. We welcome your comments.

A session's state is a set of key-value pairs. When you call the set() method, you pass either a pair of strings — a key and a value — or you pass in an Object that contains a set of key-value pairs. For example, the following code sets the "foo" key to "bar":

var stateManager = session.getStateManager();
stateManager.set("key", "bar");

(The example assumes that the session variable contains a TokBox Session object that you have connected to.)

The following code sets multiple properties at once:

var stateManager = session.getStateManager();
var newStateValues = {backgroundColor: "FFCC00", caption: "My dog has fleas."};
stateManager.set(newStateValues);

When a new key-value pair (or set of pairs) is set, the StateManager object dispatches a changed event (defined by the StateChangedEvent class). The StateManager object also dispatches an event for each key-value pair change, and the type property of the event is changed:keyName, where "keyName" is the name of the key. For example, the following code sets up two event listeners: one for all changes to state changes and one for all changes to the foo key only:

var stateManager = session.getStateManager();
stateManager.addEventListener("changed", stateChangedHandler);
stateManager.addEventListener("changed:foo", fooStateChangedHandler);

function stateChangedHandler(event) {
    for (key in event.changedValues) {
        alert("Changed state. Key: " + key + ". Value: " + event.changedValues[key]);
    }
}

function fooStateChangedHandler(event) {
    alert("Foo changed state. Value: " + event.changedValues["foo"]);
}

Set a key to null to delete it from the state:

var stateManager = session.getStateManager();
stateManager.set("foo", null);

Note that the changed values are defined in the changedValues property of the StateChangedEvent object. For the initial event dispatched, the changedValues property contains current state. For a changed event, it contains the entire current state, with a key-value pair for each property in the state. For a changed:keyName event, the initial event's changedValues property contains one property, pertaining to the specific key's (and the value is set to null if the key is not set in the state). An initial event is dispatched to each unique event listener you register, and the event's changedValues property reflects the state at the time you add the event listener.

For subsequent events (after the initial event), the changedValues property contains key-value pairs for changed properties in the state. For a changed:keyName event, the changedValues property contains one property, for the specific key, and the event is only dispatched when that key's value changes. A value is set to null when a key is deleted.

When a key name begins with moderator_ or publisher_, the property can only be set (or changed) by a client that has a token that has been assigned the role of moderator or publisher. However any client can subscribe to any state property. For example, if a client that is not assigned the role of moderator calls the following lines of code, the StateManager object dispatching a changeFailed event (defined by the ChangeFailedEvent class):

var stateManager = session.getStateManager();
stateManager.set("moderator_foo", "bar");

There are other limitations when calling the set() method. Failure to conform to these limitations results in the StateManager object dispatching a changeFailed event:

• Keys must be 100 characters or less, and they cannot contain spaces.
• Value must be 1000 characters or less. Values must be String objects. Setting a value to null deletes the key.
• You are limited to setting up to 20 keys.
• You cannot set the state of an archive (by calling the set() method of the StateManager object obtained by calling the getStateManager() method of an Archive object).

var stateManager = session.getStateManager();
stateManager.set("key", "bar");

var stateManager = session.getStateManager();
var newStateValues = {backgroundColor: "FFCC00", caption: "My dog has fleas."};
stateManager.set(newStateValues);

var stateManager = session.getStateManager();
				stateManager.set("moderator_foo", "bar");