Session Storage

Session storage is a key/value repository that exists on a basis of one per client session; each client connected to a service instance gets its own private data store synchronized with the service.

This feature can prove especially useful in collaboration scenarios, as provides a means to ensure collaboration participants do not gain access to sensitive data intended only for the host.

 

The concept of session storage is similar to application state, but there are some significant differences:

  • application state is the same on the service and all connected clients, it cannot be partitioned between a host and collaboration participants,
  • the session storage data store has a flat structure, unlike application state which stores information in an XML tree hierarchy.

For storing and sharing binary data, see Resource Manager.

Overview

Session storage functionality is provided by the service-side SessionStorageManager class, and the client-side SessionStorage class.

The service instance sets up a private data store for each client that connects to it, and each client can only interact with the specific data store that the service provided for it.

There are three main operations:

  • writing new entries (setValue)
  • reading existing entries (getValue)
  • registering change handlers for responding to changes in values (addValueChangedHandler)

The methods on the service are essentially the same as on the client; however, because the service can access the data stores for each connected client, there are differences:

  • The sessionId is a required parameter for service-side methods, as it is necessary to specify to which data store an operation applies.
  • A service-only method, setValueForAllSessions, can be used to write an entry in the data stores for all clients connected to the same service instance, thereby making the entry accessible to every participant in a collaboration setting.

Read/Write Operations

To write a key/value pair to the data store, you use setValue; to read the value of an existing key, you use getValue.

Session storage can store and transmit the full range of unicode characters (including extended characters like emojis). The only exception is the Flex client API, which supports unicode in general but not extended characters like emojis.

Setting a Value

In the example below, we are setting an entry whose key is labeled "secret" and contains the string value "Only I know".

C++

m_stateManager->SessionStorageManager().SetValue(sessionId, "secret", "Only I know");

Java

stateManager.getSessionStorageManager().setValue(sessionId, "secret", "Only I know");

HTML5

pureweb.getClient().getSessionStorage().setValue('secret', 'Only I know');				

Android

The third parameter is the suppressHandlers parameter.

framework.getWebClient().getSessionStorage().setValue("secret", "Only I know", false);

Getting a Value

In this example, we are getting the value for the previously set key labeled "secret".

C++

m_stateManager->SessionStorageManager().GetValue(sessionId, "secret");

Java

String value = stateManager.getSessionStorageManager().setValue(sessionId, "secret");

HTML5

var value = pureweb.getClient().getSessionStorage().getValue('secret'));				

Android

String value = framework.getWebClient().getSessionStorage().getValue("secret");

Registering Change Handlers

Change handlers allow the application to respond when a change occurs in a particular key within session storage.

In the snippets below, whenever the value for the "secret" key changes, the service application will execute a developer-defined function labeled OnSecretChanged.

C++

m_stateManager->SessionStorageManager().AddValueChangedHandler(sessionId, "secret", Bind(this, &MyApp::OnSecretChanged));

Java

stateManager.getSessionStorageManager().addValueChangedHandler(sessionId, key, new EventHandler<SessionStorageChangedEventArgs>()

HTML5

pureweb.getClient().getSessionStorage().addValueChangedHandler("secret", myapp.OnSecretChanged);

Android

framework.getWebClient().getSessionStorage().addValueChangedHandler(key, new EventHandler<SessionStorageChangedEventArgs>()

The function that handles the change event (in this example, OnSecretChanged), provides a SessionStorageChangedEventArgs argument. This argument contains information about the change that triggered the event, including its type (such as insertion or deletion), the key that changed and the new value.

You can also unregister these handlers using removeValueChangedHandler and removeAllValueChangedHandlers.

Keeping Track of Sessions

While working with session storage, your service may need to know which client sessions are connected at any point in time, and which is the host in a collaboration scenario.

To keep track of which client sessions are connected, you would register listeners for session connection and disconnection events. These events are raised by the service-side SessionManager class.

In the example below, we are registering for the session connected event:

C++

sessionManager.addSessionConnectedHandler(new SessionConnectedHandler());

You could then write an event handler that responds to the event as needed.

To determine which client session is the collaboration host, you use methods from the client-side CollaborationManager class. See Using IDs to Manage Collaboration on the Client.

Other Session Storage Methods

The APIs provide more methods for managing session storage than those discussed here. For example, you can check if a given key exists in a specific client session, which client session data stores contain a specific key, and so on.

For more information, see the PureWeb API reference for your programming language.