org.apache.cocoon.transformation
Class LinkRewriterTransformer

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.AbstractSAXTransformer
                      extended byorg.apache.cocoon.transformation.LinkRewriterTransformer
All Implemented Interfaces:
Configurable, ContentHandler, Disposable, Initializable, LexicalHandler, Poolable, Recyclable, Serviceable, org.apache.cocoon.sitemap.SitemapModelComponent, org.apache.cocoon.transformation.Transformer, org.apache.cocoon.xml.XMLConsumer, XMLConsumer, org.apache.cocoon.xml.XMLPipe, org.apache.cocoon.xml.XMLProducer

public class LinkRewriterTransformer
extends org.apache.cocoon.transformation.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">

InputModule Configuration

InputModules are configured twice; first statically in cocoon.xconf, and then dynamically at runtime, with dynamic configuration (if any) taking precedence. Transformer 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 within <input-module> tags:

  <map:transformer name="linkrewriter"
      src="org.apache.cocoon.transformation.LinkRewriterTransformer">
    <link-attrs>href src</link-attrs>
    <schemes>site ext</schemes>
    <input-module name="site">
      <file src="cocoon://samples/link/linkmap" reloadable="true"/>
    </input-module>
    <input-module name="mapper">
      <input-module name="site">
        <file src="{src}" reloadable="true"/>
      </input-module>
      <prefix>/site/</prefix>
      <suffix>/@href</suffix>
    </input-module>
  </map:transformer>
 
Here, we have first configured which attributes to examine, and which URL schemes to consider rewriting. In this example, <a href="site:index"> would be processed. See below for more configuration options.

Then, 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, 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:

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

A live example of LinkRewriterTransformer can be found in the Apache Forrest sitemap.

Transformer Configuration

The following configuration entries in map:transformer block are recognised:

link-attrs
Space-separated list of attributes to consider links (to be transformed). The whole value of the attribute is considered link and transformed.
link-attr
0..n of these elements each specify an attribute containing link(s) (to be transformed) and optionally a regular expression to locate substring(s) of the attribute value considered link(s). Has two attributes:
name
(required) name of the attribute whose value contains link(s).
pattern
(optional) regular expression such that when matched against the attribute value, all parenthesized expressions (except number 0) will be considered links that should be transformed. If absent, the whole value of the attribute is considered to be a link, as if the attribute was included in 'link-attrs'.
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. Defaults to 'http https ftp news mailto'.
bad-link-str
String to use for links with a correct InputModule prefix, but no value therein. Defaults to the original URI.
namespace-uri
The namespace uri of elements whose attributes are considered for transformation. Defaults to the empty namespace ("").

The attributes considered to contain links are a set of the attributes specified in 'link-attrs' element and all 'link-attr' elements. Each attribute should be specified only once either in 'link-attrs' or 'link-attr'; i.e. an attribute can have at most 1 regular expression associated with it. If neither 'link-attrs' nor 'link-attr' configuration is present, defaults to 'href'.

Below is an example of regular expression usage that will transform links x1 and x2 in <action target="foo url(x1) bar url(x2)"/>:

   <map:transformer name="linkrewriter"
       src="org.apache.cocoon.transformation.LinkRewriterTransformer">
     <link-attr name="target" pattern="(?:url\((.*?)\).*?){1,2}$"/>
     <!-- additional configuration ... -->
   </map:transformer>
 

When matched against the value of target attribute above, the parenthesized expressions are:
$0 = url(x1) bar url(x2)
$1 = x1
$2 = x2

Expression number 0 is always discarded by the transformer and the rest are considered links and re-written.

If present, map:parameter's from the map:transform block override the corresponding configuration entries from map:transformer. As an exception, 'link-attr' parameters are not recognised; 'link-attrs' parameter overrides both 'link-attrs' and 'link-attr' configuration.

Version:
$Id: LinkRewriterTransformer.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Field Summary
 
Fields inherited from class org.apache.cocoon.transformation.AbstractSAXTransformer
context, defaultNamespaceURI, EMPTY_ATTRIBUTES, ignoreEmptyCharacters, ignoreEventsCount, ignoreHooksCount, ignoreWhitespaces, manager, namespaceURI, objectModel, parameters, recorderStack, removeOurNamespacePrefixes, 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
LinkRewriterTransformer()
           
 
Method Summary
 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(org.apache.cocoon.environment.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, characters, 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.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.apache.cocoon.xml.XMLProducer
setConsumer
 

Constructor Detail

LinkRewriterTransformer

public LinkRewriterTransformer()
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
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(org.apache.cocoon.environment.SourceResolver resolver,
                  Map objectModel,
                  String src,
                  Parameters parameters)
           throws org.apache.cocoon.ProcessingException,
                  SAXException,
                  IOException
Setup this component to handle a map:transform instance.

Specified by:
setup in interface org.apache.cocoon.sitemap.SitemapModelComponent
Throws:
org.apache.cocoon.ProcessingException
SAXException
IOException

recycle

public void recycle()
Recycle this component for use in another map:transform.

Specified by:
recycle in interface Recyclable

startTransformingElement

public void startTransformingElement(String uri,
                                     String name,
                                     String raw,
                                     Attributes attr)
                              throws org.apache.cocoon.ProcessingException,
                                     IOException,
                                     SAXException
Start processing elements of our namespace. This hook is invoked for each sax event with our namespace.

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:
org.apache.cocoon.ProcessingException
IOException
SAXException

dispose

public void dispose()
Specified by:
dispose in interface Disposable


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