non-releases/trunk_before_flattening/src/java/org/apache/cocoon/components/modules/input/package.html - cocoon - Git at Google

 <!--
   Copyright 1999-2004 The Apache Software Foundation

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
   <title>input</title>

   <meta http-equiv="content-type"
  content="text/html; charset=ISO-8859-1">
 </head>
 <body>

 <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>
   &lt;input-modules>
     &lt;component-instance name="global"
              class="org.apache.cocoon.components.modules.input.GlobalInputModule"
              logger="core.modules.input"/>
     &lt;component-instance name="request"
              class="org.apache.cocoon.components.modules.input.RequestModule"
              logger="core.modules.input"/>
     &lt;component-instance name="session"
              class="org.apache.cocoon.components.modules.input.SessionModule"
              logger="core.modules.input"/>
     &lt;component-instance name="request-param"
              class="org.apache.cocoon.components.modules.input.RequestParameterModule"
              logger="core.modules.input"/>
     ...
     &lt;component-instance name="defaults"
              class="org.apache.cocoon.components.modules.input.DefaultsModule"
              logger="core.modules.input">
       &lt;values>
         &lt;skin>defaultSkin&lt;/skin>
         &lt;base-url>http://localhost:8080/cocoon&lt;/base-url>
       &lt;/values>
     &lt;/component-instance>
   &lt;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 &lt;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>
 &lt;component-instance name="mappingmodule"
     class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
     logger="core.modules.mapper">
   &lt;input-module name="xmlmodule"/>
   &lt;prefix>/site/&lt;/prefix>
   &lt;suffix>/@href&lt;/suffix>
 &lt;/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>
	<!--
	Copyright 1999-2004 The Apache Software Foundation

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<title>input</title>

	<meta http-equiv="content-type"
	content="text/html; charset=ISO-8859-1">
	</head>
	<body>

	<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>