Thanks for checking these in cassie, but I'm not sure they're named appropriately. It's fine to uppercase them and call them README's but I think you've mislabeled them from the original names in https://issues.apache.org/jira/browse/SHINDIG-270
trunk/java/social-api/RESTFUL-DEBUGGING-README This is a dispatching walkthrough. It doesn't say how to debug. There's one line that mentions a decent place for a breakpoint but that's really besides the point. It's a walkthrough of how request dispatching is done. trunk/java/social-api/RESTFUL-WIRE-FORMAT-README This also doesn't make sense to me. It's a walkthrough of how requests are processed and turned into responses in the server. If you want one readme for the whole abdera-based server, this might but a decent name for the file, but in that case, you should put the content of both of my walkthroughs into this one. I noticed that there's a JSON-WIRE-FORMAT-README and I'm guessing that you moved your docs to that one as we now have two codebases in source tree. I suppose you need to make sure people don't get confused with the abdera docs if they're using the GadgetDataServlet but why not just call it the GadgetDataServlet readme. I also don't think RESTFUL versus JSON is a natural way to break up the documentation since there is really a json and xml wire format and one codebase will serve in the future. davep On Mon, May 26, 2008 at 7:49 AM, <[EMAIL PROTECTED]> wrote: > Author: doll > Date: Mon May 26 07:49:08 2008 > New Revision: 660204 > > URL: http://svn.apache.org/viewvc?rev=660204&view=rev > Log: > SHINDIG-270 > Text from David Primmer. Committing some README files for the social code. > Once we get rid of the json wire format we can clean up the file names a bit > because they are a little long, but I think this is fine for now. > > > Added: > incubator/shindig/trunk/java/social-api/JSON-WIRE-FORMAT-README > - copied, changed from r660183, > incubator/shindig/trunk/java/social-api/README > incubator/shindig/trunk/java/social-api/RESTFUL-DEBUGGING-README > incubator/shindig/trunk/java/social-api/RESTFUL-WIRE-FORMAT-README > Removed: > incubator/shindig/trunk/java/social-api/README > > Copied: incubator/shindig/trunk/java/social-api/JSON-WIRE-FORMAT-README (from > r660183, incubator/shindig/trunk/java/social-api/README) > URL: > http://svn.apache.org/viewvc/incubator/shindig/trunk/java/social-api/JSON-WIRE-FORMAT-README?p2=incubator/shindig/trunk/java/social-api/JSON-WIRE-FORMAT-README&p1=incubator/shindig/trunk/java/social-api/README&r1=660183&r2=660204&rev=660204&view=diff > ============================================================================== > --- incubator/shindig/trunk/java/social-api/README (original) > +++ incubator/shindig/trunk/java/social-api/JSON-WIRE-FORMAT-README Mon May > 26 07:49:08 2008 > @@ -11,7 +11,7 @@ > > > > -Explanation of the current setup of the OpenSocial server code > +Explanation of the current setup of the json wire format java code > =========================================================================== > > From within java/social-api/src/main/java/org/apache/shindig/social/... > > Added: incubator/shindig/trunk/java/social-api/RESTFUL-DEBUGGING-README > URL: > http://svn.apache.org/viewvc/incubator/shindig/trunk/java/social-api/RESTFUL-DEBUGGING-README?rev=660204&view=auto > ============================================================================== > --- incubator/shindig/trunk/java/social-api/RESTFUL-DEBUGGING-README (added) > +++ incubator/shindig/trunk/java/social-api/RESTFUL-DEBUGGING-README Mon May > 26 07:49:08 2008 > @@ -0,0 +1,59 @@ > +Installing and running the server > +============================================ > +Please see BUILD-JAVA in the base project directory for information. > + > +Once running, this url http://localhost:<port>/social/rest will accept POST > requests > + that match the OpenSocial RESTFUL apis. In order to see this code in > action > + follow the README in java/server. > + > + > +For more information, see http://incubator.apache.org/projects/shindig.html > + > + > +A walkthrough of dispatching requests in Shindig's OpenSocial RESTful spec > impl > +============================================================================ > + > +If you want to debug this process, a good place to put a breakpoint is in > +AbderaServlet.service. > + > +AbderaServlet.service starts everything off when ServletRequestContext object > +is built and all Abdera-specific processing starts. Before this we're just > +doing servlet-related tasks and dependency injection. > + > +As part of ServletRequestContext being built, one of the last things done is > +initTarget, which is really provider.resolveTarget. Since our provider > +specifies we're using the RouteManager as our TargetResolver, this is the > +RouteManager's resolve method. > + > +When the server is started, the routes are initialized. The RouteManager of > +SocialApiProvider is acutally a SocialRouteManager. This subclass just wrapps > +RouteManager.addRoute for convinience. Route patterns and names are defined > in > +the enum RequestUrlTemplate. In the provider, a bunch of routes are mapped to > +their corresponding targetTypes and corresponding CollectionAdapters. > + > +RouteManager.resolve, when called, looks up the request path and matches it > in > +the targets that have been specified in the RouteManager. If it matches, it > +puts a Target object in the request object. It also looks up the > +CollectionAdapter that we're going to use to service the request in the > +route2ca map and puts it in the COLLECTION_ADAPTER_ATTRIBUTE of the request > +object. > + > +Now the request object is created and AbderaServlet.service goes on to > process > +the request in AbsractProvider.process: > +- gets the already resolved target from the request object > +- gets the HTTP method and targetType, usually COLLECTION or ENTRY > +- gets CollectionAdapter from the WorkspaceManager via getCollectionAdapter > + - the WorkspaceManager looks up the CollectionAdapter in the request > object's > + COLLECTION_ADAPTER_ATTRIBUTE > + > +At this point the AbsractProvider.process method looks at the target type and > +and calls the appropriate process* method. This is the meat of the server's > +dispatch logic. processCollection is called for TargetType.TYPE_COLLECTION. > +Inside of processCollection, if it's a GET, then getFeed is called for the > +specified CollectionAdapter. processCollection also uses the MimeType of the > +request to determine if it needs to do Media handling. > + > +If the method is PUT and targetType is ENTRY, postEntry is called in the > +CollectionAdapter. This is where the code of the CollectionAdapters takes > over. > +It should have all the info necessary to get the data for the response, build > +the response document and hand it off. > > Added: incubator/shindig/trunk/java/social-api/RESTFUL-WIRE-FORMAT-README > URL: > http://svn.apache.org/viewvc/incubator/shindig/trunk/java/social-api/RESTFUL-WIRE-FORMAT-README?rev=660204&view=auto > ============================================================================== > --- incubator/shindig/trunk/java/social-api/RESTFUL-WIRE-FORMAT-README (added) > +++ incubator/shindig/trunk/java/social-api/RESTFUL-WIRE-FORMAT-README Mon > May 26 07:49:08 2008 > @@ -0,0 +1,130 @@ > +Installing and running the server > +============================================ > +Please see BUILD-JAVA in the base project directory for information. > + > +Once running, this url http://localhost:<port>/social/rest will accept POST > requests > + that match the OpenSocial RESTFUL apis. In order to see this code in > action > + follow the README in java/server. > + > + > +For more information, see http://incubator.apache.org/projects/shindig.html > + > + > + > +A walkthrough of request processing in the Shindig's OpenSocial RESTful spec > impl > +=========================================================================== > + > +The following is a simple walkthrough of the handling of GET requests for the > +AbstractSocialEntityCollectionAdapter. This continues request processing from > +the dispatching walkthrough. > + > +AbstractEntityCollectionAdapter, the superclass, is the fullest > implementation > +of the server framework available but heavily biases toward ATOM content. By > +extending this class it becomes easy to build Collections which are backed > by a > +set of entities - such as a database row, domain objects, or files. It has > two > +content management systems, one for working with data that can be put into an > +XML document and one for media. Most of the XML processing is used when > dealing > +with Media entries, only switching to special media handling routines when > +populating the content element of Entries. > + > +This walkthrough assumes the use of the abstract base class > +AbstractSocialEntityCollectionAdapter and a CollectionAdapter extending it. > + > +AbstractCollectionAdapter > + AbstractEntityCollectionAdapter > + AbstractSocialEntityCollectionAdapter > + ActivityAdapter | PersonAdapter | GroupAdapter | AppdataAdapter > + > + > +The CollectionAdapter can be very thin and deal only with interaction with > the > +data model and some metadata. The CollectionAdapter also handles one or more > +valid URL patterns in the spec. So /people/{uid}/@all is a Collection of all > +people connected to user {uid} and the PersonAdapter adapts this person > entity. > +Each URL pattern will only deal with one fundamental resource type in Shindig > +so this mapping should suffice. > + > + > +**** > + > +The dispatch system in AbstractProvider hands off the request to the > +appropriate CollectionAdapter and calls the getEntry or getFeed method based > on > +whether the targetType is COLLECTION or ENTRY. > + > +The primary difference between getFeed and getEntry is that getFeed builds a > +Feed Document and then depending on the contents of the underlying > collection, > +it builds a series of Entry objects that are added to the Feed before it is > +returned as a response. The mechanisms for building the Entry objects are the > +same whether they are called purely for getEntry or if they are called as > part > +of a chain of getEntry calls when generating a feed. > + > +**** > + > +getFeed > + > +The first thing that getFeed does is call createFeedBase, which creates a new > +FOM* Feed object and sets it's properties such as Id, Title, Updated and > +Author. Next, addFeedDetails is called to add the selected entries to the > Feed > +document. It does this by calling getEntries. getEntries is abstract and must > +by implemented by the concrete adapter. It gets the listing of entries > +requested. These are the native pojos (like a person or activity object) that > +will be represented in the feed. It's probably best to describe these as > +"entities" rather than the rather ATOMish "entry" and this is how they're > +referenced in variables where possible. > AbstractSocialEntityCollectionAdapter > +tries to use argumetns that are named "entity" when dealing with a native > data > +source so as to disabmiguate from the Entry FOM objects that are passed > around > +in similar method calls. > + > +As the list of entry objects (our underlying set of entities as returned from > +our model) is iterated over, addFeedDetails continues to build the FOM Feed > +object by appending an Entry FOM object. It populates that FOM object by > adding > +the IRI of the entry with getFeedIriForEntry and addEntryDetails. > +getFeedIriForEntry is really a call through to the subclassed > +CollectionAdapter's getHref method. > + > +addEntryDetails does something similar to createFeedBase: it sets the ID, > Title > +and Updated, etc for the Entry FOM object. Once back in addFeedDetails, there > +is a switch on whether we're dealing with a media item or not, and if so it > +calls addMediaContent, otherwise it calls the XML addContent method. > + > +addContent simply takes the Entry FOM object and the actual pojo entity and > +adds the results of getContent on the entity to the content element. > getContent > +is abstract and must be implemented in the subclassed CollectionAdapter. This > +is the place where the datamodel access happens. > + > +At this point, the FOM object is ready for output (or there's a problem and > +it's ready to puke). buildGetFeedResponse creates the ResponseContext for a > GET > +feed request. By default, a BaseResponseContext is returned. The Etag > header > +will be set and the HTTP server takes over from here to do the writing to > +output. At this point, the request can be serialized as XML, or a the shindig > +version of JSON. > + > +**** > + > +getEntry > + > +getEntry first calls getEntryFromCollectionProvider, which tries to get the > ID > +for the entity we're getting by calling getResourceName. This method, by > +default, simply pulls the last segment of the path but could be customized to > +be less brittle and deal with something like /people/{uid}/@self by simply > +getting the "uid" parameter from the current Route object. With this ID, > +another getEntry is called, this time to an abstract method that must be > +implemented in the CollectionAdapter. This getEntry is really a getEntity, > as I > +mentioned before, since this is doing the data access to your model and isn't > +an ATOM method per-se. > + > +Once this Entry object (or entity) is returned another > +getEntryFromCollectionProvider is called, this time with the pojo and the > Feed > +IRI. This time it actually creates a FOM Entry object and in turn calls > +buildEntry. (We've got a lot of indirection here....). buildEntry builds the > +entry from the entity pojo by calling addEntryDetails as above in the feed > +processing flow. And, similarly to the feed flow, the last step is > +buildGetEntryResponse, which is similar to buildGetFeedResponse, but it does > +one extra step, which is it finds the parent collection of the entry with > +createFeedBase and calls setSource to add a source element containing the > +minimal feed doc that the entry came from. > + > +Output is the same as above for feeds. > + > + > + > +**FOM stands for Feed Object Model and is a ATOM RFC compliant Java Object. > > >
