forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: cocoon protocols
Date Tue, 07 Jun 2005 09:31:27 GMT
Tim Williams wrote:
> I ask for your patience as I really want to understand what's actually
> happening with the addressing.   I feel like until I understand *why*
> some of these things are happening, I'm stuck making mods (largely
> through trial, error, and crossed fingers)  to existing stuff instead
> of original contributions.  Here are a few more details to my
> questions....

We understand. Whilst your questions are well focused and clear we have 
no problem answering them. Especially since it is clear you actually 
read documentation you are referred to (so rare).

Talking of documentation, don't forget Forrest is a Cocoon based webapp 
so there is a wealth of documentation on the cocoon site 
(http://cocoon.apache.org) and their mailing lists. I'm not point you to 
this to say "go away" I'm merely letting you know there is a place to 
get further info if you are awaiting a response from someone here.

> On 6/6/05, Ross Gardler <rgardler@apache.org> wrote:
> 
>>Tim Williams wrote:
>>
>>>I'd like to clarify my understanding of the use of cocoon protocols in
>>>forrest.  The cocoon documentation says:
>>># context://  - get a resource using the servlet context
>>># cocoon:/ - get a pipeline from the current sitemap
>>># cocoon:// - get a pipeline using the root sitemap
>>># resource:// - get a resource from the context classloader
>>>
>>>1) Are cocoon:/ and cocoon:// interchangable within the conceptual
>>>sitemap space of forrest (e.g., \main\webapp\*.xmap)?  Anecdotally,
>>>nothing seems to break when I modify existing ones.
>>
>>My understanding is...
>>
>>cocoon:/ will *only* match something in the current sitemap (i.e. not
>>those in mounted sitemaps or sitemaps from which the current one was
>>mounted). I'm not sure if it will match in mounted sitemaps below this
>>one, I suspect it will not, but could be wrong.
> 
> 
> I may very well be getting confused on the terms root and current. 
> The forrest docs say that " Forrest's sitemap comprises the
> $FORREST_HOME/context/*.xmap files."  This leads me to believe that
> the terms root and current are conceptual rather than physical which
> would mean they are one and the same for the forrest cocoon app and
> mounting is just a mechanism to bring the physical maps together?

Firstly that documentation is now misleading because we have plugin 
sitemaps and project sitemaps as well now. Can you please point us to 
the file you read that in so we can clarify it.

Secondly, I am using root to refer to the *first* sitemap that is 
loaded. This is always FORREST_HOME/main/webapp/sitemap.xmap

If you look in that sitemap you will find many <map:mount...> elements. 
These will load other sitemaps under certain conditions. When we are 
considering matches in a sitemap that has been mounted I am using the 
term "current" to indicate that.

It may help you top read 
http://forrest.apache.org/0.7/docs/howto/howto-custom-html-source.html
Although this how-to is not about what you want to do it does have a 
very clear description of the logic in sitemap processing.

> If
> those terms are applied physically it might be more understandable why
> they are used differently in forrest but then i would like to make
> some suggestions to the documentation as i would consider it to be
> misleading in it's current form.

This is another reason why we don't mind taking the time to clarify 
things in response to your questions. It is our hope that you will 
indeed provide patches to the docs based on the understanding you gain 
from asking those questions.

In other words, bring on those patches :-))

>>cocoon:// will mount from *any* sitemap in the app
> 
> 
> again, sitemap as a physical file?  meaning \main\webapp\*.xmap +
> {project.sitemap}?

Yes, but as mentioned above we also have plugin sitemaps and project 
sitemaps now. You can see the mounts for these in 
/main/webapp/sitemap.xmap and /main/webapp/forest.xmap

>>In other words, you can make it break if you change the wrong one.
> 
> 
> Right, but I'm still not clear on what would qualify as the "wrong one".  
> 
> Here are a few examples that seem odd to me.
> 
> linkmap.xmap - For the match "**linkmap-*", the generator is pointing
> to cocoon://abs-linkmap which in my understanding would go back to the
> root sitemap (ie., sitemap.xmap) and match the abs-linkmap there which
> essentially points right back to the match that was above it in the
> first place.  In this case, why not use cocoon:/abs-linkmap.

OK The truth is that many developers do not understand the full 
implications of the subtleties of things like the difference between 
cocoon:// and cocoon:/ The further truth is that my explanations here 
are "as I understand it" (a disclaimer I had in the very first sentence 
of my initial response). What I am saying is that many of us devs do 
what makes it work, it may not be the *best* way, but it does work. In 
other words, just because it is in our code base it does not mean it is 
necessarily the right way.

As you know one of the benefits of Open Source is the many eyes 
principle. That is with lots of devs looking at the code it gradually 
gets improved. The principle also applies to mailing list discussions 
like this, if my assumptions are incorrect, it is hoped that someone 
will spot that and clarify the situation.

In your example above I imagine (there's another of those disclaimers) 
that using cocoon:/ as you suggest would in fact be more efficient, as 
Cocoon would not need to check for a match in sitemap.xmap, only in 
linkmap.xmap.

I'd suggest changing things and doing:

cd FORREST_HOME/main
./build clean test

If everything works then you can submit a patch. At this point someone 
will definitely review the code and, if our assumptions are correct it 
will be applied and hence the code will be improved (along with out 
understanding).

> tabs.xmap - the last transformer has a src of
> "cocoon:/{1}linkmap-{2}.html" which apparently goes resolves in
> sitemap.xmap and ultimately linkmap.xmap seems link it should be
> cocoon:// if anything should.

OK, this would seem to imply that my assumptions of the behaviour of 
cocoon:/ and cocoon:// are incorrect. So let me go to the Cocoon docs...

In http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html

I found:

#  Use cocoon:/current-sitemap-pipeline/foo/bar to merge in xml content 
from the current sitemap. The appropriate pipeline is selected matching 
current-sitemap-pipeline.
# Use cocoon://root-sitmap-pipeline/foo/bar to merge in xml content from 
the root sitemap. The appropriate pipeline is selected matching 
root-sitemap-pipeline.

and

Mount points allow sitemaps to be cascaded and site management workload 
to be parallelized. This creates a tree of sitemaps with the main 
sitemap at the root and possibly several sub-sitemaps as nodes and leaves.

This seems to agree with what I have said so far. So what is the difference?

I don't know the answer to this one. Lets hope someone else here knows 
and explains for us. If not then we need to go to the cocoon-users list 
and check their archives and if necessary ask the question.

I will hazard a guess based on the behaviour I have witnessed (and it is 
a guess). It might be that the cocoon:/ falls back to searching from the 
root sitemap if no match is found in the current sitemap. I am offering 
this as a guess since I know that you can have two matchers in different 
sitemaps that would ultimately do the same thing (i.e. both match 
"*.xml"). If you do cocoon:// from the sub sitemap then the matcher in 
the root is used. If you do cocoon:/ then the one in the sub sitemap 
(current) is used (i.e. the behaviour is as described).


>>>2) The same doesn't appear to hold true of forrest-core.xconf as
>>>things do break if the correct one isn't used.  Since all of them here
>>>are to the root sitemap (e.g., cocoon://) is forrest-core.xconf
>>>outside the forrest conceptual sitemap?
>>
>>Pass
> 
> 
> Fair enough, anyone else?  Ironically enough, it was your reference to
> cocoon://locationmap.xml in xconf that got me reading:
> http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html#Protocols
> and wondering how these schemes work.


Ahhh... well now I can tell you what "my understanding" is.

the value cocoon://locationmap.xml is just a value of a variable used in 
the LocationMap code. It is used within the processing of the sitemap 
and so the behaviour is no different. In other words it says, start 
looking in the root sitemap (FORREST_HOME/main/webapp/sitemap.xmap) and 
if necessary look in any relevant mounted maps.

>>>3) Are project specific sitemap.xmaps are separate root sitemaps or
>>>extensions of the forrest application sitemap?
>>
>>
>>The are mounted from the application sitemap by the following:
> 
> ...
> 
> Yes, I saw that but am still not clear on whether that makes them
> interchangable with cocoon:/ and cocoon://.  All others within
> main\webapp are mounted as well so are they equals?

According to my understanding as expressed above a cocoon:/ in the 
project sitemap will *not* search the root sitemap, a cocoon:// will.

Of course, you have provided an example that indicates this is not the 
case despite the Cocoon docs agreeing with this. The hypothesised 
fallback behaviour would fit this case too.

To have a definitive answer you will need to search the cocoon mail list 
archives and if necessary ask over there.

> I appreciate your patience as I learn this stuff...

You can reward us in many ways some are:

- with improvements to our docs, anything in the mailing lists is owned 
by the ASF so you can cut and paste relevant content.

- answering other peoples questions when you understand their problems

- helping with testing (you are doing that on the locationmap branch - 
thanks)

- code improvements (you are doing that too)

- community dynamics (you are doing that too)

Thanks for *your* help.

Ross

Mime
View raw message