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...). 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 for refactoring the rendering module and see how it goes. 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

On Feb 17, 2011, at 10:53 AM, Fabio Mancinelli wrote:

Hi Vincent,

On Wed, Feb 16, 2011 at 7:27 PM, Vincent Massol <[email protected]> wrote:

...

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...). 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)

Actually this was my point. Imho, URL are only for identifying resources (i.e., they're actually entity references).

Not really, the Action is part of it. Imagine the following scenarios: * A standard HTTP request to http://.../xwiki/bin/view/Space/Page ==> this is a "view" action * A GET REST call http://...rest/Space/Page ==> this is a "view" action * A Daemon thread wanting to execute the view action on some resource ==> this is a "view" action There are multiple ways to describe both a Resource and the action to perform on it and the role of the Resolver is to transform all these manners into a common ResourceAction object that can be handed similarly by all XWiki code.

Serializing an action into an URL is wrong because you will mix the entity with the operation in something that semantically is just an "identifier".

No it's not wrong IMO. REST is pretty limited since it can only have the following actions: GET, UPDATE, DELETE. But we do need a lot more actions than that (and you'll need to add them in the URL anyway based on a combination of GET/UPDATE/DELETE + keyword in URL) and again the goal is not to transform xwiki into a REST system but into some way more generic and we need the current scheme to work too. Basically we want to be independent of the way Actions and Resources are entered into XWiki. The idea with ResourceAction is to provide that independence and the goal of the Resolver is to generate that ResourceAction from whatever input that comes in (be it a REST call or an HTTP call with a URL corresponding to the current scheme). Do you still think that's wrong? If so how do you handle the current URLs of type: http://.../xwiki/bin/<action>/Space/Page ? Thanks -Vincent

...

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 for refactoring the rendering module and see how it goes.

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