Quote macro with aparameter break XWiki Syntax 1.0 to XWiki Syntax 2.0

Describes the new design for the XWiki Model module.

1.1 Requirements

* Notions of:
** multi wiki
** wiki
** space
** document
** document metadata (language, syntax id, etc)
** document objects
** document classes
** attachment
* UUIDs for Documents, Spaces, Wikis, Farms
** Ability to have multiple URIs for model objects
* Nested spaces
* Ability to version model objects
* Ability to add metadata to model objects
* Easy to use API (typed API)
* Simple API to get other sub elements in model objects (for ex: ability to get documents in a given space). More complex retrieval API in the Query Manager
* Authentication/Authorization to be decided
** Should checks be done outside of the model module?
** Should we use JAAS and if so what's the relationship
* Allow inheritance for document objects/classes
** objects with more than 1 class? (sergiu)
* Observation: Ability to get callbacks when objects are modified/created/removed
* Ability to lock model objects to prevent modifications in some cases (when someone is already modifying them or if the wiki is in readonly mode for example)
* (to be continued)

1.1 Features from a user point of view

* Nested spaces
* Ability to choose storage: RDBMS, file system, etc
* Document renames/deletes/etc only affect URLs but don't change document ids
* Multiple URLs for documents
* Ability to version the whole repository when a change is made (SVN-like) and hence the ability to restore the state across documents/spaces/etc
** Ability to install an application and remove it simply by doing a simple rollback even when the app is made of several documents

1.1 Implementation Details

#warning("This is a proposal in progress and it's not been voted on yet")

Use JCR for the following interesting features:
* Referenceability of nodes, UUID
* Transactional
* Versionable (whole trees). JR283 enhances on the versioning set forth in JSR170 by specifying four versioning models, simple versioning, full versioning, activities, and configurations.
* Lockable
* Import/Export (in XML format)
* Can support inheritance
* Supports observation
* Utilizes JAAS for authentication. Authorization is not explicitly outlined, the specification leaves it up to the repository vendor to implement a specific permission model. While the API defines a rudimentary permission check for node operations, there is no way to set permissions based on users, groups, and roles. JSR283 greatly improves in this area.
** [Pluggable security model that can maintain ACL at object level>http://whiteboardjunkie.wordpress.com/2008/11/24/where-am-i-using-jcr-and-why/]
* JSR 283 (JCR 2.0) further introduces the concept of shareable nodes which allows multiple paths of access to a node, providing the ability to implement faceted navigations through content
* JSR 283 further introduces the concept of journaled listeners which can ask the repository to re-play all events after a certain timestamp
* Shareable nodes. {quote:http://jtoee.com/jsr-170/the_jcr_primer/8/}In JSR170, a node can only be the child node of one other node. This makes it impossible to file nodes under multiple taxonomies, i.e. defining multiple paths to get to the same node. JSR283 hence introduces the (optional) concept of shareable nodes.{quote} This allows implementing multiple URIs for a given model object.
* "Primary child item" feature. {quote}Any one of a node's child items may be specified as its primary child item. This item can be directly accessed (without knowing its name) with the method Node.getPrimaryItem(). The primary item of a particular node (if it has one) is declared in its node type.{quote}. This could allow for example a document to have a default view for displaying its content.

* Mapping:
** Wiki = Workspace
*** We cannot have Wiki = Repository since there's no inter repository operations and we want for example the ability for a given wiki to include a document from another wiki
*** Allows clone nodes between wikis and support references between wikis (children wiki can have references to admin wiki documents for example)
*** UUID are unique per repository (and not per workspace)
*** A node with the same UUID in several workspaces point to the same Node
*** Note: one version storage per repository
*** Ability to call Node.update(String srcWorkspace) to replace this node by the one and its children from the srcWorkspace (same as svn update)
*** We can still have the ability to clone a wiki (and thus clone a workspace) to provide a working branch (for example for staging a workspace) and then later on do an update (as in svn update) to merge the changes back into the main "trunk"
** Document = Node + special NodeType
** Document metadata = Property
** Space = Node + special NodeType
** Document objects = Node + special NodeType (subnode of Document)
** Document object properties = Propery
** Document classes = Node + special NodeType (subnode of Document)
** Document class property = Property
** Attachment = Node + special NodeType (subnode of Document)
** Attachment data/metadata = Property

* Advantages of using JCR:
** Standardized
** Existing implementations (JackRabbit, exo JCR, etc)
** Ability to use existing tools that act on JCR:
*** [JCR Explorer>http://www.jcr-explorer.org/screenshots.html]

*Idea: Use workspaces to provide editorial workflow: 
{quote:http://jtoee.com/jsr-170/the_jcr_primer/2/}
At the core of the specification is the concept of the repository. A repository contains any number of workspaces. While a simple repository usually only contains one workspace, a repository can contain any number of workspaces. A workspace is essentially a view into the repository. The same content items may appear in multiple workspaces, some content items may only be present in one workspace. Workspaces can be thought of work-in-progress areas of a repository, much like a scrapbook. Content is always created in a workspace and may then be propagated into another workspace.

There are many potential uses for multiple workspaces. For example, one can use workspaces in a similar way to branches in a source control system (even though as we will see later, the JCR provides versioning separately). A group of content editors work locally in a workspace and when their work is completed, the finished work can be submitted into a central workspace.

Workspaces could potentially also be used to differentiate between in-progress, QA, and live environments, where changes are propagates from one workspace to the other as they go through the editorial workflow.{quote}

1.1.1 Open Questions

* Do we keep a xwiki storage API or do we decide to standardize on the JCR API?
** If not then directly put the JCR Session object in the xwiki execution context after having authenticated the user against the repository to get the Session
* Find out how to map JCR services to existing xwiki services: query manager, storage, observation, etc
* What name mapping do we use for nodes representing documents for example since JCR imposes restrictions on node names?
* TODO: Check JPA and especially JPA 2.0 (http://www.infoq.com/news/2009/05/jpa20) to see if it's a valid alternative for us

1.1 References

* XWiki:
** [Initial Model Proposal on the dev list>http://xwiki.markmail.org/message/5elx2g47g6m4blqw?q=model+Wiki+Farm]
** [Document Name and Factory on the dev list>http://xwiki.markmail.org/message/ebeafpu6gvhqdunq?q=DocumentName+DocumentNameFactory]

* JCR:
** [Various JCR links>http://wiki.apache.org/jackrabbit/JcrLinks]
** [JCR Primer>http://jtoee.com/jsr-170/the_jcr_primer/]
** [JCR 1.0 API>http://www.day.com/maven/jsr170/javadocs/jcr-1.0/]
** [JCR 2.0>http://jcp.org/en/jsr/detail?id=283]
** [JCR: A Practictioner's Perspective>http://www.theserverside.com/tt/articles/article.tss?l=JCRPract]
** [Content Modeling for JCR>http://dev.day.com/microsling/content/blogs/main/contentmodels2.html]
** [Interesting JCR blog posts>http://whiteboardjunkie.wordpress.com/category/jcr/]