org.apache.cocoon.transformation
Class VariableRewriterTransformer

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.AbstractSAXTransformer
                      org.apache.cocoon.transformation.VariableRewriterTransformer

All Implemented Interfaces:

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

public class VariableRewriterTransformer
extends AbstractSAXTransformer
implements Initializable, Disposable

Rewrites URIs in links to a value determined by an InputModule. The URI scheme identifies the InputModule to use, and the rest of the URI is used as the attribute name.

Example

For instance, if we had an XMLFileModule, configured to read values from an XML file:

 <site>
   <faq>
     <how_to_boil_eggs href="faq/eggs.html"/>
   </faq>
 </site>
 

mapped to the prefix 'site:', then <link href="site:/site/faq/how_to_boil_eggs/@href"> would be replaced with <link href="faq/eggs.html">

InputModules are configured twice; first statically in cocoon.xconf, and then dynamically at runtime, with dynamic configuration (if any) taking precedence. VariableRewriterTransformer allows you to pass a dynamic configuration to used InputModules as follows.

First, a template Configuration is specified in the static <map:components> block of the sitemap:

  <map:transformer name="linkrewriter"
    src="org.apache.cocoon.transformation.VariableRewriterTransformer">
    <input-module name="site" src="cocoon://samples/link/linkmap" reloadable="true"/>
    <input-module name="mapper">
      <input-module name="site" src="{src}" reloadable="true"/>
      <prefix>/site/</prefix>
      <suffix>/@href</suffix>
    </input-module>
  </map:transformer>
 

Here, we have established dynamic configuration templates for two modules, 'site' (an XMLFileModule and 'mapper' (A SimpleMappingMetaModule. All other InputModules will use their static configs. Note that the dynamic config syntax different to the static config syntax (attributes instead of elements). Note also that, when configuring a Meta InputModule like 'mapper', we need to also configure the 'inner' module (here, 'site') with a nested <input-module>.

There is one further twist; to have really dynamic configuration, we need information available only when the transformer actually runs. This is why the above config was called a "template" Configuration; it needs to be 'instantiated' and provided extra info, namely:

• The {src} string will be replaced with the map:transform @src attribute value.
• Any other {variables} will be replaced with map:parameter values

With the above config template, we can have a matcher like:

    <map:match pattern="**welcome">
      <map:generate src="index.xml"/>
      <map:transform type="linkrewriter" src="cocoon:/{1}linkmap"/>
      <map:serialize type="xml"/>
    </map:match>
 

Which would cause the 'mapper' XMLFileModule to be configured with a different XML file, depending on the request.

Similarly, we could use a dynamic prefix:

      <prefix>{prefix}</prefix>
 

in the template config, and:

   <map:parameter name="prefix" value="/site/"/>
 

in the map:transform

Configuration

The following map:parameter's are recognised:

link-attrs

Space-separated list of attributes to consider links (to be transformed). Defaults to 'href'.

schemes

Space-separated list of URI schemes to explicitly include. If specified, all URIs with unlisted schemes will not be converted.

exclude-schemes

Space-separated list of URI schemes to explicitly exclude.

bad-link-str

String to use for links with a correct InputModule prefix, but no value therein. Defaults to the original URI.

Note that currently, only links in the default ("") namespace are converted.

Version:

$Id: VariableRewriterTransformer.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Author:

Jeff Turner

Field Summary

Fields inherited from class org.apache.cocoon.transformation.AbstractSAXTransformer

context, defaultNamespaceURI, EMPTY_ATTRIBUTES, emptyAttributes, ignoreEmptyCharacters, ignoreEventsCount, ignoreHooksCount, ignoreWhitespaces, manager, namespaceURI, objectModel, parameters, recorderStack, request, resolver, response, source, stack

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

VariableRewriterTransformer()

Method Summary

void	characters(char[] p0, int p1, int p2) Process the SAX event.
void	configure(Configuration conf) Configure this component from the map:transformer block.
void	dispose()
void	initialize() Initiate resources prior to this component becoming active.
void	recycle() Recycle this component for use in another map:transform.
void	setup(SourceResolver resolver, Map objectModel, String src, Parameters parameters) Setup this component to handle a map:transform instance.
void	startTransformingElement(String uri, String name, String raw, Attributes attr) Start processing elements of our namespace.

Methods inherited from class org.apache.cocoon.transformation.AbstractSAXTransformer

addRecorder, comment, endCDATA, endDocument, endDTD, endElement, endEntity, endParametersRecording, endParametersRecording, endPrefixMapping, endRecording, endSAXRecording, endSerializedXMLRecording, endTextRecording, endTransformingElement, findPrefixMapping, getMutableAttributes, ignorableWhitespace, processingInstruction, removeRecorder, sendEndElementEvent, sendEndElementEventNS, sendEndPrefixMapping, sendEvents, sendParametersEvents, sendStartElementEvent, sendStartElementEvent, sendStartElementEventNS, sendStartElementEventNS, sendStartPrefixMapping, sendTextEvent, service, setDocumentLocator, setupTransforming, skippedEntity, startCDATA, startDocument, startDTD, startElement, startEntity, startParametersRecording, startPrefixMapping, startRecording, startSAXRecording, startSerializedXMLRecording, startTextRecording

Methods inherited from class org.apache.cocoon.xml.AbstractXMLProducer

setConsumer, setContentHandler, setLexicalHandler

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, 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.apache.cocoon.xml.XMLProducer

setConsumer

Constructor Detail

VariableRewriterTransformer

public VariableRewriterTransformer()

Method Detail

configure

public void configure(Configuration conf)
               throws ConfigurationException

Configure this component from the map:transformer block. Called before initialization and setup.

Specified by:

configure in interface Configurable

Overrides:

configure in class AbstractSAXTransformer

Throws:

ConfigurationException

initialize

public void initialize()
                throws Exception

Initiate resources prior to this component becoming active.

Specified by:

initialize in interface Initializable

Throws:

Exception

setup

public void setup(SourceResolver resolver,
                  Map objectModel,
                  String src,
                  Parameters parameters)
           throws ProcessingException,
                  SAXException,
                  IOException

Setup this component to handle a map:transform instance.

Specified by:

setup in interface SitemapModelComponent

Overrides:

setup in class AbstractSAXTransformer

Throws:

ProcessingException

SAXException

IOException

startTransformingElement

public void startTransformingElement(String uri,
                                     String name,
                                     String raw,
                                     Attributes attr)
                              throws ProcessingException,
                                     IOException,
                                     SAXException

Start processing elements of our namespace. This hook is invoked for each sax event with our namespace.

Overrides:

startTransformingElement in class AbstractSAXTransformer

Parameters:

uri - The namespace of the element.

name - The local name of the element.

raw - The qualified name of the element.

attr - The attributes of the element.

Throws:

ProcessingException

IOException

SAXException

characters

public void characters(char[] p0,
                       int p1,
                       int p2)
                throws SAXException

Process the SAX event.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class AbstractSAXTransformer

Parameters:

p0 - The characters from the XML document.

p1 - The start position in the array.

p2 - The number of characters to read from the array.

Throws:

SAXException

See Also:

ContentHandler.characters(char[], int, int)

recycle

public void recycle()

Recycle this component for use in another map:transform.

Specified by:

recycle in interface Recyclable

Overrides:

recycle in class AbstractSAXTransformer

dispose

public void dispose()

Specified by:

dispose in interface Disposable

Overrides:

dispose in class AbstractSAXTransformer