jscripts/opensocial/datarequest.js

   1
   2 /*
   3  * Licensed under the Apache License, Version 2.0 (the "License");
   4  * you may not use this file except in compliance with the License.
   5  * You may obtain a copy of the License at
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   9  * Unless required by applicable law or agreed to in writing, software
  10  * distributed under the License is distributed on an "AS IS" BASIS,
  11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12  * See the License for the specific language governing permissions and
  13  * limitations under the License.
  14  */
  15
  16 /**
  17  * @fileoverview Object used to request social information from the container.
  18  * This includes data for friends, profiles, app data, and activities.
  19  *
  20  * All apps that require access to people information should send a dataRequest
  21  * in order to receieve a dataResponse
  22  */
  23
  24
  25 /**
  26  * @class
  27  * <p>
  28  * Used to request social information from the container.
  29  * This includes data for friends, profiles, app data, and activities.
  30  * All apps that require access to people information
  31  * should send a DataRequest.
  32  * </p>
  33  *
  34  * <p>
  35  * Here's an example of creating, initializing, sending, and handling
  36  * the results of a data request:
  37  * </p>
  38  *
  39  * <pre>function requestMe() {
  40   var req = opensocial.newDataRequest();
  41   req.add(req.newFetchPersonRequest(
  42             opensocial.IdSpec.PersonId.VIEWER),
  43           "viewer");
  44   req.send(handleRequestMe);
  45 };
  46
  47 function handleRequestMe(data) {
  48   var viewer = data.get("viewer");
  49   if (viewer.hadError()) {
  50     <em>//Handle error using viewer.getError()...</em>
  51     return;
  52   }
  53
  54   <em>//No error. Do something with viewer.getData()...</em>
  55 }
  56 </pre>
  57  * <p>
  58  * <b>See also:</b>
  59  * <a href="opensocial.html#newDataRequest"><code>
  60  * opensocial.newDataRequest()</code></a>
  61  * </p>
  62  *
  63  * @name opensocial.DataRequest
  64  */
  65
  66 /**
  67  * Do not create a DataRequest directly, instead use
  68  * opensocial.createDataRequest();
  69  *
  70  * @private
  71  * @constructor
  72  */
  73 opensocial.DataRequest = function() {};
  74
  75
  76 /**
  77  * Get the requested objects
  78  *
  79  * @return {Array.<{key:String, request:BaseDataRequest}>}
  80  *    requestObjects An array of data requests that the container should fetch
  81  *    data for
  82  * @private
  83  */
  84 opensocial.DataRequest.prototype.getRequestObjects = function() {};
  85
  86
  87 /**
  88  * Adds an item to fetch (get) or update (set) data from the server.
  89  * A single DataRequest object can have multiple items.
  90  * As a rule, each item is executed in the order it was added,
  91  * starting with the item that was added first.
  92  * However, items that can't collide might be executed in parallel.
  93  *
  94  * @param {Object} request Specifies which data to fetch or update
  95  * @param {String} opt_key A key to map the generated response data to
  96  */
  97 opensocial.DataRequest.prototype.add = function(request, opt_key) {};
  98
  99
 100 /**
 101  * Sends a data request to the server in order to get a data response.
 102  * Although the server may optimize these requests,
 103  * they will always be executed
 104  * as though they were serial.
 105  *
 106  * @param {Function} opt_callback The function to call with the
 107  *   <a href="opensocial.DataResponse.html">data response</a>
 108  *    generated by the server
 109  */
 110 opensocial.DataRequest.prototype.send = function(opt_callback) {};
 111
 112
 113 /**
 114  * @static
 115  * @class
 116  * The sort orders available for ordering person objects.
 117  *
 118  * @name opensocial.DataRequest.SortOrder
 119  */
 120 opensocial.DataRequest.SortOrder = {
 121   /**
 122    * When used will sort people by the container's definition of top friends.
 123    * This field may be used interchangeably with the string 'topFriends'.
 124    * @member opensocial.DataRequest.SortOrder
 125    */
 126   TOP_FRIENDS : 'topFriends',
 127   /**
 128    * When used will sort people alphabetically by the name field.
 129    * This field may be used interchangeably with the string 'name'.
 130    * @member opensocial.DataRequest.SortOrder
 131    */
 132   NAME : 'name'
 133 };
 134
 135
 136 /**
 137  * @static
 138  * @class
 139  * The filters available for limiting person requests.
 140  *
 141  * @name opensocial.DataRequest.FilterType
 142  */
 143 opensocial.DataRequest.FilterType = {
 144   /**
 145    * Retrieves all friends.
 146    * This field may be used interchangeably with the string 'all'.
 147    * @member opensocial.DataRequest.FilterType
 148    */
 149   ALL : 'all',
 150   /**
 151    * Retrieves all friends that use this application.
 152    *
 153    * Note: Containers may define "use" in any manner they deem appropriate for
 154    * their functionality, and it is not expected that this field will have
 155    * the exact same semantics across containers.
 156    * This field may be used interchangeably with the string 'hasApp'.
 157    * @member opensocial.DataRequest.FilterType
 158    */
 159   HAS_APP : 'hasApp',
 160   /**
 161    * Retrieves only the user's top friends as defined by the container.
 162    * Container support for this filter type is OPTIONAL.
 163    * This field may be used interchangeably with the string 'topFriends'.
 164    * @member opensocial.DataRequest.FilterType
 165    */
 166   TOP_FRIENDS : 'topFriends',
 167   /**
 168    * Will filter the people requested by checking if they are friends with
 169    * the given <a href="opensocial.IdSpec.html">idSpec</a>. Expects a filterOptions parameter to be passed with the
 170    *    following fields defined:
 171    *  - idSpec The <a href="opensocial.IdSpec.html">idSpec</a> that each person must be friends with.
 172    * This field may be used interchangeably with the string 'isFriendsWith'.
 173    * @member opensocial.DataRequest.FilterType
 174   */
 175   IS_FRIENDS_WITH: 'isFriendsWith'
 176 };
 177
 178
 179 /**
 180  * @static
 181  * @class
 182  * @name opensocial.DataRequest.PeopleRequestFields
 183  */
 184 opensocial.DataRequest.PeopleRequestFields = {
 185   /**
 186    * An array of
 187    * <a href="opensocial.Person.Field.html">
 188    * <code>opensocial.Person.Field</code></a>
 189    * specifying what profile data to fetch
 190    * for each of the person objects. The server will always include
 191    * ID, NAME, and THUMBNAIL_URL.
 192    * This field may be used interchangeably with the string 'profileDetail'.
 193    * @member opensocial.DataRequest.PeopleRequestFields
 194    */
 195   PROFILE_DETAILS : 'profileDetail',
 196
 197   /**
 198    * A sort order for the people objects; defaults to TOP_FRIENDS.
 199    * Possible values are defined by
 200    * <a href="opensocial.DataRequest.SortOrder.html">SortOrder</a>.
 201    * This field may be used interchangeably with the string 'sortOrder'.
 202    * @member opensocial.DataRequest.PeopleRequestFields
 203    */
 204   SORT_ORDER : 'sortOrder',
 205
 206   /**
 207    * How to filter the people objects; defaults to ALL.
 208    * Possible values are defined by
 209    * <a href="opensocial.DataRequest.FilterType.html">FilterType</a>.
 210    * This field may be used interchangeably with the string 'filter'.
 211    * @member opensocial.DataRequest.PeopleRequestFields
 212    */
 213   FILTER : 'filter',
 214
 215   /**
 216    * Additional options to be passed into the filter,
 217    * specified as a Map&lt;String, Object>.
 218    * This field may be used interchangeably with the string 'filterOptions'.
 219    * @member opensocial.DataRequest.PeopleRequestFields
 220    */
 221   FILTER_OPTIONS: 'filterOptions',
 222
 223   /**
 224    * When paginating, the index of the first item to fetch;
 225    * specified as a number.
 226    * This field may be used interchangeably with the string 'first'.
 227    * @member opensocial.DataRequest.PeopleRequestFields
 228    */
 229   FIRST : 'first',
 230
 231   /**
 232    * The maximum number of items to fetch,
 233    * specified as a number; defaults to 20. If set to a larger
 234    * number, a container may honor the request, or may limit the number to a
 235    * container-specified limit of at least 20.
 236    * This field may be used interchangeably with the string 'max'.
 237    * @member opensocial.DataRequest.PeopleRequestFields
 238    */
 239   MAX : 'max'
 240 };
 241
 242
 243 /**
 244  * Creates an item to request a profile for the specified person ID.
 245  * When processed, returns a
 246  * <a href="opensocial.Person.html"><code>Person</code></a> object.
 247  *
 248  * @param {String} id The ID of the person to fetch; can be the standard
 249  *    <a href="opensocial.DataRequest.PersonId.html">person ID</a>
 250  *    of VIEWER or OWNER
 251  * @param {Map.&lt;opensocial.DataRequest.PeopleRequestFields, Object&gt;}
 252  *  opt_params
 253  *    Additional
 254  *    <a href="opensocial.DataRequest.PeopleRequestFields.html">parameters</a>
 255  *    to pass to the request; this request supports PROFILE_DETAILS
 256  * @return {Object} A request object
 257  */
 258 opensocial.DataRequest.prototype.newFetchPersonRequest = function(id,
 259     opt_params) {};
 260
 261
 262 /**
 263  * Creates an item to request friends from the server.
 264  * When processed, returns a <a href="opensocial.Collection.html">Collection</a>
 265  * &lt;<a href="opensocial.Person.html">Person</a>&gt; object.
 266  *
 267  * @param {opensocial.IdSpec} idSpec An IdSpec used to specify
 268  *    which people to fetch. See also <a href="opensocial.IdSpec.html">IdSpec</a>.
 269  * @param {Map.&lt;opensocial.DataRequest.PeopleRequestFields, Object&gt;}
 270  *  opt_params
 271  *    Additional
 272  *    <a href="opensocial.DataRequest.PeopleRequestFields.html">params</a>
 273  *    to pass to the request
 274  * @return {Object} A request object
 275  */
 276 opensocial.DataRequest.prototype.newFetchPeopleRequest = function(idSpec,
 277     opt_params) {};
 278
 279
 280 /**
 281  * @static
 282  * @class
 283  * @name opensocial.DataRequest.DataRequestFields
 284  */
 285 opensocial.DataRequest.DataRequestFields = {
 286   /**
 287    * How to escape person data returned from the server; defaults to HTML_ESCAPE.
 288    * Possible values are defined by
 289    * <a href="opensocial.EscapeType.html">EscapeType</a>.
 290    * This field may be used interchangeably with the string 'escapeType'.
 291    * @member opensocial.DataRequest.DataRequestFields
 292    */
 293   ESCAPE_TYPE : 'escapeType'
 294 };
 295
 296
 297 /**
 298  * Creates an item to request app data for the given people.
 299  * When processed, returns a Map&lt;
 300  * <a href="opensocial.DataRequest.PersonId.html">PersonId</a>,
 301  * Map&lt;String,
 302  * Object&gt;&gt; object. All of the data values returned will be valid json.
 303  *
 304  * @param {opensocial.IdSpec} idSpec An IdSpec used to specify
 305  *    which people to fetch. See also <a href="opensocial.IdSpec.html">IdSpec</a>.
 306  * @param {Array.&lt;String&gt; | String} keys The keys you want data for; this
 307  *     can be an array of key names, a single key name, or "*" to mean
 308  *     "all keys"
 309  * @param {Map.&lt;opensocial.DataRequest.DataRequestFields, Object&gt;}
 310  *  opt_params Additional
 311  *    <a href="opensocial.DataRequest.DataRequestFields.html">params</a>
 312  *    to pass to the request
 313  * @return {Object} A request object
 314  */
 315 opensocial.DataRequest.prototype.newFetchPersonAppDataRequest = function(idSpec,
 316     keys, opt_params) {};
 317
 318
 319 /**
 320  * Creates an item to request an update of an app field for the given person.
 321  * When processed, does not return any data.
 322  *
 323  * @param {String} id The ID of the person to update; only the
 324  *     special <code>VIEWER</code> ID is currently allowed.
 325  * @param {String} key The name of the key. This may only contain alphanumeric
 326  *     (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-).
 327  * @param {Object} value The value, must be valid json
 328  * @return {Object} A request object
 329  */
 330 opensocial.DataRequest.prototype.newUpdatePersonAppDataRequest = function(id,
 331     key, value) {};
 332
 333
 334 /**
 335  * Deletes the given keys from the datastore for the given person.
 336  * When processed, does not return any data.
 337  *
 338  * @param {String} id The ID of the person to update; only the
 339  *     special <code>VIEWER</code> ID is currently allowed.
 340  * @param {Array.&lt;String&gt; | String} keys The keys you want to delete from
 341  *     the datastore; this can be an array of key names, a single key name,
 342  *     or "*" to mean "all keys"
 343  * @return {Object} A request object
 344  */
 345 opensocial.DataRequest.prototype.newRemovePersonAppDataRequest = function(id,
 346     keys) {};
 347
 348
 349 /**
 350  * Creates an item to request an activity stream from the server.
 351  *
 352  * <p>
 353  * When processed, returns a Collection&lt;Activity&gt;.
 354  * </p>
 355  *
 356  * @param {opensocial.IdSpec} idSpec An IdSpec used to specify
 357  *    which people to fetch. See also <a href="opensocial.IdSpec.html">IdSpec</a>.
 358  * @param {Map.&lt;opensocial.DataRequest.ActivityRequestFields, Object&gt;}
 359  *  opt_params
 360  *    Additional parameters
 361  *    to pass to the request; not currently used
 362  * @return {Object} A request object
 363  */
 364 opensocial.DataRequest.prototype.newFetchActivitiesRequest = function(idSpec,
 365     opt_params) {};