Return-Path: 
 <dev-return-14855-apmail-forrest-dev-archive=forrest.apache.org@forrest.apache.org>
Delivered-To: apmail-forrest-dev-archive@www.apache.org
Received: (qmail 36008 invoked from network); 24 Jan 2005 10:54:08 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur-2.apache.org with SMTP; 24 Jan 2005 10:54:08 -0000
Received: (qmail 13002 invoked by uid 500); 24 Jan 2005 10:54:07 -0000
Delivered-To: apmail-forrest-dev-archive@forrest.apache.org
Received: (qmail 12970 invoked by uid 500); 24 Jan 2005 10:54:07 -0000
Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:dev-help@forrest.apache.org>
list-unsubscribe: <mailto:dev-unsubscribe@forrest.apache.org>
list-post: <mailto:dev@forrest.apache.org>
Reply-To: dev@forrest.apache.org
Delivered-To: mailing list dev@forrest.apache.org
Received: (qmail 12954 invoked by uid 99); 24 Jan 2005 10:54:06 -0000
X-ASF-Spam-Status: No, hits=-0.0 required=10.0
	tests=SPF_HELO_PASS,SPF_PASS
X-Spam-Check-By: apache.org
Received-SPF: pass (hermes.apache.org: domain of
 cjxaf-forrest-dev-1@m.gmane.org designates 80.91.229.2 as permitted sender)
Received: from main.gmane.org (HELO main.gmane.org) (80.91.229.2)
  by apache.org (qpsmtpd/0.28) with ESMTP; Mon, 24 Jan 2005 02:54:06 -0800
Received: from list by main.gmane.org with local (Exim 3.35 #1 (Debian))
	id 1Ct1r6-0001Il-00
	for <dev@forrest.apache.org>; Mon, 24 Jan 2005 11:54:00 +0100
Received: from host190-154.pool80204.interbusiness.it ([80.204.154.190])
        by main.gmane.org with esmtp (Gmexim 0.1 (Debian))
        id 1AlnuQ-0007hv-00
        for <dev@forrest.apache.org>; Mon, 24 Jan 2005 11:54:00 +0100
Received: from nicolaken by host190-154.pool80204.interbusiness.it with local
 (Gmexim 0.1 (Debian))
        id 1AlnuQ-0007hv-00
        for <dev@forrest.apache.org>; Mon, 24 Jan 2005 11:54:00 +0100
X-Injected-Via-Gmane: http://gmane.org/
To: dev@forrest.apache.org
From: Nicola Ken Barozzi <nicolaken@apache.org>
Subject: LocationMap (was Re: Forrest 0.6 - stable?)
Date: Mon, 24 Jan 2005 11:53:55 +0100
Lines: 202
Message-ID: <ct2k43$brh$1@sea.gmane.org>
References: <41F4BBD6.1040300@apache.org> <ct2gtl$24d$1@sea.gmane.org>
 <41F4C7C5.9090809@apache.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Complaints-To: usenet@sea.gmane.org
X-Gmane-NNTP-Posting-Host: host190-154.pool80204.interbusiness.it
User-Agent: Mozilla Thunderbird 1.0 (Windows/20041206)
X-Accept-Language: en-us, en
In-Reply-To: <41F4C7C5.9090809@apache.org>
Sender: news <news@sea.gmane.org>
X-Virus-Checked: Checked
X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N

Reinhard Poetz wrote:
> Nicola Ken Barozzi wrote:
...
>> IMHO they will change in 0.8, with the introduction of the locationmap.
> 
> Can you  give me a pointer to "locationmap"?

Hmmm... it's in the mail archives ;-)

Ok, well it's about describing where the sources for Forrest are with a 
special "sitemap" called "locationmap". The code is in SVN since ages, 
but we have not yet put it to good use.

I'm adding the first mail from Unico about it below.
It's in the thread named "LocationMapModule".

                              - 0 -

A locationmap defines a mapping from requests to location strings.

It was conceived to:

a) Provide a more powerful means for semantic linking.
b) Enable Forrest with a standard configuration override mechanism.

The syntax of a locationmap resembles that of the sitemap in that it 
also makes use of Matchers and Selectors to traverse a tree of nodes 
towards a leaf. In the case of the locationmap however the leaf does not 
identify a pipeline but instead identifies a location string.

                                           -- o --

An example:
-----------

<locationmap xmlns="http://apache.org/cocoon/locationmap/1.0">

