Changing the Application State
But where did the application load its data from? Normally, an application would query its own container (orkut, MySpace, etc.) to access information relative to the user that is accessing the application and his friends.
In the current development setup, Shindig uses an XML file that describes the application state. Here is the state (state-basic.xml) used for the basic application just created:
<?xml version="1.0" encoding="UTF-8"?>
<person id="john.doe" name="John Doe" gender="M">
<person id="jane.doe" name="Jane Doe" phone="867-5309" gender="F">
<person id="george.doe" name="George Doe" gender="M">
<person id="maija.m" name="Maija Meikäläinen" gender="F">
<person id="riccardo.govoni" name="Riccardo G" gender="M" >
If you check the parameters used to load the application in Figure 4 again, you will notice that you are instructing the container to use the state-basic.xml file to load application state and that you are impersonating the user john.doe when accessing the application. This explains the source of the data. You can customize the XML file to verify how the application responds to different setups.
Application states can contain much more information than what is shown in state-basic.xml above, including custom data for each user and activities streams. Refer to the Shindig documentation for further info.
More OpenSocial Entities, Persistence, and Activities
So far, you have gotten an overview of the APIs that deal with people and relationships. Two further areas remain to be explored: persistence and activities.
In terms of persistence support, the OpenSocial model allows for custom data to be saved on a per-application, per-user basis. Each OpenSocial application has an associated persistent store (managed by the container) that it can use to write and read custom data. Applications cannot access data associated to different applications, preserving a compartmentalized environment. Applications have write permission only on VIEWER data: they can write data only when associated to the current user. However, they have read permission both on VIEWER data and other entities, such as VIEWER_FRIENDS. This means that applications can collect their data across networks of users--this represents the true value of a social application. For example, the application you will explore shortly allows each user to store his favorite movies, but at the same time collects the same preferences from the cluster of friends using the same application. The result is aggregated movie reports representing the preferences of the entire network of friends.
The following two API functions are used to store and read data:
// assume req is a DataRequest object.
// data store request
'VIEWER', key, value));
// data fetch request
The req.newUpdatePersonAppDataRequest() function stores custom data. It accepts only the 'VIEWER' identifier. It then accepts a key and value for the data to be stored. Values can be strings only, so JSON should be used to handle complex objects. The OpenSocial APIs include the gadget.json.parse() and gadgets.json.stringify() utility functions to deal with bidirectional JSON conversion.
After storing data, you can fetch them using req.newFetchPersonAppDataRequest(). This call accepts wider identifiers, such as VIEWER_FRIENDS, the key that points to the data to be retrieved, and the key that will refer to them in the response returned from the data request (friendsdata in the example).
Lastly, OpenSocial applications can deal with activities streams as well. You can publish activities associated to the user and read from activities streams from his network of friends using the following two additional API functions:
// publish activity
var activity = opensocial.newActivity(params);
opensocial.requestCreateActivity(activity, priority, callback);
// read activities
// req is a DataRequest object
The same rules described previously about read and write permissions apply. Further information about activities are available in the OpenSocial documentation.