org.apache.cocoon.transformation
Class AbstractSAXTransformer

java.lang.Object
  |
  +--org.apache.avalon.framework.logger.AbstractLoggable
        |
        +--org.apache.cocoon.xml.AbstractXMLProducer
              |
              +--org.apache.cocoon.xml.AbstractXMLPipe
                    |
                    +--org.apache.cocoon.transformation.AbstractTransformer
                          |
                          +--org.apache.cocoon.transformation.AbstractSAXTransformer

All Implemented Interfaces:

org.apache.avalon.framework.component.Component, org.apache.avalon.framework.component.Composable, org.apache.avalon.framework.configuration.Configurable, org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler, org.apache.avalon.framework.logger.Loggable, org.apache.avalon.excalibur.pool.Poolable, org.apache.avalon.excalibur.pool.Recyclable, SitemapModelComponent, Transformer, XMLConsumer, XMLPipe, XMLProducer

Direct Known Subclasses:

SQLTransformer

public abstract class AbstractSAXTransformer

extends AbstractTransformer

implements org.apache.avalon.framework.component.Composable, org.apache.avalon.framework.configuration.Configurable, org.apache.avalon.excalibur.pool.Recyclable

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 AbstractSunshineTransformer 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:

CVS $Id: AbstractSAXTransformer.java,v 1.2.2.1 2002/06/07 09:34:24 cziegeler Exp $

Author:

Carsten Ziegeler

Field Summary

protected Context	context The current Context object
protected java.lang.String	defaultNamespaceURI This is the default namespace used by the transformer.
protected org.xml.sax.helpers.AttributesImpl	emptyAttributes Empty attributes (for performance).
protected boolean	ignoreEmptyCharacters Controlls SAX event handling If set to true all characters events containing only whitespaces are ignored.
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.
protected int	ignoreHooksCount Controlls SAX event handling If this is greater than zero, the hooks are not called.
protected boolean	ignoreWhitespaces Controlls SAX event handling.
protected org.apache.avalon.framework.component.ComponentManager	manager The Avalon ComponentManager for getting Components
protected java.lang.String	namespaceURI The used namespace for the SAX filtering.
protected java.util.Map	objectModel The current objectModel of the environment
protected org.apache.avalon.framework.parameters.Parameters	parameters The parameters specified in the sitemap
protected java.util.Stack	recorderStack The stack of current used recorders
protected Request	request The current Request object
protected SourceResolver	resolver The SourceResolver for this request
protected Response	response The current Response object
protected java.lang.String	source The source attribute specified in the sitemap
protected java.util.Stack	stack A stack for collecting information.

Fields inherited from class org.apache.cocoon.xml.AbstractXMLProducer

contentHandler, lexicalHandler, xmlConsumer

Fields inherited from interface org.apache.cocoon.transformation.Transformer

ROLE

Constructor Summary

AbstractSAXTransformer()

Method Summary

