Hi Fabio, On Jan 26, 2011, at 10:03 PM, Fabio Mancinelli wrote:
> Hi Vincent > > this is very interesting. AFAIU you are proposing a REST-like (as in > http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2). > Because of this similarity I've find quite strange to see packed in a > "string representation" that could be taken as the resource > identifier, the reference, the action, and the expected > representation. That was just one example of serialization. > For example: page:view:wiki:space1.space2.page is actually a request > for getting the content of the resource wiki:space1.space2.page > rendered in HTML with a skin applied. > > From my point of view (very HTTP-REST biased) this would have been > "translated" like > > VIEW, xwiki://wiki.space1.space2.page, {target: text/html} Yes this is exactly the same as what I was showing ;) > Where a clear separation among actions, identifiers and paramaters > (for example for selecting the representation) is more evident. > > Other examples: > > entity:view:wiki:space1.space2.page, params: context=new -> VIEW, > xwiki://wiki:space1.space2.page, {target: text/plain, params : > {context : new}} > entity:link:wiki:[email protected] -> VIEW, > xwiki://wiki:[email protected], {target: link} > > Your examples are all about VIEWing resources. But you also mentioned > creation and updating. > > Something like this could be done by issuing requests like UPDATE, > xwiki://wiki:space.page, {content-type: text/plain, payload: "new page > content"} > > What does this mean at the API level? > > Simply having something like > > execute(Action, Reference, Map<String, Object> metadata) where Action > is an enum {VIEW, UPDATE, DELETE, whatever} which consitutes the > Uniform Interface through which manipulating the resources (i.e., the > equivalent of HTTP's GET, PUT, POST DELETE or WebDav COPY, MKCOL, > etc.) What is in this enum is XWiki specific of course. > > In this way the action, the identifier and the metadata are clearly > separated and not mixed in a string representation that could be taken > for the actual identifier. I never suggested that we would manipulate data as a String! I actually proposed ResourceReference and ResourceAction in my initial proposal. Now I think we might not need a ResourceReference class and we might only need: ResourceAction { ResourceType type Action action Object reference <-- for entities would contain an EntityReference Map<String, Object> parameters } However we also need Resolvers and Serializers. For example to transform from a URL into a ResourceAction: ResourceAction ResourceActionResolver.resolve(url) And to transform from a ResourceAction to a URL: URL ResourceActionSerializer.serialize(ResourceAction) Then we still need executors. Something like: ResourceActionExecutor.execute(ResourceAction) One question we need to solve is how granular are the executor implementations. Since all data is contained inside ResourceAction we theoretically only need 1 implementation that would do some ifs on the type and the action. We could have such a generic implementation that looks up specific executors based on a hint composed of type and action (e.g. "<type>/<action>", "entity/view"). Any other ideas? I think the next step for me would be to try using that to refactor the rendering module. Thanks -Vincent > I don't know if this makes sense from your point of view. > Anyway I like a lot the direction the module is taking :) > > -Fabio > > > On Wed, Jan 26, 2011 at 8:42 AM, Vincent Massol <[email protected]> wrote: >> Hi devs, >> >> While designing the xwiki-action and xwiki-url modules I've realized that we >> need a general way to represent an xwiki resource and an action on that >> resource. >> This will allow every resource in XWiki to be addressable and offer a >> generic action mechanism. >> >> What is an xwiki resource? >> ===================== >> Examples: >> * an Entity (Document, XObject, XProperty, Attachment, etc) >> * A Page (i.e. an Entity rendered with a skin) >> * a resource file on the filesystem (image, css, js, icon, etc) >> * something on which a REST call will operate (which may or may not be an >> Entity) >> >> Note that a resource has a type, a reference and optional generic >> parameters. It's very much similar to a URI in the JDK but represented >> differently. >> >> What is an action done on a resource? >> ===================== >> Examples: >> * For an Entity: view it in XHTML (or in any other syntax) >> * For an Entity: view it with the skin applied, in XHTML (or in any other >> syntax) >> * Generate a URL for it >> * Create a link to it >> * For an Entity: Create it, modify it, delete it >> >> Where would it be used: >> ===================== >> Examples: >> * To transform any XWiki URL into a resource object. Any XWiki URL would be >> transformed internally into a resource. Note: The current XWikiURL class >> located in the xwiki-url module would disappear >> * In the Rendering to represent the reference of a link or an image. Ex: >> [[label>>reference]]. We currently have a ResourceReference class that would >> be removed and replaced by the new generic resource class. >> * More generically Resource and Resource Actions will be used at entry >> points of XWiki and internally XWiki will only manipulate Resources. >> >> String representation: >> ===================== >> <resource type>:<action>:<resource reference> >> >> Examples: >> ===================== >> * view a document with skin applied >> page:view:wiki:space1.space2.page >> <==> ViewAction >> >> * view a document >> entity:view:wiki:space1.space2.page >> params: context=new >> <==> No equiv or {{include document="wiki:space1.space2.page" >> context="new"/}} >> >> ex: link to attachment >> entity:link:wiki:[email protected] >> <==> [[attach:wiki:[email protected]]] >> >> ex: link to a document >> entity:link:wiki:space1.space2.page >> <==> [[doc:wiki:space1.space2.page]] >> >> ex: view icon >> icon:view:accept >> <==> image:icon:accept >> >> ex: view image stored in document >> entity:view:wiki:[email protected] >> <==> image:doc:wiki:[email protected] >> >> ex: view image located at external URL >> url:view:http://server/my.png >> <==> image:url:http://server/my.png >> >> API >> === >> >> * ResourceReference >> * ResourceAction (extends ResourceReference by adding an action field) >> * ResourceReferenceSerializer >> * ResourceReferenceResolver >> * ResourceExecutor(ResourceReference). Hint = <executor type>/<resource >> type>/<resource action> >> >> Example: View "entity:view:wiki:[email protected]" in XHTML >> Algorithm: >> - lookup ResourceExecutor (hint = "xhtml/entity/view") >> - cast ref = ResourceReference.getReference() to EntityReference >> - if ref.type == ATTACHMENT >> - get attachment URL >> => <img src="..../my.png"/> >> >> Example: Generate URL for "entity:view:wiki:[email protected]" >> Algorithm: >> - lookup ResourceExecutor (hint = "url/entity/view") >> - cast ref = ResourceReference.getReference() to EntityReference >> => http://wiki/xwiki/bin/view/space/page/my.png >> >> OR simply: >> >> ResourceExecutor(ResourceAction). Hint = <executor type> >> >> ex: "xhtml", "url", etc. >> >> And it's up to the executor to have sub components for the various actions, >> resource types.... >> >> Conclusion >> =========== >> >> The API is not completely finished and I'd need to explore it (ie start >> implementing it) to refine it. >> Right now I'd just like to discuss whether you see the idea as interesting >> and whether I should start spending some time working on it. >> >> I'll post refinements as I progress. >> >> Thanks >> -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
