You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2015/07/13 09:45:28 UTC
svn commit: r958088 - in /websites/staging/sling/trunk/content: ./
documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
Author: buildbot
Date: Mon Jul 13 07:45:27 2015
New Revision: 958088
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jul 13 07:45:27 2015
@@ -1 +1 @@
-1690313
+1690577
Modified: websites/staging/sling/trunk/content/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html Mon Jul 13 07:45:27 2015
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><strong><a href="/documentation.html">Documentation</a></strong> <br />
<a href="/documentation/getting-started.html">Getting Started</a> <br />
<a href="/documentation/the-sling-engine.html">The Sling Engine</a> <br />
<a href="/documentation/development.html">Development</a> <br />
@@ -90,9 +101,20 @@
<h1>Output Rewriting Pipelines (org.apache.sling.rewriter)</h1>
- <p>The Apache Sling Rewriter is a module for rewriting the output generated by a usual Sling rendering process. Some possible use cases include rewriting or checking all links in an html page, manipulating the html page, or using the generated output as the base for further transformation. An example of futher transformation is to use XSLT to transform rendered XML to some output format like HTML or XSL:FO for generating PDF.</p>
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p>The Apache Sling Rewriter is a module for rewriting the output generated by a usual Sling rendering process. Some possible use cases include rewriting or checking all links in an html page, manipulating the html page, or using the generated output as the base for further transformation. An example of futher transformation is to use XSLT to transform rendered XML to some output format like HTML or XSL:FO for generating PDF.</p>
<p>For supporting these use cases, the rewriter uses the concept for a processor. The processor is a component that is injected through a servlet filter into the response. By implementing the <em>Processor</em> interface one is able to rewrite the whole response in one go. A more convenient way of processing the output is by using a so called pipeline; the Apache Sling rewriter basically uses the same concept as the famous Apache Cocoon: an XML based pipeline for further post processing of the output. The pipeline is based on SAX events.</p>
-<h2 id="sax-pipelines">SAX Pipelines</h2>
+<h2 id="sax-pipelines">SAX Pipelines<a class="headerlink" href="#sax-pipelines" title="Permanent link">¶</a></h2>
<p>The rewriter allows to configure a pipeline for post processing of the generated response. Depending on how the pipeline is assembled the rewriting process might buffer the whole output in order to do proper post processing - for example this is required if an HTML response is "transformed" to XHTML or if XSLT is used to process the response.</p>
<p>As the pipeline is based on SAX events, there needs to be a component that generates these events and sends them through the pipeline. By default the Sling rendering scripts write to an output stream, so there is a need to parse this output and generate the SAX events.</p>
<p>The first component in the pipeline generating the initial SAX events is called a generator. The generator gets the output from Sling, generates SAX events (XML), and streams these events into the pipeline. The counterpart of the generator is the serializer which builds the end of the pipeline. The serializer collects all incomming SAX events, transforms them into the required response by writing into output stream of the response.</p>
@@ -113,10 +135,10 @@
</ul>
<p>As you can see from the configuration there are several possibilities to define when a pipeline should be used for a response, like paths, extensions, content types, or resource types. It is possible to specify several of them at once. In this case all conditions must be met.</p>
<p>If a component needs a configuration, the configuration is stored in a child node which name is <em>{componentType}-{name}</em>, e.g. to configure the html generator (named <em>html-generator</em>), the node should have the name <em>generator-html-generator</em>. In the case that the pipeline contains the same transformer several times, the configuration child node should have the formant <em>{componentType}-{index}</em> where index is the index of the transformer starting with 1. For example if you have a pipeline with the following transformers, xslt, html-cleaner, xslt, link-checker, then the configuration nodes should be named <em>transformer-1</em> (for the first xslt), <em>transformer-html-cleaner</em>, <em>transformer-3</em> (for the second xslt), and <em>transformer-link-checker</em>.</p>
-<h3 id="default-pipeline">Default Pipeline</h3>
+<h3 id="default-pipeline">Default Pipeline<a class="headerlink" href="#default-pipeline" title="Permanent link">¶</a></h3>
<p>The default pipeline is configured for the <em>text/html</em> mime type and the <em>html</em> extensions and consists of the <em>html-generator</em> as the generator, and the <em>html-serializer</em> for generating the final response.
As the html generated by Sling is not required to be valid XHTML, the html parser is using an HTML parser to create valid SAX events. In order to perform this, the generator needs to buffer the whole response first.</p>
-<h2 id="implementing-pipeline-components">Implementing Pipeline Components</h2>
+<h2 id="implementing-pipeline-components">Implementing Pipeline Components<a class="headerlink" href="#implementing-pipeline-components" title="Permanent link">¶</a></h2>
<p>Each pipeline component type has a corresponding Java interface (Generator, Transformer, and Serializer) together with a factory interface (GeneratorFactory, TransformerFactory, and SerializerFactory). When implementing such a component, both interfaces need to be implemented. The factory has only one method which creates a new instance of that type for the current request. The factory has to be registered as a service. For example if you're using the Maven SCR plugin, it looks like this:</p>
<div class="codehilite"><pre><span class="nd">@scr.component</span> <span class="n">metatype</span><span class="o">=</span><span class="s">"no"</span>
<span class="nd">@scr.service</span> <span class="n">interface</span><span class="o">=</span><span class="s">"TransformerFactory"</span>
@@ -125,7 +147,7 @@ As the html generated by Sling is not re
<p>The factory needs to implement the according interface and should be registered as a service for this factory interface (this is a plain service and not a factory service in the OSGi sense). Each factory gets a unique name through the <em>pipeline.type</em> property. The pipeline configuration in the repository just references this unique name (like validator).</p>
-<h2 id="extending-the-pipeline">Extending the Pipeline</h2>
+<h2 id="extending-the-pipeline">Extending the Pipeline<a class="headerlink" href="#extending-the-pipeline" title="Permanent link">¶</a></h2>
<p>With the possibilities from above, it is possible to define new pipelines and add custom components to the pipeline. However, in some cases it is required to just add a custom transformer to the existing pipeline. Therefore the rewriting can be configured with pre and post transformers that are simply added to each configured pipeline. This allows a more flexible way of customizing the pipeline without changing/adding a configuration in the repository.</p>
<p>The approach here is nearly the same. A transformer factory needs to be implemented, but instead of giving this factory a unique name, this factory is marked as a global factory:</p>
<div class="codehilite"><pre><span class="nd">@scr.component</span> <span class="n">metatype</span><span class="o">=</span><span class="s">"no"</span>
@@ -137,7 +159,8 @@ As the html generated by Sling is not re
<p><em>RANKING</em> is an integer value (don't forget the type attribute otherwise the ranking is interpreted as zero!) specifying where to add the transformer in the pipeline. If the value is less than zero the transformer is added at the beginning of the pipeline right after the generator. If the ranking is equal or higher as zero, the transformer is added at the end of the pipeline before the serializer.</p>
<p>The <em>TransformerFactory</em> interface has just one method which returns a new transformer instance. If you plan to use other services in your transformer you might declare the references on the factory and pass in the instances into the newly created transformer.</p>
-<h2 id="implementing-a-processor">Implementing a Processor</h2>
+<p>Since the transformer carries information about the current response it is not advisable to reuse the same transformer instance among multiple calls of <code>TransformerFactory.createTransformer</code>.</p>
+<h2 id="implementing-a-processor">Implementing a Processor<a class="headerlink" href="#implementing-a-processor" title="Permanent link">¶</a></h2>
<p>A processor must conform to the Java interface <em>org.apache.sling.rewriter.Processor</em>. It gets initializd (method <em>init</em>) with the <em>ProcessingContext</em>. This context contains all necessary information for the current request (especially the output writer to write the rewritten content to).
The <em>getWriter</em> method should return a writer where the output is written to. When the output is written or an error occured <em>finished</em> is called.</p>
<p>Like the pipeline components a processor is generated by a factory which has to be registered as a service factory, like this:</p>
@@ -147,7 +170,7 @@ The <em>getWriter</em> method should ret
</pre></div>
-<h2 id="configuring-a-processor">Configuring a Processor</h2>
+<h2 id="configuring-a-processor">Configuring a Processor<a class="headerlink" href="#configuring-a-processor" title="Permanent link">¶</a></h2>
<p>The processors can be configured in the repository as a child node of <em>/apps/APPNAME/config/rewriter</em> (or libs or any configured search path). Each node can have the following properties:</p>
<ul>
<li>processorType - the type of the processor (required) - this is the part from the scr factory information after the slash (in the example above this is <em>uniqueName</em>)</li>
@@ -160,7 +183,7 @@ The <em>getWriter</em> method should ret
<li>enabled (boolean) - Is this configuration active? (default yes)</li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1631318 by sseifert on Mon, 13 Oct 2014 08:29:00 +0000
+ Rev. 1690577 by kwin on Mon, 13 Jul 2015 07:45:14 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project