Rewriting the output through pipelines has been edited by Mike Mueller (Apr 28, 2009).

(View changes)

Content:

Apache Sling Rewriter

The Apache Sling rewriter is a module rewritten the output from Sling by a SAX based pipeline or a single component (called a Processor).

SAX Pipelines

The rewriter allows to configure a pipeline for post processing of the generated response.

The pipeline starts with a generator. The generator gets the output from Sling. It's the task of the generator to generate SAX events (XML) and stream these into the pipeline. A transformer is a component in the middle of the pipeline, a pipeline can have zero to n transformers. The transformer receives SAX events from the previous component in the pipeline and sends SAX events to the next component in the pipeline. A transformer can remove events, change events, add events or just pass the events. The pipeline ends with a serializer collecting all SAX events and writing the output to a provided output stream.

Sling contains a default pipeline which is executed for all html responses: it starts with an html generator, parsing the html output and sending events into the pipeline. A html serializer collects all events and serializes the output.

The pipelines can be configured in the repository as a child node of /apps/APPNAME/config/rewriter (or /libs/APPNAME/config/rewriterg). (In fact the configured search paths of the resource resolver are observed.) Each node can have the following properties:

  • generatorType - the type of the generator (required)
  • serializerType - the type of the serializer (required)
  • transformerTypes (multivalue string) - the types of the transformers (optional)
  • paths (multivalue string) - the paths this pipeline should run on (content paths)
  • contentTypes (multivalue string) - the content types this pipeline should be used for (optional)
  • order (long) - the configurations are sorted by this order, order must be higher or equal to 0. The configuration with the highest order is tried first.
  • enabled (boolean) - Is this configuration active? (default yes)

If a component needs a configuration, the configuration is stored in a child node which name is COMPONENTTYPE-NAME, e.g. to configure the html generator (named html-generator), the node should have the name generator-html-generator.

Configuring the HTML Generator

By default the used html generator only generates events for some of the html tags. If you want to change this, create a pipeline config like outlined above for the pipeline and configure the html generator by adding the generator-html-generator node with a multi value string property named includeTags. The values define the tags, the parser uses.

Default Pipeline

The default pipeline is configured for the text/html mime type and consists of the html-generator as generator, and the html-serializer for generating the final response.

Implementing Pipeline Components

Each pipeline component type has a corresponding Java interface (Generator, Transformer, Serializer). When implementing such a component, this has to be registered as a service factory for the given type, like this:

@scr.component metatype="no" factory="org.apache.sling.rewriter.Transformer/validator"

The factory information has always to be set to the full name of the Java interface, followed by a slash, followed by a unique name for this component. The pipeline configuration in the repository just references this unique name (like validator).

Extending the Pipeline

It is possible to extend each pipeline by rewriter transformers at the beginning and at the end. This allows a more flexible way of customizing the pipeline without changing/adding a configuration in the repository.

The approach here is a little bit different but nearly the same. Instead of directly implementing the Transformer interface, the customizing can be done by implementing a RewriterTransformerFactory and use the following ~SCR properties:

@scr.component metatype="no"
@scr.service interface="RewriterTransformerFactory"
@scr.property name="service.ranking" value="RANKING" type="Integer"

RANKING 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.

The RewriterTransformerFactory 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.

Implementing a Processor

A processor must conform to the Java interface org.apache.sling.rewriter.Processor. It gets initializd (method init) with the ProcessingContext. This context contains all necessary information for the current request (especially the output writer to write the rewritten content to).
The getWriter method should return a writer where the output is written to. When the output is written or an error occured finished is called.

Each processor has to be registered as a service factory, like this:

@scr.component metatype="no" factory="org.apache.sling.rewriter.Processor/uniqueName"

Configuring a Processor

The processors can be configured in the repository as a child node of /apps/APPNAME/config/rewriter (or libs or any configured search path). Each node can have the following properties:

  • 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 uniqueName)
  • paths (multivalue string) - the paths this processor should run on (content paths)
  • contentTypes (multivalue string) - the content types this processor should be used for (optional)
  • order (long) - the configurations are sorted by this order, order must be higher or equal to 0. The configuration with the highest order is tried first.
  • enabled (boolean) - Is this configuration active? (default yes)

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences