26 Jan
2011
26 Jan
'11
10:03 p.m.
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_…).
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.
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}
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:space.page@my.png -> VIEW,
xwiki://wiki:space.page@my.png, {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 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 <vincent(a)massol.net> 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:space.page@my.png
<==> [[attach:wiki:space.page@my.png]]
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:space.page@my.png
<==> image:doc:wiki:space.page@my.png
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:space.page@my.png" 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:space.page@my.png"
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
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
