The Apache Sling rewriter is a module rewritten the output from Sling by a SAX based pipeline or a single component (called a Processor).
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:
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.
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.
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.
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).
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.
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).
Each processor has to be registered as a service factory, like this:
@scr.component metatype="no" factory="org.apache.sling.rewriter.Processor/uniqueName"
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: