[xwiki-devs] [Proposal] New module: xwiki-resources

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