This project has retired. For details please refer to its Attic page.

org.apache.cocoon.transformation
Class IncludeTransformer

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.cocoon.xml.AbstractXMLProducer
          org.apache.cocoon.xml.AbstractXMLPipe
              org.apache.cocoon.transformation.AbstractTransformer
                  org.apache.cocoon.transformation.IncludeTransformer

All Implemented Interfaces:

Poolable, Recyclable, Component, Configurable, LogEnabled, Serviceable, CacheableProcessingComponent, SitemapModelComponent, Transformer, XMLPipe, XMLProducer, XMLConsumer, ContentHandler, LexicalHandler

public class IncludeTransformer
extends AbstractTransformer
implements Serviceable, Configurable, 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. Setting strip-root="true" has no effect if recursive processing is enabled.

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 1304258 2012-03-23 10:09:27Z ilgrosso $

Field Summary

protected Environment	environment The Environment used within parallel threads
protected ServiceManager	manager The ServiceManager instance associated with this instance.
protected SourceResolver	resolver The SourceResolver used to resolve included URIs.
protected String	threadPool The name of the thread pool to use (for parallel processing).
protected 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	enableLogging(Logger logger) Initialize own and pipe loggers
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(XMLConsumer consumer) Set the XMLConsumer that will receive XML data.
void	setContentHandler(ContentHandler handler) Set the ContentHandler that will receive XML data.
void	setLexicalHandler(LexicalHandler handler) Set the LexicalHandler that will receive XML data.
void	setup(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.avalon.framework.logger.AbstractLogEnabled

getLogger, setupLogger, setupLogger, setupLogger

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

The SourceResolver used to resolve included URIs.

environment

protected Environment environment

The Environment used within parallel threads

validity

protected MultiSourceValidity validity

The SourceValidity instance associated with this request.

Constructor Detail

IncludeTransformer

public IncludeTransformer()

Create a new IncludeTransformer instance.

Method Detail

enableLogging

public void enableLogging(Logger logger)

Initialize own and pipe loggers

Specified by:

enableLogging in interface LogEnabled

Overrides:

enableLogging in class AbstractLogEnabled

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(SourceResolver resolver,
                  Map om,
                  String src,
                  Parameters parameters)
           throws ProcessingException,
                  SAXException,
                  IOException

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

Specified by:

setup in interface SitemapModelComponent

Throws:

ProcessingException

SAXException

IOException

See Also:

Serviceable.service(ServiceManager)

setConsumer

public void setConsumer(XMLConsumer consumer)

Description copied from class: AbstractXMLProducer

Set the XMLConsumer that will receive XML data.
This method will simply call setContentHandler(consumer) and setLexicalHandler(consumer).

Specified by:

setConsumer in interface XMLProducer

Overrides:

setConsumer in class AbstractXMLProducer

setContentHandler

public void setContentHandler(ContentHandler handler)

Description copied from class: AbstractXMLProducer

Set the ContentHandler that will receive XML data.
Subclasses may retrieve this ContentHandler instance accessing the protected super.contentHandler field.

Overrides:

setContentHandler in class AbstractXMLProducer

setLexicalHandler

public void setLexicalHandler(LexicalHandler handler)

Description copied from class: AbstractXMLProducer

Set the LexicalHandler that will receive XML data.
Subclasses may retrieve this LexicalHandler instance accessing the protected super.lexicalHandler field.

Overrides:

setLexicalHandler in class AbstractXMLProducer

recycle

public void recycle()

Recycle this component instance.

Specified by:

recycle in interface Recyclable

Overrides:

recycle in class AbstractXMLProducer

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

Overrides:

startDocument in class AbstractXMLPipe

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

Overrides:

endDocument in class AbstractXMLPipe

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

Overrides:

startPrefixMapping in class AbstractXMLPipe

Parameters:

prefix - The Namespace prefix being declared.

nsuri - The Namespace URI the prefix is mapped to.

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

Overrides:

endPrefixMapping in class AbstractXMLPipe

Parameters:

prefix - The prefix that was being mapping.

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 CacheableProcessingComponent

Returns:

The generated key or null if the component is currently not cacheable.

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 CacheableProcessingComponent

Returns:

a non null SourceValidity.

See Also:

CacheableProcessingComponent.getValidity()