protected void	addRecorder(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) SAX Event handling
void	compose(org.apache.avalon.framework.component.ComponentManager manager) Avalon Composable Interface
void	configure(org.apache.avalon.framework.configuration.Configuration configuration) Avalon Configurable Interface
void	endCDATA() SAX Event handling
void	endDocument() Process the SAX event.
void	endDTD() SAX Event handling
void	endElement(java.lang.String uri, java.lang.String name, java.lang.String raw) Process the SAX event.
void	endEntity(java.lang.String name) SAX Event handling
org.apache.excalibur.source.SourceParameters	endParametersRecording(org.apache.avalon.framework.parameters.Parameters source) End recording of parameters If source is null a new parameters object is created, otherwise the parameters are added to this object.
org.apache.excalibur.source.SourceParameters	endParametersRecording(org.apache.excalibur.source.SourceParameters source) End recording of parameters If source is null a new parameters object is created, otherwise the parameters are added to this object.
void	endPrefixMapping(java.lang.String prefix) SAX Event handling
org.w3c.dom.DocumentFragment	endRecording() Stop DocumentFragment recording.
java.lang.String	endSerializedXMLRecording() Return the serialized xml string.
java.lang.String	endTextRecording() Stop recording of text and return the recorded information.
void	endTransformingElement(java.lang.String uri, java.lang.String name, java.lang.String raw) Start processing elements of our namespace.
void	ignorableWhitespace(char[] p0, int p1, int p2) Process the SAX event.
void	processingInstruction(java.lang.String target, java.lang.String data) SAX Event handling
void	recycle() Recycle this component.
protected java.lang.Object	removeRecorder() Remove a recorder from the recording chain.
void	sendEndElementEvent(java.lang.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(org.w3c.dom.Node node) Send SAX events to the next pipeline component.
void	sendParametersEvents(org.apache.excalibur.source.SourceParameters pars) Send SAX events for the SourceParameters.
void	sendStartElementEvent(java.lang.String localname) Send SAX events to the next pipeline component.
void	sendStartElementEvent(java.lang.String localname, org.xml.sax.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(java.lang.String text) Send SAX events to the next pipeline component.
void	setDocumentLocator(org.xml.sax.Locator locator) SAX Event handling
void	setup(SourceResolver resolver, java.util.Map objectModel, java.lang.String src, org.apache.avalon.framework.parameters.Parameters par) Setup the next round.
void	setupTransforming() Setup the transformation of an xml document.
void	skippedEntity(java.lang.String name) SAX Event handling
void	startCDATA() SAX Event handling
void	startDocument() Process the SAX event.
void	startDTD(java.lang.String name, java.lang.String public_id, java.lang.String system_id) SAX Event handling
void	startElement(java.lang.String uri, java.lang.String name, java.lang.String raw, org.xml.sax.Attributes attr) Process the SAX event.
void	startEntity(java.lang.String name) SAX Event handling
void	startParametersRecording() Start recording of parameters.
void	startPrefixMapping(java.lang.String prefix, java.lang.String uri) SAX Event handling
void	startRecording() Start DocumentFragment recording.
void	startSerializedXMLRecording(java.util.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 text.
void	startTransformingElement(java.lang.String uri, java.lang.String name, java.lang.String raw, org.xml.sax.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.avalon.framework.logger.AbstractLoggable

getLogger, setLogger, setupLogger, setupLogger, setupLogger

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

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 java.lang.String namespaceURI

The used namespace for the SAX filtering. This is either the defaultNamespaceURI or the value set by the "namespaceURI" parameter for the pipeline.

defaultNamespaceURI

protected java.lang.String defaultNamespaceURI

This is the default namespace used by the transformer. It should be set by in the constructor.

stack

protected java.util.Stack stack

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

recorderStack

protected java.util.Stack recorderStack

The stack of current used recorders

request

protected Request request

The current Request object

response

protected Response response

The current Response object

context

protected Context context

The current Context object

objectModel

protected java.util.Map objectModel

The current objectModel of the environment

parameters

protected org.apache.avalon.framework.parameters.Parameters parameters

The parameters specified in the sitemap

source

protected java.lang.String source

The source attribute specified in the sitemap

manager

protected org.apache.avalon.framework.component.ComponentManager manager

The Avalon ComponentManager for getting Components

resolver

protected SourceResolver resolver

The SourceResolver for this request

emptyAttributes

protected org.xml.sax.helpers.AttributesImpl emptyAttributes

Empty attributes (for performance). This can be used do create own attributes, but make sure to clean them afterwords.

Constructor Detail

AbstractSAXTransformer

public AbstractSAXTransformer()

Method Detail

configure

public void configure(org.apache.avalon.framework.configuration.Configuration configuration)
               throws org.apache.avalon.framework.configuration.ConfigurationException

Avalon Configurable Interface

Specified by:

configure in interface org.apache.avalon.framework.configuration.Configurable

setup

public void setup(SourceResolver resolver,
                  java.util.Map objectModel,
                  java.lang.String src,
                  org.apache.avalon.framework.parameters.Parameters par)
           throws ProcessingException,
                  org.xml.sax.SAXException,
                  java.io.IOException

Setup the next round. The instance variables are initialised.

Parameters:

resolver - The current SourceResolver

objectModel - The objectModel of the environment.

src - The value of the src attribute in the sitemap.

par - The parameters from the sitemap.

recycle

public void recycle()

Recycle this component.

Specified by:

recycle in interface org.apache.avalon.excalibur.pool.Recyclable

Overrides:

recycle in class AbstractXMLProducer

compose

public void compose(org.apache.avalon.framework.component.ComponentManager manager)

Avalon Composable Interface

Specified by:

compose in interface org.apache.avalon.framework.component.Composable

Parameters:

manager - The Avalon Component Manager

startDocument

public void startDocument()
                   throws org.xml.sax.SAXException

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

Overrides:

startDocument in class AbstractXMLPipe

See Also:

ContentHandler.startDocument()

endDocument

public void endDocument()
                 throws org.xml.sax.SAXException

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

Overrides:

endDocument in class AbstractXMLPipe

See Also:

ContentHandler.endDocument()

startElement

public void startElement(java.lang.String uri,
                         java.lang.String name,
                         java.lang.String raw,
                         org.xml.sax.Attributes attr)
                  throws org.xml.sax.SAXException

Process the SAX event. The namespace of the event is checked. If it is the defined namespace for this transformer the startTransformingElement() hook is called.

Overrides:

startElement in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.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.

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

a - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.

endElement

public void endElement(java.lang.String uri,
                       java.lang.String name,
                       java.lang.String raw)
                throws org.xml.sax.SAXException

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

Overrides:

endElement in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.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.

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

characters

public void characters(char[] p0,
                       int p1,
                       int p2)
                throws org.xml.sax.SAXException

Process the SAX event.

Overrides:

characters in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

c - The characters from the XML document.

start - The start position in the array.

len - The number of characters to read from the array.

ignorableWhitespace

public void ignorableWhitespace(char[] p0,
                                int p1,
                                int p2)
                         throws org.xml.sax.SAXException

Process the SAX event.

Overrides:

ignorableWhitespace in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

c - The characters from the XML document.

start - The start position in the array.

len - The number of characters to read from the array.

addRecorder

protected void addRecorder(XMLConsumer recorder)

Add a new recorder to the recording chain. Do not invoke this method directly.

removeRecorder

protected java.lang.Object removeRecorder()

Remove a recorder from the recording chain. Do not invoke this method directly.

startRecording

public void startRecording()
                    throws org.xml.sax.SAXException

Start DocumentFragment recording. All invoming events are recorded and not forwarded. The resulting DocumentFragment can be obtained by the matching endRecording() call.

endRecording

public org.w3c.dom.DocumentFragment endRecording()
                                          throws org.xml.sax.SAXException

Stop DocumentFragment recording. All invoming events are recorded and not forwarded. This method returns the resulting DocumentFragment.

startTextRecording

public void startTextRecording()
                        throws org.xml.sax.SAXException

Start recording of text. All events are not forwarded and the characters events are merged to a string

endTextRecording

public java.lang.String endTextRecording()
                                  throws org.xml.sax.SAXException

Stop recording of text and return the recorded information.

Returns:

The String.

startSerializedXMLRecording

public void startSerializedXMLRecording(java.util.Properties format)
                                 throws org.xml.sax.SAXException

Start recording of serialized xml All events are converted to an xml string which can be retrieved by endSerializedXMLRecording.

Parameters:

format - The format for the serialized output. If null is specified, the default format is used.

endSerializedXMLRecording

public java.lang.String endSerializedXMLRecording()
                                           throws org.xml.sax.SAXException,
                                                  ProcessingException

Return the serialized xml string.

Returns:

A string containing the recorded xml information, formatted by the properties passed to the corresponding startSerializedXMLRecording().

startParametersRecording

public void startParametersRecording()
                              throws org.xml.sax.SAXException

Start recording of parameters. All events are not forwarded and the incoming xml is converted to parameters. Each toplevel node is a parameter and its text subnodes form the value. The Parameters can eiter be retrieved by endParametersRecording().

endParametersRecording

public org.apache.excalibur.source.SourceParameters endParametersRecording(org.apache.avalon.framework.parameters.Parameters source)
                                                                    throws org.xml.sax.SAXException

End recording of parameters If source is null a new parameters object is created, otherwise the parameters are added to this object.

Parameters:

source - An optional parameters object.

Returns:

The object containing all parameters.

endParametersRecording

public org.apache.excalibur.source.SourceParameters endParametersRecording(org.apache.excalibur.source.SourceParameters source)
                                                                    throws org.xml.sax.SAXException

End recording of parameters If source is null a new parameters object is created, otherwise the parameters are added to this object.

Parameters:

source - An optional parameters object.

Returns:

The object containing all parameters.

setupTransforming

public void setupTransforming()
                       throws java.io.IOException,
                              ProcessingException,
                              org.xml.sax.SAXException

Setup the transformation of an xml document. This method is called just before the transformation (sending of sax events) starts. It should be used to initialize setup parameter depending on the object modell.

startTransformingElement

public void startTransformingElement(java.lang.String uri,
                                     java.lang.String name,
                                     java.lang.String raw,
                                     org.xml.sax.Attributes attr)
                              throws ProcessingException,
                                     java.io.IOException,
                                     org.xml.sax.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.

endTransformingElement

public void endTransformingElement(java.lang.String uri,
                                   java.lang.String name,
                                   java.lang.String raw)
                            throws ProcessingException,
                                   java.io.IOException,
                                   org.xml.sax.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.

sendTextEvent

public void sendTextEvent(java.lang.String text)
                   throws org.xml.sax.SAXException

Send SAX events to the next pipeline component. The characters event for the given text is send to the next component in the current pipeline.

Parameters:

text - The string containing the information.

sendStartElementEvent

public void sendStartElementEvent(java.lang.String localname)
                           throws org.xml.sax.SAXException

Send SAX events to the next pipeline component. The startElement event for the given element is send to the next component in the current pipeline. The element has no namespace and no attributes

Parameters:

localname - The name of the event.

sendStartElementEvent

public void sendStartElementEvent(java.lang.String localname,
                                  org.xml.sax.Attributes attr)
                           throws org.xml.sax.SAXException

Send SAX events to the next pipeline component. The startElement event for the given element is send to the next component in the current pipeline. The element has no namespace.

Parameters:

localname - The name of the event.

attr - The Attributes of the element

sendEndElementEvent

public void sendEndElementEvent(java.lang.String localname)
                         throws org.xml.sax.SAXException

Send SAX events to the next pipeline component. The endElement event for the given element is send to the next component in the current pipeline. The element has no namespace.

Parameters:

localname - The name of the event.

sendEvents

public void sendEvents(org.w3c.dom.Node node)
                throws org.xml.sax.SAXException

Send SAX events to the next pipeline component. The node is parsed and the events are send to the next component in the pipeline.

Parameters:

node - The tree to be included.

sendParametersEvents

public void sendParametersEvents(org.apache.excalibur.source.SourceParameters pars)
                          throws org.xml.sax.SAXException

Send SAX events for the SourceParameters. For each parametername/value pair an element is created with the name of the parameter and the content of this element is the value.

startEntity

public void startEntity(java.lang.String name)
                 throws org.xml.sax.SAXException

SAX Event handling

Overrides:

startEntity in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

name - The name of the entity. If it is a parameter entity, the name will begin with '%'.

endEntity

public void endEntity(java.lang.String name)
               throws org.xml.sax.SAXException

SAX Event handling

Overrides:

endEntity in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

name - The name of the entity that is ending.

sendStartPrefixMapping

protected void sendStartPrefixMapping()
                               throws org.xml.sax.SAXException

Send all start prefix mapping events to the current content handler

sendEndPrefixMapping

protected void sendEndPrefixMapping()
                             throws org.xml.sax.SAXException

Send all end prefix mapping events to the current content handler

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator locator)

SAX Event handling

Overrides:

setDocumentLocator in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

locator - An object that can return the location of any SAX document event.

startPrefixMapping

public void startPrefixMapping(java.lang.String prefix,
                               java.lang.String uri)
                        throws org.xml.sax.SAXException

SAX Event handling

Overrides:

startPrefixMapping in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

prefix - The Namespace prefix being declared.

uri - The Namespace URI the prefix is mapped to.

endPrefixMapping

public void endPrefixMapping(java.lang.String prefix)
                      throws org.xml.sax.SAXException

SAX Event handling

Overrides:

endPrefixMapping in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

prefix - The prefix that was being mapping.

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException

SAX Event handling

Overrides:

processingInstruction in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

target - The processing instruction target.

data - The processing instruction data, or null if none was supplied.

skippedEntity

public void skippedEntity(java.lang.String name)
                   throws org.xml.sax.SAXException

SAX Event handling

Overrides:

skippedEntity in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

name - The name of the skipped entity. If it is a parameter entity, the name will begin with '%'.

startDTD

public void startDTD(java.lang.String name,
                     java.lang.String public_id,
                     java.lang.String system_id)
              throws org.xml.sax.SAXException

SAX Event handling

Overrides:

startDTD in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

name - The document type name.

publicId - The declared public identifier for the external DTD subset, or null if none was declared.

systemId - The declared system identifier for the external DTD subset, or null if none was declared.

endDTD

public void endDTD()
            throws org.xml.sax.SAXException

SAX Event handling

Overrides:

endDTD in class AbstractXMLPipe

startCDATA

public void startCDATA()
                throws org.xml.sax.SAXException

SAX Event handling

Overrides:

startCDATA in class AbstractXMLPipe

endCDATA

public void endCDATA()
              throws org.xml.sax.SAXException

SAX Event handling

Overrides:

endCDATA in class AbstractXMLPipe

comment

public void comment(char[] ary,
                    int start,
                    int length)
             throws org.xml.sax.SAXException

SAX Event handling

Overrides:

comment in class AbstractXMLPipe

Following copied from class: org.apache.cocoon.xml.AbstractXMLPipe

Parameters:

ch - An array holding the characters in the comment.

start - The starting position in the array.

len - The number of characters to use from the array.