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 <[EMAIL PROTECTED]> 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
