org.apache.cocoon.transformation
Class IncludeTransformer

java.lang.Object
  org.apache.cocoon.util.AbstractLogEnabled
      org.apache.cocoon.xml.AbstractXMLProducer
          org.apache.cocoon.xml.AbstractXMLPipe
              org.apache.cocoon.transformation.AbstractTransformer
                  org.apache.cocoon.transformation.IncludeTransformer

All Implemented Interfaces:

org.apache.cocoon.caching.CacheableProcessingComponent, Configurable, ContentHandler, LexicalHandler, Poolable, Recyclable, Serviceable, org.apache.cocoon.sitemap.SitemapModelComponent, org.apache.cocoon.transformation.Transformer, XMLConsumer, org.apache.cocoon.xml.XMLConsumer, org.apache.cocoon.xml.XMLPipe, org.apache.cocoon.xml.XMLProducer

public class IncludeTransformer

extends org.apache.cocoon.transformation.AbstractTransformer

implements Serviceable, Configurable, org.apache.cocoon.caching.CacheableProcessingComponent

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.

Root Element Stripping

The root element of included content may be automatically stripped by specifying strip-root="true" on the include element. This is the same functionality as provided by CIncludeTransformer.

Example:

 <i:include xmlns:i="http://apache.org/cocoon/include/1.0"
               src="cocoon://path/to/include" strip-root="true"/>
 

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&paramB=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.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Field Summary

protected RequestAttributes	attributes The RequestAttributes used within parallel threads
protected org.apache.cocoon.environment.Environment	environment The Environment used within parallel threads
protected ServiceManager	manager The ServiceManager instance associated with this instance.
protected org.apache.cocoon.environment.SourceResolver	resolver The SourceResolver used to resolve included URIs.
protected String	threadPool The name of the thread pool to use (for parallel processing).
protected org.apache.cocoon.components.source.impl.MultiSourceValidity	validity The SourceValidity instance associated with this request.

Fields inherited from class org.apache.cocoon.xml.AbstractXMLProducer

contentHandler, EMPTY_CONTENT_HANDLER, lexicalHandler, xmlConsumer

Fields inherited from interface org.apache.cocoon.transformation.Transformer

ROLE

Constructor Summary

IncludeTransformer()
Create a new IncludeTransformer instance.

Method Summary

void	configure(Configuration configuration)
void	endDocument() Receive notification of the end of an XML document.
void	endPrefixMapping(String prefix) Receive notification of the end of a prefix mapping.
Serializable	getKey() Return the caching key associated with this transformation.
SourceValidity	getValidity() Generate (or return) the SourceValidity instance used to possibly validate cached generations.
void	recycle() Recycle this component instance.
void	service(ServiceManager manager) Setup the ServiceManager available for this instance.
void	setConsumer(org.apache.cocoon.xml.XMLConsumer consumer)
void	setContentHandler(ContentHandler handler)
void	setLexicalHandler(LexicalHandler handler)
void	setup(org.apache.cocoon.environment.SourceResolver resolver, Map om, String src, Parameters parameters) Setup this component instance in the context of its pipeline and current request.
void	startDocument() Receive notification of the beginning of an XML document.
void	startPrefixMapping(String prefix, String nsuri) Receive notification of the start of a prefix mapping.

Methods inherited from class org.apache.cocoon.xml.AbstractXMLPipe

characters, comment, endCDATA, endDTD, endElement, endEntity, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startCDATA, startDTD, startElement, startEntity

Methods inherited from class org.apache.cocoon.util.AbstractLogEnabled

getLogger, setLogger

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.xml.sax.ContentHandler

characters, endElement, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startElement

Methods inherited from interface org.xml.sax.ext.LexicalHandler

comment, endCDATA, endDTD, endEntity, startCDATA, startDTD, startEntity

Field Detail

manager

protected ServiceManager manager

The ServiceManager instance associated with this instance.

threadPool

protected String threadPool

The name of the thread pool to use (for parallel processing).

resolver

protected org.apache.cocoon.environment.SourceResolver resolver

The SourceResolver used to resolve included URIs.

attributes

protected RequestAttributes attributes

The RequestAttributes used within parallel threads

environment

protected org.apache.cocoon.environment.Environment environment

The Environment used within parallel threads

validity

protected org.apache.cocoon.components.source.impl.MultiSourceValidity validity

The SourceValidity instance associated with this request.

Constructor Detail

IncludeTransformer

public IncludeTransformer()

Create a new IncludeTransformer instance.

Method Detail

service

public void service(ServiceManager manager)
             throws ServiceException

Setup the ServiceManager available for this instance.

Specified by:

service in interface Serviceable

Throws:

ServiceException

See Also:

Serviceable.service(ServiceManager)

configure

public void configure(Configuration configuration)
               throws ConfigurationException

Specified by:

configure in interface Configurable

Throws:

ConfigurationException

setup

public void setup(org.apache.cocoon.environment.SourceResolver resolver,
                  Map om,
                  String src,
                  Parameters parameters)
           throws org.apache.cocoon.ProcessingException,
                  SAXException,
                  IOException

Setup this component instance in the context of its pipeline and current request.

Specified by:

setup in interface org.apache.cocoon.sitemap.SitemapModelComponent

Throws:

org.apache.cocoon.ProcessingException

SAXException

IOException

See Also:

Serviceable.service(ServiceManager)

setConsumer

public void setConsumer(org.apache.cocoon.xml.XMLConsumer consumer)

Specified by:

setConsumer in interface org.apache.cocoon.xml.XMLProducer

setContentHandler

public void setContentHandler(ContentHandler handler)

setLexicalHandler

public void setLexicalHandler(LexicalHandler handler)

recycle

public void recycle()

Recycle this component instance.

Specified by:

recycle in interface Recyclable

See Also:

Recyclable.recycle()

startDocument

public void startDocument()
                   throws SAXException

Receive notification of the beginning of an XML document.

Specified by:

startDocument in interface ContentHandler

Throws:

SAXException

See Also:

ContentHandler.startDocument()

endDocument

public void endDocument()
                 throws SAXException

Receive notification of the end of an XML document.

Specified by:

endDocument in interface ContentHandler

Throws:

SAXException

See Also:

ContentHandler.startDocument()

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String nsuri)
                        throws SAXException

Receive notification of the start of a prefix mapping.

This transformer will remove all prefix mapping declarations for those prefixes associated with the http://apache.org/cocoon/include/1.0 namespace.

Specified by:

startPrefixMapping in interface ContentHandler

Throws:

SAXException

See Also:

ContentHandler.startPrefixMapping(String, String)

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Receive notification of the end of a prefix mapping.

This transformer will remove all prefix mapping declarations for those prefixes associated with the http://apache.org/cocoon/include/1.0 namespace.

Specified by:

endPrefixMapping in interface ContentHandler

Throws:

SAXException

See Also:

ContentHandler.endPrefixMapping(java.lang.String)

getKey

public Serializable getKey()

Return the caching key associated with this transformation.

When including cocoon:// sources with dynamic content depending on environment (request parameters, session attributes, etc), it makes sense to provide such environment values to the transformer to be included into the key using key sitemap parameter.

Specified by:

getKey in interface org.apache.cocoon.caching.CacheableProcessingComponent

See Also:

CacheableProcessingComponent.getKey()

getValidity

public SourceValidity getValidity()

Generate (or return) the SourceValidity instance used to possibly validate cached generations.

Specified by:

getValidity in interface org.apache.cocoon.caching.CacheableProcessingComponent

Returns:

a non null SourceValidity.

See Also:

CacheableProcessingComponent.getValidity()