| A simple transformer including resolvable sources (accessed through
Cocoon's
SourceResolver ) from its input.
Inclusion is triggered by the <include ... /> element
defined in the http://apache.org/cocoon/include/1.0 namespace.
Example:
<i:include xmlns:i="http://apache.org/cocoon/include/1.0"
src="cocoon://path/to/include"/>
An interesting feature of this
Transformer is that it implements the
CacheableProcessingComponent interface and provides full support for
caching. In other words, if the input given to this transformer has not changed,
and all of the included sources are (cacheable) and still valid, this transformer
will not force a pipeline re-generation like the
CIncludeTransformer .
Relative Source Resolution
Include sources which are specified using relative URI will be resolved
relative to the source document location. This is consistent with
XIncludeTransformer behavior, but differs from
CIncludeTransformer .
Parameters Passing
Parameters to be passed to the included sources can be specified in two ways:
the first one is to encode them onto the source itelf, for example:
<i:include xmlns:i="http://apache.org/cocoon/include/1.0"
src="cocoon://path/to/include?paramA=valueA¶mB=valueB"/>
Another approach allows the encoding of parameters to be done automatically by
the transformer, so that one can easily pass parameter name or values containing
the & (amperstand) or = (equals) character, which are
reserved characters in URIs. An example:
<i:include xmlns:i="http://apache.org/cocoon/include/1.0"
src="cocoon://path/to/include">
<i:parameter name="firstParameterName" value="firstParameterValue"/>
<i:parameter name="other&Para=Name" value="other=Para&Value"/>
</i:include>
Fallback Element
IncludeTransformer allows fallback element to be specified within
include element. XML content of the fallback element will be included instead
of source content if source inclusion caused an exception. Fallback element
can have nested include elements. An example:
<i:include xmlns:i="http://apache.org/cocoon/include/1.0"
src="cocoon://path/to/include">
<i:fallback>
The data is temporarily unavailable.
We are sorry for the trouble; please try again later.
</i:fallback>
</i:include>
Parallel Processing
Another feature of this
Transformer is that it allows parallel processing
of includes. By setting the optional parameter parallel to true,
the various included contents are processed (included) in parallel threads rather
than in series, in one thread. This parameter can be set in either the transformer
definition (to affect all IncludeTransformer instances):
<parallel>true</parallel>
or in a pipeline itself (to only affect that instance of the IncludeTransformer):
<map:parameter name="parallel" value="true"/>
By default, parallel processing is turned off.
Recursive Processing
This
Transformer allows recursive processing of includes.
By setting the optional parameter recursive to true,
the various included contents are scanned for include elements, and processed
in the same manner as incoming XML events. This parameter can be set in either
the transformer definition (to affect all IncludeTransformer instances):
<recursive>true</recursive>
or in a pipeline itself (to only affect that instance of the IncludeTransformer):
<map:parameter name="recursive" value="true"/>
This feature is similar to the XInclude processing. By default,
recursive processing is turned off.
version:
$Id: IncludeTransformer.java 433543 2006-08-22 06:22:54Z crossley $ | 