org.apache.cocoon.transformation
Class IncludeTransformer

java.lang.Object
  extended byorg.apache.cocoon.util.AbstractLogEnabled
      extended byorg.apache.cocoon.xml.AbstractXMLProducer
          extended byorg.apache.cocoon.xml.AbstractXMLPipe
              extended byorg.apache.cocoon.transformation.AbstractTransformer
                  extended byorg.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()


Copyright 1999-2008 The Apache Software Foundation. All Rights Reserved.