|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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
public class IncludeTransformer
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
.
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
.
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
Example:
<i:include xmlns:i="http://apache.org/cocoon/include/1.0" src="cocoon://path/to/include" strip-root="true"/>
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>
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>
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.
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.
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 |
---|
protected ServiceManager manager
ServiceManager
instance associated with this instance.
protected String threadPool
protected SourceResolver resolver
SourceResolver
used to resolve included URIs.
protected Environment environment
Environment
used within parallel threads
protected MultiSourceValidity validity
SourceValidity
instance associated with this request.
Constructor Detail |
---|
public IncludeTransformer()
Create a new IncludeTransformer
instance.
Method Detail |
---|
public void enableLogging(Logger logger)
Initialize own and pipe
loggers
enableLogging
in interface LogEnabled
enableLogging
in class AbstractLogEnabled
public void service(ServiceManager manager) throws ServiceException
Setup the ServiceManager
available for this instance.
service
in interface Serviceable
ServiceException
Serviceable.service(ServiceManager)
public void configure(Configuration configuration) throws ConfigurationException
configure
in interface Configurable
ConfigurationException
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.
setup
in interface SitemapModelComponent
ProcessingException
SAXException
IOException
Serviceable.service(ServiceManager)
public void setConsumer(XMLConsumer consumer)
AbstractXMLProducer
XMLConsumer
that will receive XML data.
setContentHandler(consumer)
and setLexicalHandler(consumer)
.
setConsumer
in interface XMLProducer
setConsumer
in class AbstractXMLProducer
public void setContentHandler(ContentHandler handler)
AbstractXMLProducer
ContentHandler
that will receive XML data.
ContentHandler
instance
accessing the protected super.contentHandler
field.
setContentHandler
in class AbstractXMLProducer
public void setLexicalHandler(LexicalHandler handler)
AbstractXMLProducer
LexicalHandler
that will receive XML data.
LexicalHandler
instance
accessing the protected super.lexicalHandler
field.
setLexicalHandler
in class AbstractXMLProducer
public void recycle()
Recycle this component instance.
recycle
in interface Recyclable
recycle
in class AbstractXMLProducer
Recyclable.recycle()
public void startDocument() throws SAXException
Receive notification of the beginning of an XML document.
startDocument
in interface ContentHandler
startDocument
in class AbstractXMLPipe
SAXException
ContentHandler.startDocument()
public void endDocument() throws SAXException
Receive notification of the end of an XML document.
endDocument
in interface ContentHandler
endDocument
in class AbstractXMLPipe
SAXException
ContentHandler.startDocument()
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.
startPrefixMapping
in interface ContentHandler
startPrefixMapping
in class AbstractXMLPipe
prefix
- The Namespace prefix being declared.nsuri
- The Namespace URI the prefix is mapped to.
SAXException
ContentHandler.startPrefixMapping(String, String)
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.
endPrefixMapping
in interface ContentHandler
endPrefixMapping
in class AbstractXMLPipe
prefix
- The prefix that was being mapping.
SAXException
ContentHandler.endPrefixMapping(java.lang.String)
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.
getKey
in interface CacheableProcessingComponent
null
if the component
is currently not cacheable.CacheableProcessingComponent.getKey()
public SourceValidity getValidity()
Generate (or return) the SourceValidity
instance used to
possibly validate cached generations.
getValidity
in interface CacheableProcessingComponent
SourceValidity
.CacheableProcessingComponent.getValidity()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |