AbstractSAXTransformer (Cocoon Pipeline Implementation 1.0.0 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.cocoon.transformation
Class AbstractSAXTransformer

java.lang.Object
  org.apache.cocoon.util.AbstractLogEnabled
      org.apache.cocoon.xml.AbstractXMLProducer
          org.apache.cocoon.xml.AbstractXMLPipe
              org.apache.cocoon.transformation.AbstractTransformer
                  org.apache.cocoon.transformation.AbstractSAXTransformer

All Implemented Interfaces:: Configurable, ContentHandler, Disposable, LexicalHandler, Poolable, Recyclable, Serviceable, org.apache.cocoon.sitemap.SitemapModelComponent, org.apache.cocoon.transformation.Transformer, XMLConsumer, org.apache.cocoon.xml.XMLConsumer, org.apache.cocoon.xml.XMLPipe, org.apache.cocoon.xml.XMLProducer

public abstract class AbstractSAXTransformer
extends AbstractTransformer
implements Serviceable, Configurable, Disposable

This class is the basis for all transformers. It provides various useful methods and hooks for implementing own custom transformers.

The basic behaviour of each transformer consists of the following four parts:

Listen for specific events with a given namespace
Collect information via these events
Process the information
Create new events from the processed information

For all these four purposes the AbstractSAXTransformer offers some powerful methods and hooks:

Namespace handling

By setting the instance variable namespaceURI to the namespace the events are filtered and only events with this namespace are send to the two hooks: startTransformingElement and endTransformingElement. It is possible to override the default namespace for the transformer by specifying the parameter "namespaceURI" in the pipeline. This avoids possible namespace collisions.

Recording of information

There are several methods for recording information, e.g. startRecording(), startTextRecording() etc. These methods collect information from the xml stream for further processing.

Creating new events

New events can be easily created with the sendEvents() method, the sendStartElementEvent() methods, the sendEndElementEvent() method or the sendTextEvent() method.

Initialization

Before the document is processed the setupTransforming hook is invoked.

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

Field Summary
`protected org.apache.cocoon.environment.Context`	`context` The current Context object
`protected String`	`defaultNamespaceURI` This is the default namespace used by the transformer.
`protected static Attributes`	`EMPTY_ATTRIBUTES` Empty immutable attributes (for performance).
`protected boolean`	`ignoreEmptyCharacters` Controlls SAX event handling.
`protected int`	`ignoreEventsCount` Controlls SAX event handling.
`protected int`	`ignoreHooksCount` Controlls SAX event handling.
`protected boolean`	`ignoreWhitespaces` Controlls SAX event handling.
`protected ServiceManager`	`manager` The Avalon ServiceManager for getting Components
`protected String`	`namespaceURI` The namespace used by the transformer for the SAX events filtering.
`protected Map`	`objectModel` The current objectModel of the environment
`protected Parameters`	`parameters` The parameters specified in the sitemap
`protected Stack`	`recorderStack` The stack of current used recorders
`protected boolean`	`removeOurNamespacePrefixes` Remove namespace prefixes for our namespace?
`protected org.apache.cocoon.environment.Request`	`request` The current Request object
`protected org.apache.cocoon.environment.SourceResolver`	`resolver` The SourceResolver for this request
`protected org.apache.cocoon.environment.Response`	`response` The current Response object
`protected String`	`source` The source attribute specified in the sitemap
`protected Stack`	`stack` A stack for collecting information.

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
`AbstractSAXTransformer()`

Method Summary
`protected void`	`addRecorder(org.apache.cocoon.xml.XMLConsumer recorder)` Add a new recorder to the recording chain.
`void`	`characters(char[] p0, int p1, int p2)` Process the SAX event.
`void`	`comment(char[] ary, int start, int length)` Report an XML comment anywhere in the document.
`void`	`configure(Configuration configuration)`
`void`	`dispose()`
`void`	`endCDATA()` Report the end of a CDATA section.
`void`	`endDocument()` Process the SAX event.
`void`	`endDTD()` Report the end of DTD declarations.
`void`	`endElement(String uri, String name, String raw)` Process the SAX event.
`void`	`endEntity(String name)` Report the end of an entity.
`SourceParameters`	`endParametersRecording(Parameters additionalParameters)` End recording of parameters If source is null a new parameters object is created, otherwise the parameters are added to this object.
`SourceParameters`	`endParametersRecording(SourceParameters additionalParameters)` End recording of parameters If source is null a new parameters object is created, otherwise the parameters are added to this object.
`void`	`endPrefixMapping(String prefix)` Process the SAX event.
`DocumentFragment`	`endRecording()` Stop DOM DocumentFragment recording.
`XMLizable`	`endSAXRecording()` Stop recording of SAX events.
`String`	`endSerializedXMLRecording()` Return the serialized xml string.
`String`	`endTextRecording()` Stop recording of text and return the recorded information.
`void`	`endTransformingElement(String uri, String name, String raw)` Start processing elements of our namespace.
`protected String`	`findPrefixMapping(String uri)` Find prefix mapping for the given namespace URI.
`protected AttributesImpl`	`getMutableAttributes(Attributes a)` Helper method to get a modifiable attribute set.
`void`	`ignorableWhitespace(char[] p0, int p1, int p2)` Process the SAX event.
`void`	`processingInstruction(String target, String data)` Process the SAX event.
`void`	`recycle()` Recycle the producer by removing references, and resetting handlers to null (empty) implementations.
`protected Object`	`removeRecorder()` Remove a recorder from the recording chain.
`void`	`sendEndElementEvent(String localname)` Send SAX events to the next pipeline component.
`void`	`sendEndElementEventNS(String localname)` Send SAX events to the next pipeline component.
`protected void`	`sendEndPrefixMapping()` Send all end prefix mapping events to the current content handler
`void`	`sendEvents(Node node)` Send SAX events to the next pipeline component.
`void`	`sendParametersEvents(SourceParameters pars)` Send SAX events for the `SourceParameters`.
`void`	`sendStartElementEvent(String localname)` Send SAX events to the next pipeline component.
`void`	`sendStartElementEvent(String localname, Attributes attr)` Send SAX events to the next pipeline component.
`void`	`sendStartElementEventNS(String localname)` Send SAX events to the next pipeline component.
`void`	`sendStartElementEventNS(String localname, Attributes attr)` Send SAX events to the next pipeline component.
`protected void`	`sendStartPrefixMapping()` Send all start prefix mapping events to the current content handler
`void`	`sendTextEvent(String text)` Send SAX events to the next pipeline component.
`void`	`service(ServiceManager aManager)`
`void`	`setDocumentLocator(Locator locator)` Process the SAX event.
`void`	`setup(org.apache.cocoon.environment.SourceResolver resolver, Map objectModel, String src, Parameters params)`
`void`	`setupTransforming()` Setup the transformation of an xml document.
`void`	`skippedEntity(String name)` Process the SAX event.
`void`	`startCDATA()` Report the start of a CDATA section.
`void`	`startDocument()` Process the SAX event.
`void`	`startDTD(String name, String public_id, String system_id)` Report the start of DTD declarations, if any.
`void`	`startElement(String uri, String name, String raw, Attributes attr)` Process the SAX event.
`void`	`startEntity(String name)` Report the beginning of an entity.
`void`	`startParametersRecording()` Start recording of parameters.
`void`	`startPrefixMapping(String prefix, String uri)` Process the SAX event.
`void`	`startRecording()` Start DOM DocumentFragment recording.
`void`	`startSAXRecording()` Start recording of SAX events.
`void`	`startSerializedXMLRecording(Properties format)` Start recording of serialized xml All events are converted to an xml string which can be retrieved by endSerializedXMLRecording.
`void`	`startTextRecording()` Start recording of a text.
`void`	`startTransformingElement(String uri, String name, String raw, Attributes attr)` Start processing elements of our namespace.

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

Field Detail

EMPTY_ATTRIBUTES

protected static final Attributes EMPTY_ATTRIBUTES

Empty immutable attributes (for performance). Use them whenever creating an element with no attributes.

ignoreWhitespaces

protected boolean ignoreWhitespaces

Controlls SAX event handling. If set to true all whitespace events are ignored.

ignoreEmptyCharacters

protected boolean ignoreEmptyCharacters

Controlls SAX event handling. If set to true all characters events containing only whitespaces are ignored.

ignoreEventsCount

protected int ignoreEventsCount

Controlls SAX event handling. If this is incremented all events are not forwarded to the next pipeline component, but the hooks are still called.

ignoreHooksCount

protected int ignoreHooksCount

Controlls SAX event handling. If this is greater than zero, the hooks are not called. Attention, make sure, that you decrement this counter properly as your hooks are not called anymore!

namespaceURI

protected String namespaceURI

The namespace used by the transformer for the SAX events filtering. This either equals to the defaultNamespaceURI or to the value set by the namespaceURI sitemap parameter for the pipeline. Must never be null.

defaultNamespaceURI

protected String defaultNamespaceURI

This is the default namespace used by the transformer. Implementations should set its value in the constructor. Must never be null.

stack

protected final Stack stack

A stack for collecting information. The stack is important for collection information especially when the tags can be nested.

recorderStack

protected final Stack recorderStack

The stack of current used recorders

request

protected org.apache.cocoon.environment.Request request

The current Request object

response

protected org.apache.cocoon.environment.Response response

The current Response object

context

protected org.apache.cocoon.environment.Context context

The current Context object

objectModel

protected Map objectModel

The current objectModel of the environment

parameters

protected Parameters parameters

The parameters specified in the sitemap

source

protected String source

The source attribute specified in the sitemap

manager

protected ServiceManager manager

The Avalon ServiceManager for getting Components

resolver

protected org.apache.cocoon.environment.SourceResolver resolver

The SourceResolver for this request

removeOurNamespacePrefixes

protected boolean removeOurNamespacePrefixes

Remove namespace prefixes for our namespace?

Since:: 2.2

Constructor Detail

AbstractSAXTransformer

public AbstractSAXTransformer()

Method Detail

service

public void service(ServiceManager aManager)
             throws ServiceException

Specified by:: service in interface Serviceable

Throws:: ServiceException
See Also:: Serviceable.service(ServiceManager)

configure

public void configure(Configuration configuration)
               throws ConfigurationException

Specified by:: configure in interface Configurable

Throws:: ConfigurationException
See Also:: Configurable.configure(Configuration)

setup

public void setup(org.apache.cocoon.environment.SourceResolver resolver,
                  Map objectModel,
                  String src,
                  Parameters params)
           throws org.apache.cocoon.ProcessingException,
                  SAXException,
                  IOException

Specified by:: setup in interface org.apache.cocoon.sitemap.SitemapModelComponent

Throws:: org.apache.cocoon.ProcessingException; SAXException; IOException
See Also:: SitemapModelComponent.setup(SourceResolver, Map, String, Parameters)

recycle

public void recycle()

Description copied from class: AbstractXMLProducer

Recycle the producer by removing references, and resetting handlers to null (empty) implementations.

Specified by:: recycle in interface Recyclable
Overrides:: recycle in class AbstractXMLProducer

See Also:: Recyclable.recycle()

dispose

public void dispose()

Specified by:: dispose in interface Disposable

See Also:: Disposable.dispose()

setDocumentLocator

public void setDocumentLocator(Locator locator)

Process the SAX event.

Specified by:: setDocumentLocator in interface ContentHandler
Overrides:: setDocumentLocator in class AbstractXMLPipe

Parameters:: locator - An object that can return the location of any SAX document event.
See Also:: ContentHandler.setDocumentLocator(org.xml.sax.Locator)

startDocument

public void startDocument()
                   throws SAXException

Process the SAX event. A new document is processed. The hook method setupTransforming() is invoked.

Specified by:: startDocument in interface ContentHandler
Overrides:: startDocument in class AbstractXMLPipe

Throws:: SAXException
See Also:: ContentHandler.startDocument()

endDocument

public void endDocument()
                 throws SAXException

Process the SAX event. The processing of the document is finished.

Specified by:: endDocument in interface ContentHandler
Overrides:: endDocument in class AbstractXMLPipe

Throws:: SAXException
See Also:: ContentHandler.endDocument()

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

Process the SAX event.

Specified by:: startPrefixMapping in interface ContentHandler
Overrides:: startPrefixMapping in class AbstractXMLPipe

Parameters:: prefix - The Namespace prefix being declared.; uri - The Namespace URI the prefix is mapped to.
Throws:: SAXException
See Also:: ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Process the SAX event.

Specified by:: endPrefixMapping in interface ContentHandler
Overrides:: endPrefixMapping in class AbstractXMLPipe

Parameters:: prefix - The prefix that was being mapping.
Throws:: SAXException
See Also:: ContentHandler.endPrefixMapping(java.lang.String)

startElement

public void startElement(String uri,
                         String name,
                         String raw,
                         Attributes attr)
                  throws SAXException

Process the SAX event. The namespace of the event is checked. If it is the defined namespace for this transformer, the startTransformingElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes) hook is called.

