svn commit: r640868 - /incubator/shindig/trunk/java/gadgets/src/main/java/org/apache/shindig/social/README

[do...@apache.org]

Author: doll
Date: Tue Mar 25 08:55:22 2008
New Revision: 640868

URL: http://svn.apache.org/viewvc?rev=640868&view=rev
Log:
Added a README for the java social directory that starts to outline how things work, including the wire format, how to use the Service interfaces etc. 

It probably needs tons more info, so feel free to contribute :)



Added:
    incubator/shindig/trunk/java/gadgets/src/main/java/org/apache/shindig/social/README

Added: incubator/shindig/trunk/java/gadgets/src/main/java/org/apache/shindig/social/README
URL: http://svn.apache.org/viewvc/incubator/shindig/trunk/java/gadgets/src/main/java/org/apache/shindig/social/README?rev=640868&view=auto
==============================================================================
--- incubator/shindig/trunk/java/gadgets/src/main/java/org/apache/shindig/social/README (added)
+++ incubator/shindig/trunk/java/gadgets/src/main/java/org/apache/shindig/social/README Tue Mar 25 08:55:22 2008
@@ -0,0 +1,134 @@
+Using the GadgetDataServlet and integrating with Shindig's OpenSocial code
+===========================================================================
+
+=== Directories:
+  *.java - classes necessary for handling all json data requests made from
+      javascript. These calls can be the OpenSocial spec defined ones
+      (handled by the opensocial directory) or any custom calls that the
+      javascript needs the server to handle (see the
+      samplecontainer/StateFileDataHandler for an example)
+  opensocial/* - provides the OpenSocialDataHandler and all dependant OpenSocial
+      related classes
+  samplecontainer/* - provides the SampleContainer implementation that Shindig
+      uses by default. If you are creating your own container it is best to
+      model your code after this directory. If you wish to extend OpenSocial
+      with additional data requests in a spec compliant way, follow the
+      StateFileDataHandler example.
+
+
+
+=== Main servlet: GadgetDataServlet
+
+This servlet handles all requests to the socialdata url. These
+requests are expected to post two items of information, "st" which should map to
+a gadget token and "request" which should be stringified json.
+
+The "request" json should be an array of objects which all have a "type" field.
+This type field is used to select the right GadgetDataHandler implementation to
+process the request object. The data handler will be passed all of the fields in
+the request object.
+
+Here is an example of a valid request:
+[{type : "FETCH_PEOPLE", idSpec : "VIEWER"},
+ {type : "CUSTOM_TYPE", param1 : "value1", param2 : "value2"}]
+
+This is an example of an invalid request:
+[{idSpec : "VIEWER"},
+ {param1 : "value1", param2 : "value2"}]
+The items do not have type values and so can't be processed.
+
+
+The default setup of Shindig uses the code in social/samplecontainer to process
+all of the requests that come in. This code has one custom handler,
+StateFileDataHandler, and also uses the standard OpenSocialDataHandler.
+
+
+
+=== OpenSocialDataHandler: The wire format
+
+The OpenSocialDataHandler handles all json request objects with the following
+types:
+    FETCH_PEOPLE,
+    FETCH_PERSON_APP_DATA, UPDATE_PERSON_APP_DATA,
+    FETCH_ACTIVITIES, CREATE_ACTIVITY
+
+json details:
+
+-------- Note: This is all subject to change! More information below. --------
+
+FETCH_PEOPLE
+  incoming json:
+   {type : "FETCH_PEOPLE",
+    idSpec : <opensocial idSpec>,
+    profileDetail : <list of profile fields>,
+    sortOrder : <opensocial.DataRequest.SortOrder>,
+    filter : <opensocial.DataRequest.FilterType>,
+    first : <int>,
+    max : <int>}
+  json produced:
+   {items: <array of objects compatible with JsonPerson>,
+    offset: <int>,
+    totalSize: <int>}
+
+FETCH_PERSON_APP_DATA
+  incoming json:
+   {type : "FETCH_PERSON_APP_DATA",
+    idSpec : <opensocial idSpec>,
+    keys : <array of strings>}
+  json produced:
+   <an object with the format: Map<PersonId, Map<Key, Value>> - matches the
+   OpenSocial spec exactly>
+
+UPDATE_PERSON_APP_DATA
+  incoming json:
+   {type : "UPDATE_PERSON_APP_DATA",
+    idSpec : <opensocial idSpec>,
+    key : <string>,
+    value : <string>}
+  json produced:
+   none
+
+FETCH_ACTIVITIES
+  incoming json:
+   {type : "UPDATE_PERSON_APP_DATA",
+    idSpec : <opensocial idSpec>}
+  json produced:
+   {<array of objects compatible with JsonActivity>}
+
+CREATE_ACTIVITY
+  incoming json:
+   {type : "CREATE_ACTIVITY",
+    idSpec : <opensocial idSpec>,
+    activity : <json compatible with
+        gadgets.json.stringify(opensocial.Activity)>}
+  json produced:
+   none
+
+
+The default Shindig setup receives its requests from
+features/opensocial-0.7/jsoncontainer. If you use this javascript class your
+json format will always match the server exactly. This wire format is always
+subject to change as it is solely for the purpose of communicating between the
+Shindig javascript and the Shindig java classes. Shindig will always be
+compatible with itself and will not commit to staying constant for outside
+dependencies.
+
+If you wish to use Shindig to support OpenSocial it is highly reccomended that
+you implement the Service interfaces. This will isolate you from json wire
+format changes.
+
+If you do not wish to use Shindig to support OpenSocial, you should probably be
+looking at the OpenSocial RESTful apis instead of this README:
+http://code.google.com/apis/opensocial/docs/dataapis.html
+
+
+
+=== OpenSocialDataHandler - The service interfaces
+
+In order to determine where the data for each of these requests is fetched from
+the samplecontainer code provides implementations of the three OpenSocial
+services: ActivitiesService, DataService, and PeopleService in the
+samplecontainer/Basic*Service files.
+
+You should provide your own implementations of these files to fetch data from a
+database or an existing service, or some other storage mechanism.
\ No newline at end of file