org.apache.cocoon.transformation
Class IncludeTransformer

java.lang.Object
  extended by org.apache.avalon.framework.logger.AbstractLogEnabled
      extended by org.apache.cocoon.xml.AbstractXMLProducer
          extended by org.apache.cocoon.xml.AbstractXMLPipe
              extended by org.apache.cocoon.transformation.AbstractTransformer
                  extended by 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()


Copyright © 1999-2010 The Apache Software Foundation. All Rights Reserved.