New URL system

Why do we care about Urls
=========================

Because Nuxeo5 mainly deals with managing and browsing content, it is
important to provide a way to locate a content object from an URL.

We have several use cases where Nuxeo5 need to provide support for URL:

• Bookmarking a document in the web browser to be able to easily come
  back to it
• Sending a document référence via mail (Subsricptions, alerts)
• Providing a basic rest API for an external application like an
  external search engine
• Be crawler frendly (external full text indexing for wcm)
• Provide application specific URL normalization based on business
  schemas (can be used to insert links into the documents)

URLs patterns
=============

There are several reasons for not having just one static URL pattern :

performance vs business requirements :
--------------------------------------
Some URLs patterns are better for performance, some other are just
needed for business reason even if not optimal from a technical point of
view.

Acess only vs navigation urls :
-------------------------------
Having a URL that is bookmarkable in each page implies that current URL
is allways meaningfull enought to restore the state of the application.
Most business URL use cases only need to provide URL resolution : just
accessing to a document.

State recovering can have differents scopes :
---------------------------------------------
a URL can represent : a document , a version or a given view of a
document (ie : select the right management tab).

implementation
--------------
The URLs mapping implementation may act on differents layers :

• Servlet container (ie : filters)
• JSF engine (ie : phase listener)
• Seam (ie: pages.xml mapping)
• Pure resolver (codec)

Constraints
===========

URLs can be generated and manipulated by components from diffrents
layers :

• ui : web interface
• service : notifications or subscriptions
• storage : indexing
  This means that at least the codecs must be accesible from all layers.

Some information, like the server name, the port or the protocol can
only be safely generated from inside the web container. Other layers
will rely on a static configuration.

Current inplementation state
============================

DocumentLocation and DocumentView
---------------------------------
The DocumentLocation stores the DocumentRef and the core instance name.
The DocumentView associate the DocumentLocation with informations about
the JSF view and the current tab. This allows to navigate to a specifc
view of a document.

DocumentLocator
---------------
Provides encoding / decoding API for one URL pattern.

Seam + NavigationContext
------------------------
Via Seam pages.xml, the getDocument.faces is bound to a method of
navigationContext that navigates to the target DocumentLocation.
This provides implementation for the "access only" use cases (like
PermLink)

Seam rest mapping
-----------------
facelets are bound to a Seam component that restore/resync the
navigation context and delegate the rendering to the target view.
Inside default Nuxeo5, only view_documents.faces is bound.
Seam redirect filter, use our resync component to pull context
informations
This mapping allow to have bookmarkable urls for all the navigations
that go to a view of a documents.

URL Filter
----------
A simple filter is used to provide Zope like URLs : /repo/doc/view
insteed of ?repository=repo&docId=1XXXXX&viewId=view
In addition, the Seam redirect filter is wrapped to rewrite redirect
URLs to the target pattern.

Seam service
------------
urlMaker (seam component) can be used to generate or resolve url.

JSF Components
--------------
<nxd:restDocLink> can be used to render a GET link to a DocumentView.

Target implementation
=====================

DocumentLocatorService
----------------------
NXRuntime service that exposes 2 extensions points :

• codec
  Register URL<=>DocumentLocation/DocumentView encoder/decoders
• configuration
  Define some generic config :
• static baseURL value : http://myserver:8080/nuxeo/
• default codec
  This service offers an API that forwards to the default codec.

We have at least 4 codec implementations :

• existing DocumentLocator impl
• 2 existing DocumentView mapper impl
• 1 business locator

URLMapperService
----------------
NXRuntime service that exposes a extension point to register
configuratons profiles :

• name
• default yes/no
• codec name
• needFilter : yes/no
• RequestWrapper class used in filter
• needResponseWrapper : yes/no
• ResponseWrapper class used in filter
• usesDefaultAccessor : yes/no

In a near future, we may need to JSF Phase Listener that make us more
independant of the page.xml config.

This service is wrapped by a Seam components.

• provides API applied to current Context (ie : getCurrentDocumentURL)
• provides API for actual baseURL ( getBaseURL )
• provides default accessor implementation with page.xml mapping (ie: getDocument.faces)

PublisherFilter
---------------
Based on current FancyURLFilter, uses wrappers defined in
URLMapperService to rewrite requests and response.