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
