|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Objectorg.apache.cocoon.util.AbstractLogEnabled
org.apache.cocoon.xml.AbstractXMLProducer
org.apache.cocoon.xml.AbstractXMLPipe
org.apache.cocoon.transformation.AbstractTransformer
org.apache.cocoon.transformation.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.
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 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 |
protected ServiceManager manager
ServiceManager instance associated with this instance.
protected String threadPool
protected org.apache.cocoon.environment.SourceResolver resolver
SourceResolver used to resolve included URIs.
protected RequestAttributes attributes
RequestAttributes used within parallel threads
protected org.apache.cocoon.environment.Environment environment
Environment used within parallel threads
protected org.apache.cocoon.components.source.impl.MultiSourceValidity validity
SourceValidity instance associated with this request.
| Constructor Detail |
public IncludeTransformer()
Create a new IncludeTransformer instance.
| Method Detail |
public void service(ServiceManager manager)
throws ServiceException
Setup the ServiceManager available for this instance.
service in interface ServiceableServiceExceptionServiceable.service(ServiceManager)
public void configure(Configuration configuration)
throws ConfigurationException
configure in interface ConfigurableConfigurationException
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.
setup in interface org.apache.cocoon.sitemap.SitemapModelComponentorg.apache.cocoon.ProcessingException
SAXException
IOExceptionServiceable.service(ServiceManager)public void setConsumer(org.apache.cocoon.xml.XMLConsumer consumer)
setConsumer in interface org.apache.cocoon.xml.XMLProducerpublic void setContentHandler(ContentHandler handler)
public void setLexicalHandler(LexicalHandler handler)
public void recycle()
Recycle this component instance.
recycle in interface RecyclableRecyclable.recycle()
public void startDocument()
throws SAXException
Receive notification of the beginning of an XML document.
startDocument in interface ContentHandlerSAXExceptionContentHandler.startDocument()
public void endDocument()
throws SAXException
Receive notification of the end of an XML document.
endDocument in interface ContentHandlerSAXExceptionContentHandler.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 ContentHandlerSAXExceptionContentHandler.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 ContentHandlerSAXExceptionContentHandler.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 org.apache.cocoon.caching.CacheableProcessingComponentCacheableProcessingComponent.getKey()public SourceValidity getValidity()
Generate (or return) the SourceValidity instance used to
possibly validate cached generations.
getValidity in interface org.apache.cocoon.caching.CacheableProcessingComponentSourceValidity.CacheableProcessingComponent.getValidity()
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||