Specified by:: startElement in interface ContentHandler
Overrides:: startElement in class AbstractXMLPipe

Parameters:: uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.; name - The local name (without prefix), or the empty string if Namespace processing is not being performed.; raw - The raw XML 1.0 name (with prefix), or the empty string if raw names are not available.; attr - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.
Throws:: SAXException
See Also:: ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endElement

public void endElement(String uri,
                       String name,
                       String raw)
                throws SAXException

Process the SAX event. The namespace of the event is checked. If it is the defined namespace for this transformer, the endTransformingElement(java.lang.String, java.lang.String, java.lang.String) hook is called.

Specified by:: endElement in interface ContentHandler
Overrides:: endElement in class AbstractXMLPipe

Parameters:: uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.; name - The local name (without prefix), or the empty string if Namespace processing is not being performed.; raw - The raw XML 1.0 name (with prefix), or the empty string if raw names are not available.
Throws:: SAXException
See Also:: ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

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 AbstractXMLPipe

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)

ignorableWhitespace

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

Process the SAX event.

Specified by:: ignorableWhitespace in interface ContentHandler
Overrides:: ignorableWhitespace in class AbstractXMLPipe

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.ignorableWhitespace(char[], int, int)

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException

Process the SAX event.

Specified by:: processingInstruction in interface ContentHandler
Overrides:: processingInstruction in class AbstractXMLPipe

Parameters:: target - The processing instruction target.; data - The processing instruction data, or null if none was supplied.
Throws:: SAXException
See Also:: ContentHandler.processingInstruction(java.lang.String, java.lang.String)

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

Process the SAX event.

Specified by:: skippedEntity in interface ContentHandler
Overrides:: skippedEntity in class AbstractXMLPipe

Parameters:: name - The name of the skipped entity. If it is a parameter entity, the name will begin with '%'.
Throws:: SAXException
See Also:: ContentHandler.skippedEntity(java.lang.String)