You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by je...@apache.org on 2003/05/03 18:01:45 UTC
cvs commit: cocoon-2.1/src/java/org/apache/cocoon/components/modules/input package.html
jefft 2003/05/03 09:01:44
Modified: src/java/org/apache/cocoon/components/modules/input
package.html
Log:
Improve package.html description of input modules.
Revision Changes Path
1.2 +141 -6 cocoon-2.1/src/java/org/apache/cocoon/components/modules/input/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/java/org/apache/cocoon/components/modules/input/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 9 Mar 2003 00:09:04 -0000 1.1
+++ package.html 3 May 2003 16:01:44 -0000 1.2
@@ -8,12 +8,147 @@
</head>
<body>
-<h1>input<br>
-</h1>
-
-<p>Input modules provide a simple interface to obtain values largely based
-on the methods provided by request and session to get values and names of
-attributes.</p>
+<h1>InputModules</h1>
+
+<h2>Introduction</h2>
+<p>
+Input modules are generic components that let one map a key to one or more
+values. In concept and API, input modules are closest to the <a
+ href="http://java.sun.com/j2se/1.4/docs/api/java/util/Properties.html">java.util.Properties</a>
+class. An input module has a number of named attributes, each of which has an
+associated value or values, which will be computed or looked up when requested.
+</p>
+<pre>
+ | InputModule |
+ |----------------------------|
+ | PropName | PropValue(s) |
+ |----------------------------|
+ | prop1 | value1 |
+ | prop2 | value2 |
+ | ... | ... |
+ | propn | valuen |
+ +----------------------------+
+</pre>
+<p>Three operations are defined by the <a
+ href="InputModule.html">InputModule</a> interface:</p>
+<dl>
+ <dt>getAttributeNames</dt>
+ <dd>Retrieve a list of all available attributes (the set <i>prop1, prop2, ..., propn</i>).</dd>
+ <dt>getAttribute</dt>
+ <dd>
+ Retrieve the value of an attribute. For instance,
+ <code>getAttribute(<i>prop1</i>)</code> would return <i>value1</i>
+ </dd>
+ <dt>GetAttributeValues</dt>
+ <dd>Retrieve an Iterator for a list of values for an attribute.</dd>
+</dl>
+
+<h2>Usage</h2>
+<p>
+Input modules are used in various places in Cocoon, notably from within the
+sitemap, XSPs, and matchers.</p>
+<p>
+In the sitemap, input modules are made available
+through a {modulename:attributename} syntax. For instance, if a <a
+ href="RequestParameterModule.html">RequestParameterModule</a> named
+<code>request-param</code> is defined in cocoon.xconf, then
+<code>{request-param:user}</code> will in effect be replaced by the value of
+the <code>user</code> request parameter (e.g. index.html?user=joe). Similarly,
+a <a href="SystemPropertyModule.html">SystemPropertyModule</a> named
+<code>system-property</code> would allow
+<code>{system-property:user.home}</code> to represent user's home directory
+path.
+</p>
+
+<h2>Configuration</h2>
+<p>
+Input modules are declared in cocoon.xconf. There is a section dedicated to
+input modules:</p>
+<pre>
+ <input-modules>
+ <component-instance name="global"
+ class="org.apache.cocoon.components.modules.input.GlobalInputModule"
+ logger="core.modules.input"/>
+ <component-instance name="request"
+ class="org.apache.cocoon.components.modules.input.RequestModule"
+ logger="core.modules.input"/>
+ <component-instance name="session"
+ class="org.apache.cocoon.components.modules.input.SessionModule"
+ logger="core.modules.input"/>
+ <component-instance name="request-param"
+ class="org.apache.cocoon.components.modules.input.RequestParameterModule"
+ logger="core.modules.input"/>
+ ...
+ <component-instance name="defaults"
+ class="org.apache.cocoon.components.modules.input.DefaultsModule"
+ logger="core.modules.input">
+ <values>
+ <skin>defaultSkin</skin>
+ <base-url>http://localhost:8080/cocoon</base-url>
+ </values>
+ </component-instance>
+ <input-modules>
+</pre>
+<h3>Static/dynamic configuration</h3>
+<p>
+In cocoon.xconf, each input module can take a <em>static</em> configuration.
+This is made available to the class via the <code>configure()</code> method,
+called once on startup. In the example above, an Avalon
+<code>Configuration</code> object representing the <values> node will be
+passed to the DefaultsModule.
+</p>
+<p>
+In addition, every time an input module is used, a <em>dynamic</em>
+configuration is passed to it, as well as the current "object model". You can
+see these in the <a href="InputModule.html">InputModule</a> interface
+definition for all three methods. This dynamic, per-request configuration will
+usually <strong>override</strong> the static configuration. This dual
+static/dynamic configuration makes input modules useful in a wide variety of
+circumstances.
+</p>
+
+<h2>Meta Modules</h2>
+<p>
+So-called "meta" modules are modules that act on other modules. The simplest
+example of a meta module is the <a
+href="SimpleMappingMetaModule.html">SimpleMappingMetaModule</a>, which will
+query another module with a modified version of an attribute name. For
+instance, if configured with:</p>
+<pre>
+<component-instance name="mappingmodule"
+ class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
+ logger="core.modules.mapper">
+ <input-module name="xmlmodule"/>
+ <prefix>/site/</prefix>
+ <suffix>/@href</suffix>
+</component-instance>
+</pre>
+<p>
+Then a key <code>foo</code> will cause <code>xmlmodule</code> to be queried for
+attribute <code>/site/foo/@href</code>, and that value will be returned.</p>
+<p>
+Another useful example is <a href="ChainMetaModule.html">ChainMetaModule</a>,
+which will query a set of input modules until one returns a non-null value for
+an attribute, providing "fall-back" behaviour.
+</p>
+<p>
+The machinery for meta modules is provided in <a
+href="AbstractMetaModule.html">AbstractMetaModule</a>.
+
+<h2>JXPath use in Input Modules</h2>
+<p>Many input modules make use of the <a
+href="http://jakarta.apache.org/commons/jxpath/">JXPath</a> library, which lets
+one traverse Java object structures with an XPath-like syntax. Support for
+this is mostly located in the <a
+href="JXPathMetaModule.html">JXPathMetaModule</a> and <a
+href="AbstractJXPathModule.html">AbstractJXPathModule</a> superclasses, which
+should be kept synchronised.
+</p>
+
+<h2>Further Information</h2>
+<p>The best way to learn what can be done with input modules is by examining
+the samples that come with the Cocoon application. The main Cocoon
+documentation and Cocoon Wiki should have further information.
</body>
</html>