At Carsten's request, I'm attempting to summarise a long (46 email)
thread about input module 'chaining'. See [1] for exactly which mails I
mean. Re-reading it, it seems I'm the only one who was really confused, but
here's a summary anyway.
For the record: input modules are classes which give you easy sitemap
access to various kinds of data, most commonly the HTTP request data. For
examples, see src/webapp/samples/modules/sitemap.xmap. The data model is
"keys to values", similar to a Properties object. So {moduleA:foo} means
"look up the value corresponding to the key 'foo' in the 'moduleA'
module."
As Carsten summarized, the thread has covered two types of inter-module
behaviour, both called 'chaining' at various stages:
a) "Defaulting". Where if a module doesn't contain a value, another
module is queried. Primary use-case for Forrest.
b) "Real chaining". Where a module uses another module's input to decide
it's output. Examples include DigestMetaModule, which "obtains values
from other module and returns message digest of value".
Not making this difference clear has led to _lots_ of confusion. But on
with the summary..
About 10 days ago, I submitted an XMLModule[2], which allows XPath access to an
XML file, inside a sitemap (eg {configfile:/foo/bar}). Chris said:
"I would prefer that module to be a "meta" module that can be
configured to take input from any source (i.e. another InputModule)
rather than do the reading itself."
Here, Chris was trying to broaden the use of "real chaining". However,
"real chaining" doesn't particularly make sense to XMLModule. I said
this, and then introduced the "defaulting" pattern of use:
> Often, one wants a variable's value to come from one of a number of
> sources, ordered by preference:
>
> - From a request value, or if not present,
> - From a session value, or if not present,
> - From an XML config file or database.
To which Chris replied:
> To this I would suggest to have a module that does exactly this, along
> the lines of the current DefaultsMetaModule. Just that it takes a
> configurable list of modules to test. I hope that it's still not FS ;-)
It's a pity I didn't understand the distinction between "defaulting" and
"chaining", and that they should be solved individually. To cut a looong
story short, we ended up agreeing[3] on a solution to the "defaulting"
problem:
Simple use-case: say we want to know the site 'skin' in the sitemap, in order to
know what stylesheets to apply. The skin may be determined, in order of
preference:
- a request parameter, OR (if not present)
- an XML config file for the site, OR (if not present)
- a default value
So first, one would declare the individual modules:
<component-instance
class="org.apache.cocoon.components.modules.input.RequestParameterModule"
logger="core.modules.input" name="request-param"/>
<component-instance
class="org.apache.cocoon.components.modules.input.XMLModule"
logger="core.modules.input" name="xmlconf">
<config>resource:///forrestconf.xml</config>
</component-instance>
<component-instance
class="org.apache.cocoon.components.modules.input.DefaultsModule"
logger="core.modules.input" name="default">
<values>
<skin>defaultSkin</skin>
</values>
</component-instance>
So far, {default:skin} returns 'defaultSkin', {xmlconf:/*/skin} returns
'forrest-site' and {request-param:skin} returns whatever.
Now we declare a 'chaining' module which implements the if-then-else behaviour
described above:
<component-instance
class="org.apache.cocoon.components.modules.input.ChainingMetaModule"
logger="core.modules.input" name="skin">
<input-module name="request-param"/>
<input-module name="xmlconf"/>
<input-module name="default"/>
</component-instance>
The implementation of this is very simple: query each configured module in turn,
until one returns a value.
Pretty obvious really :) You have to look at the current DefaultsMetaModule
usage to appreciate just how much simpler than the current system this is.
Also, please note that this defaulting system can be implemented with almost any
underlying input module API.
--Jeff
[1] The thread starts at:
http://marc.theaimsgroup.com/?t=103338042200004&r=1&w=2 and
http://marc.theaimsgroup.com/?t=103354993700001&r=1&w=2
It incorporates mails with subjects like:
XML input module (was: RE: Nice changes!)
Input module chaining (Re: XML input module)
[VOTE] Input module chaining (Re: XML input module)
Chaining order (Re: [VOTE] Input module chaining)
[2] http://nagoya.apache.org/bugzilla/show_bug.cgi?id=13131
[3] http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=103407750307375&w=2
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