<!--
   + Components section: define Matchers and Selectors here.
   + The current implementation only supports a subset of
   + the Avalon lifecycles. Only those that are actually
   + implemented by the currently available Selectors and Matchers.
   + Moreover, it expects them to be ThreadSafe (which all of them are IIRC)
   + -->
   <components>
     <matchers default="parameter">
       <matcher
         name="parameter"
         src="org.apache.cocoon.matching.WildcardParameterMatcher">
         <!--
           + #lm:name is a special parameter that is passed into
           + the Matcher by the LocationMap implementation.
           + It identifies the name string the module was called
           + with. For example when calling the module as follows:
           + {lm:/my/virtual/path} the parameters value will
           + be /my/virtual/path .
           + -->
         <parameter>#lm:name</parameter>
       </matcher>
       <matcher
         name="request"
         src="org.apache.cocoon.matching.WildcardURIMatcher"
       />
     </matchers>
     <selectors default="exists">
       <selector
         name="exists"
         src="org.apache.cocoon.selecting.ResourceExistsSelector"
       />
     </selectors>
   </components>

<!--
   + Locator section.
   + A locator groups matchers and selectors and provides a base location
   + locations are resolved against.
   + The locator below exemplifies how a locator could be used
   + to enable clients to override resource locations.
   + -->
   <locator base="."> <!-- resolves to the current sitemap context -->
     <!--
       + locate skin stylesheets by searching fs locations 
/forrest/styles/{1}
       + and /hippo/styles/{1} respectively.
       + if none exist default to ./styles/
       + -->
     <match pattern="**.html" type="request">
       <select type="exists">
         <location src="file://unico/styles/{1}.xsl" />
         <location src="file://hippo/styles/{1}.xsl" />
       </select>
       <location src="styles/{1}.xsl" />
     </match>
   </locator>

   <!--
     + This locator exemplifies how to use a locationmap for
     + link resolving. Note the use of the parameter
     + type matcher. This one has been defined above to match
     + the special '#lm:name' parameter that holds a reference
     + to the argument the input module was called with.
     + -->
   <locator base=".">
     <match pattern="xdocs/**.xml" type="parameter">
       <match pattern="xdocs/news/*/*/*/today.xml">
         <location src="news/archive/{3}{2}{1}.html" />
       </match>
       <location src="{1}.html" />
     </match>
   </locator>
</locationmap>


                                           -- o --


In the first example a sitemap would be able to do something like:

sitemap.xmap:
<map:match pattern="**.html">
   <map:generate src="xdocs/{1}.xml" />
   <map:transform src="{lm:}" type="xslt" />
   <map:serialize type="html" />
</map:match>

Note the usage of the locationmap module: {lm:}. The input module 
argument is empty because it is not used in the locationmap anyway (the 
matcher used is of type request).

In the second usage scenario the idea is that xdocs in a repository are 
only aware of their relative locations. What URL they are mapped to in a 
website is not their concern. Therefore there needs to be a translation 
between links between documents within an xml repository and their 
locations on a website. This is very similar to semantic linking where 
editors define a virtual link and that link gets mapped to an actual 
location by a module that knows where the page is currently located 
(such as one reading a forrest site.xml file). The difference is that 
the source links are actually not virtual semantic identifiers at all 
but physical system identifiers, only relative to a seperate system than 
the target one. The LocationMap accommodates a complete mapping from any 
source location to any target location.

In scenario the module is used by a LinkRewriterTransformer:

sitemap.xmap:
<map:match pattern="**.html">
   <map:generate src="repo/**.xml" />
   <map:transform src="content2page.xsl" type="xslt" />
   <map:transform type="linkrewriter" />
   <map:serialize type="html" />
</map:match>

repo/{1}.xml:
<document>
   <title>How to use locationmaps</title>
   <related href="repo:xdocs/news/10/10/2002/today.xml" />
   <related href="repo:xdocs/news/02/02/2001/today.xml" />
   <body>blah</body>
</document>

{1}.html:
<html>
   <title>How to use locationmaps</title>
   <body>
    <p>blah</p>
    See also:
    <p><a href="news/archive/20021010.html">related news<a></p>
    <p><a href="news/archive/20010202.html">related news<a></p>
   </body>
</html>

                                           -- o --

Issues and Notes.
-----------------

The reason for the 'archored' syntax of special variables #lm:name and 
#lm:base is due to the fact that the treeprocessor code for variable 
resolution which I reused provides a way to declare global variables 
that way.

The reuse of Matcher and Selectors makes the locationmap very powerful. 
However, especially the Selector concept is not an exact fit when used 
in the context of a locationmap. This is because the test string that is 
passed to the selector in a locationmap has a more specific meaning than 
the test strings that are passed to it in the sitemap. In the 
locationmap's case it is the resolved location src attribute, whereas in 
a sitemap it can be anything because it is explicitly passed in as 
<map:when test="{something}"/>. Therefore some selectors do not make 
sense in the context of a locationmap (f.e. a HostSelector).

Nothing in the code indicates that <location src="something" /> is 
interpreted as a location string per se. It can in fact be anything. Its 
only semantic constraint is that it is a string literal.



-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------