net.sf.joost.stx
Class Processor

java.lang.Object
  extended by org.xml.sax.helpers.XMLFilterImpl
      extended by net.sf.joost.stx.Processor
All Implemented Interfaces:
Constants, ContentHandler, DTDHandler, EntityResolver, ErrorHandler, LexicalHandler, XMLFilter, XMLReader
Direct Known Subclasses:
DebugProcessor

public class Processor
extends XMLFilterImpl
implements Constants, LexicalHandler

Processes an XML document as SAX XMLFilter. Actions are contained within an array of templates, received from a transform node.

Version:
$Revision: 2.61 $ $Date: 2009/08/21 12:46:17 $
Author:
Oliver Becker

Nested Class Summary
 class Processor.Data
          Inner class for data which is processing/template specific.
 class Processor.DataStack
          Inner class that implements a stack for Processor.Data objects.
 
Field Summary
private  StringBuffer collectedCharacters
          Buffer for collecting character data into single text nodes
private  Context context
          The Context object
private  Processor.DataStack dataStack
          Stack for Processor.Data objects
private  Stack eventStack
          Stack for input events (of type SAXEvent).
private  TemplateFactory.Instance[] globalTemplates
          Array of global visible templates (templates with an attribute visibility="global").
private  Stack innerProcStack
          Stack needed for inner processing (buffers, documents).
private  Hashtable inScopeNamespaces
          The namespaces of the current scope
private  boolean insideCDATA
          Set to true between startCDATA() and endCDATA(), needed for CDATA processing
private  boolean insideDTD
          Set to true between startDTD(java.lang.String, java.lang.String, java.lang.String) and endDTD(), needed for ignoring comments
private  boolean isProcessorClass
           
private  SAXEvent lastElement
          Last event (this Processor uses one look-ahead)
private static org.apache.commons.logging.Log log
           
private  Stack namespaceContext
          The namespace context as a stack
private  boolean nsContextActive
          Flag that controls namespace contexts
 Properties outputProperties
           
static byte PASS_THROUGH_ALL
          Possible actions when no matching template was found.
static byte PASS_THROUGH_ATTRIBUTE
          Possible actions when no matching template was found.
static byte PASS_THROUGH_COMMENT
          Possible actions when no matching template was found.
static byte PASS_THROUGH_ELEMENT
          Possible actions when no matching template was found.
static byte PASS_THROUGH_NONE
          Possible actions when no matching template was found.
static byte PASS_THROUGH_PI
          Possible actions when no matching template was found.
static byte PASS_THROUGH_TEXT
          Possible actions when no matching template was found.
private  int processStatus
          contains the last return value after processing STX instructions
private static String PROP_PREFIX
          Standard prefix for SAX2 properties
private  int skipDepth
          Depth in the subtree to be skipped; increased by startElement and decreased by endElement.
private  TransformFactory.Instance transformNode
          The node representing the transformation sheet
 
Fields inherited from interface net.sf.joost.Constants
DEBUG, DEFAULT_ENCODING, FEAT_NS, FEAT_NSPREFIX, FEATURE_URI_PREFIX, FUNC_NS, JOOST_EXT_NS, PR_ATTRIBUTES, PR_BUFFER, PR_CHILDREN, PR_CONTINUE, PR_ERROR, PR_SELF, PR_SIBLINGS, STX_NS
 
Constructor Summary
Processor(InputSource src, ParseContext pContext)
          Constructs a new Processor instance by parsing an STX transformation sheet.
Processor(Parser stxParser)
          Constructs a new Processor instance from an existing Parser (Joost representation of an STX transformation sheet)
Processor(Processor proc)
          Constructs a copy of the given Processor.
Processor(XMLReader reader, InputSource src, ParseContext pContext)
          Constructs a new Processor instance by parsing an STX transformation sheet.
 
Method Summary
 void characters(char[] ch, int start, int length)
           
 void clearParameters()
          Clear all preset parameters
private  void clearProcessSiblings()
          Clear all consecutive pending stx:process-siblings instructions on the top of dataStack.
private  void clearProcessSiblings(Processor.Data stopData, boolean clearLast)
          Clear consecutive pending stx:process-siblings instructions on the top of dataStack until the passed object is encountered.
 void comment(char[] ch, int start, int length)
           
 Processor copy()
          Constructs a copy of this Processor.
static XMLReader createXMLReader()
          Create an XMLReader object (a SAX Parser)
private  AbstractInstruction doProcessLoop(AbstractInstruction inst, SAXEvent event, boolean skipProcessBase)
          Performs the processing of the linked instruction chain until an end condition was met.
 void endCDATA()
           
 void endDocument()
           
 void endDTD()
           
 void endElement(String uri, String lName, String qName)
           
 void endEntity(String name)
           
private  void endExternDocument()
          Emits an endDocument event to an external handler (in Context.targetHandler), preceded by all necessary namespace undeclarations (endPrefixMapping events).
 void endInnerProcessing()
          Ends the inner processing by restoring the collected text data.
 void endPrefixMapping(String prefix)
           
private  TemplateFactory.Instance findMatchingTemplate()
           
private  boolean foundUnprocessedTemplate(TemplateFactory.Instance temp)
          Check for the next best matching template after stx:process-self
 Context getContext()
          Returns a ref to the current context of the processing.
protected  Processor.DataStack getDataStack()
          Returns a reference to the data stack.
 Emitter getEmitter()
          Returns a ref to the registered emitter
 Stack getEventStack()
          Returns a reference to the event stack.
protected  SAXEvent getLastElement()
          Returns a ref to the last element (look ahead)
 String getOutputEncoding()
           
 Object getParameter(String name)
          Returns a global parameter of the STX transformation sheet
 void ignorableWhitespace(char[] ch, int start, int length)
           
private  void init(TransformFactory.Instance pTransformNode)
          Initialize a Processor object
protected  Emitter initializeEmitter(Context ctx)
          The initialization of the emitter could be overriden for debug purpose.
private  void initNamespaces()
          Create a fresh namespace hashtable
 void initOutputProperties()
          Initialize the output properties to the values specified in the transformation sheet or to their default values, resp.
private  void processAttributes(Attributes attrs)
          Simulate events for each of the attributes of the current element.
private  void processCharacters()
          Process a text node (from several consecutive characters events)
private  void processEvent()
          Processes the upper most event on the event stack.
 void processingInstruction(String target, String data)
           
protected  int processInstruction(AbstractInstruction inst, SAXEvent event)
          Process an instruction.
private  void processLastElement(boolean hasChildren)
          Process last element start (stored as lastElement in startElement)
private  void processSiblings()
          Check and process pending templates whose processing was suspended by an stx:process-siblings instruction
 void setContentHandler(ContentHandler handler)
          Registers a content handler.
 void setDeclHandler(DeclHandler handler)
          Registers a declaration handler.
 void setDocumentLocator(Locator locator)
          Store the locator in the context object
 void setErrorListener(ErrorListener listener)
          Registers a ErrorListener object for reporting errors while processing (transforming) the XML input
 void setLexicalHandler(LexicalHandler handler)
          Registers a lexical handler.
 void setMessageEmitter(StxEmitter emitter)
          Registers a message emitter for stx:message
 void setOutputURIResolver(OutputURIResolver resolver)
          Registers an OutputURIResolver for stx:result-document
 void setParameter(String name, Object value)
          Sets a global parameter of the STX transformation sheet
 void setParent(XMLReader parent)
          Assigns a parent to this filter instance.
 void setProperty(String prop, Object value)
          Set the property of a value on the underlying XMLReader.
 void setTransformerHandlerResolver(TransformerHandlerResolver resolver)
          Registers a custom TransformerHandlerResolver object.
 void setURIResolver(URIResolver resolver)
          Registers a URIResolver for stx:process-document
 void startCDATA()
           
 void startDocument()
           
 void startDTD(String name, String publicId, String systemId)
           
 void startElement(String uri, String lName, String qName, Attributes attrs)
           
 void startEntity(String name)
           
private  void startExternDocument()
          Emits a startDocument event to an external handler (in Context.targetHandler), followed by all necessary namespace declarations (startPrefixMapping events).
 void startInnerProcessing()
          Starts the inner processing of a new buffer or another document by saving the text data already read and jumping to the targetted group (if specified).
 void startPrefixMapping(String prefix, String uri)
           
 
Methods inherited from class org.xml.sax.helpers.XMLFilterImpl
error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, getProperty, notationDecl, parse, parse, resolveEntity, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, skippedEntity, unparsedEntityDecl, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PASS_THROUGH_NONE

public static final byte PASS_THROUGH_NONE
Possible actions when no matching template was found. Set by stx:options' no-match-events

See Also:
Constant Field Values

PASS_THROUGH_ELEMENT

public static final byte PASS_THROUGH_ELEMENT
Possible actions when no matching template was found. Set by stx:options' no-match-events

See Also:
Constant Field Values

PASS_THROUGH_TEXT

public static final byte PASS_THROUGH_TEXT
Possible actions when no matching template was found. Set by stx:options' no-match-events

See Also:
Constant Field Values

PASS_THROUGH_COMMENT

public static final byte PASS_THROUGH_COMMENT
Possible actions when no matching template was found. Set by stx:options' no-match-events

See Also:
Constant Field Values

PASS_THROUGH_PI

public static final byte PASS_THROUGH_PI
Possible actions when no matching template was found. Set by stx:options' no-match-events

See Also:
Constant Field Values

PASS_THROUGH_ATTRIBUTE

public static final byte PASS_THROUGH_ATTRIBUTE
Possible actions when no matching template was found. Set by stx:options' no-match-events

See Also:
Constant Field Values

PASS_THROUGH_ALL

public static final byte PASS_THROUGH_ALL
Possible actions when no matching template was found. Set by stx:options' no-match-events

See Also:
Constant Field Values

transformNode

private TransformFactory.Instance transformNode
The node representing the transformation sheet


globalTemplates

private TemplateFactory.Instance[] globalTemplates
Array of global visible templates (templates with an attribute visibility="global").


context

private Context context
The Context object


skipDepth

private int skipDepth
Depth in the subtree to be skipped; increased by startElement and decreased by endElement.


insideCDATA

private boolean insideCDATA
Set to true between startCDATA() and endCDATA(), needed for CDATA processing


insideDTD

private boolean insideDTD
Set to true between startDTD(java.lang.String, java.lang.String, java.lang.String) and endDTD(), needed for ignoring comments


collectedCharacters

private StringBuffer collectedCharacters
Buffer for collecting character data into single text nodes


lastElement

private SAXEvent lastElement
Last event (this Processor uses one look-ahead)


inScopeNamespaces

private Hashtable inScopeNamespaces
The namespaces of the current scope


namespaceContext

private Stack namespaceContext
The namespace context as a stack


nsContextActive

private boolean nsContextActive
Flag that controls namespace contexts


eventStack

private Stack eventStack
Stack for input events (of type SAXEvent). Every startElement event pushes itself on this stack, every endElement event pops its event from the stack. Character events (text()), comments, PIs will be put on the stack before processing and removed immediately afterwards. This stack is needed for matching and for position counting within the parent of each event.


innerProcStack

private Stack innerProcStack
Stack needed for inner processing (buffers, documents). This stack stores the event stack for stx:process-document and character data that has been already read as look-ahead (collectedCharacters).


outputProperties

public Properties outputProperties

isProcessorClass

private final boolean isProcessorClass

dataStack

private Processor.DataStack dataStack
Stack for Processor.Data objects


log

private static org.apache.commons.logging.Log log

PROP_PREFIX

private static String PROP_PREFIX
Standard prefix for SAX2 properties


processStatus

private int processStatus
contains the last return value after processing STX instructions

Constructor Detail

Processor

public Processor(InputSource src,
                 ParseContext pContext)
          throws IOException,
                 SAXException
Constructs a new Processor instance by parsing an STX transformation sheet. This constructor attempts to create its own XMLReader object.

Parameters:
src - the source for the STX transformation sheet
pContext - the parse context
Throws:
IOException - if src couldn't be retrieved
SAXException - if a SAX parser couldn't be created

Processor

public Processor(XMLReader reader,
                 InputSource src,
                 ParseContext pContext)
          throws IOException,
                 SAXException
Constructs a new Processor instance by parsing an STX transformation sheet.

Parameters:
reader - the parser that is used for reading the transformation sheet
src - the source for the STX transformation sheet
pContext - a parse context
Throws:
IOException - if src couldn't be retrieved
SAXException - if a SAX parser couldn't be created

Processor

public Processor(Parser stxParser)
          throws SAXException
Constructs a new Processor instance from an existing Parser (Joost representation of an STX transformation sheet)

Parameters:
stxParser - the Joost representation of a transformation sheet
Throws:
SAXException - if createXMLReader() fails

Processor

public Processor(Processor proc)
          throws SAXException
Constructs a copy of the given Processor.

Parameters:
proc - the original Processor object
Throws:
SAXException - if the construction of a new XML parser fails
Method Detail

copy

public Processor copy()
               throws SAXException
Constructs a copy of this Processor.

Throws:
SAXException - if the construction of a new XML parser fails

createXMLReader

public static XMLReader createXMLReader()
                                 throws SAXException
Create an XMLReader object (a SAX Parser)

Throws:
SAXException - if a SAX Parser couldn't be created

init

private void init(TransformFactory.Instance pTransformNode)
Initialize a Processor object


initNamespaces

private void initNamespaces()
Create a fresh namespace hashtable


initializeEmitter

protected Emitter initializeEmitter(Context ctx)
The initialization of the emitter could be overriden for debug purpose.

Parameters:
ctx - The current context
Returns:
an emitter-instance

initOutputProperties

public void initOutputProperties()
Initialize the output properties to the values specified in the transformation sheet or to their default values, resp.


setParent

public void setParent(XMLReader parent)
Assigns a parent to this filter instance. Attempts to register itself as a lexical handler on this parent.

Specified by:
setParent in interface XMLFilter
Overrides:
setParent in class XMLFilterImpl

setContentHandler

public void setContentHandler(ContentHandler handler)
Registers a content handler.

Specified by:
setContentHandler in interface XMLReader
Overrides:
setContentHandler in class XMLFilterImpl

setLexicalHandler

public void setLexicalHandler(LexicalHandler handler)
Registers a lexical handler.


setDeclHandler

public void setDeclHandler(DeclHandler handler)
Registers a declaration handler. Does nothing at the moment.


setProperty

public void setProperty(String prop,
                        Object value)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
Set the property of a value on the underlying XMLReader.

Specified by:
setProperty in interface XMLReader
Overrides:
setProperty in class XMLFilterImpl
Throws:
SAXNotRecognizedException
SAXNotSupportedException

setErrorListener

public void setErrorListener(ErrorListener listener)
Registers a ErrorListener object for reporting errors while processing (transforming) the XML input


getOutputEncoding

public String getOutputEncoding()
Returns:
the output encoding specified in the STX transformation sheet

setParameter

public void setParameter(String name,
                         Object value)
Sets a global parameter of the STX transformation sheet

Parameters:
name - the (expanded) parameter name
value - the parameter value

getParameter

public Object getParameter(String name)
Returns a global parameter of the STX transformation sheet

Parameters:
name - the (expanded) parameter name
Returns:
the parameter value or null if this parameter isn't present

clearParameters

public void clearParameters()
Clear all preset parameters


setTransformerHandlerResolver

public void setTransformerHandlerResolver(TransformerHandlerResolver resolver)
Registers a custom TransformerHandlerResolver object.

Parameters:
resolver - the resolver to be registered

setURIResolver

public void setURIResolver(URIResolver resolver)
Registers a URIResolver for stx:process-document

Parameters:
resolver - the resolver to be registered

setOutputURIResolver

public void setOutputURIResolver(OutputURIResolver resolver)
Registers an OutputURIResolver for stx:result-document

Parameters:
resolver - the resolver to be registered

setMessageEmitter

public void setMessageEmitter(StxEmitter emitter)
Registers a message emitter for stx:message

Parameters:
emitter - the emitter object to be registered

startInnerProcessing

public void startInnerProcessing()
Starts the inner processing of a new buffer or another document by saving the text data already read and jumping to the targetted group (if specified).


endInnerProcessing

public void endInnerProcessing()
                        throws SAXException
Ends the inner processing by restoring the collected text data.

Throws:
SAXException

foundUnprocessedTemplate

private boolean foundUnprocessedTemplate(TemplateFactory.Instance temp)
Check for the next best matching template after stx:process-self

Parameters:
temp - a template matching the current node
Returns:
true if this template hasn't been processed before

findMatchingTemplate

private TemplateFactory.Instance findMatchingTemplate()
                                               throws SAXException
Returns:
the matching template for the current event stack.
Throws:
SAXException

doProcessLoop

private AbstractInstruction doProcessLoop(AbstractInstruction inst,
                                          SAXEvent event,
                                          boolean skipProcessBase)
                                   throws SAXException
Performs the processing of the linked instruction chain until an end condition was met. This method stores the last return value in the class member variable processStatus.

Parameters:
inst - the first instruction in the chain
event - the current event
skipProcessBase - set if ProcessBase instructions shouldn't be reported
Returns:
the last processed instruction
Throws:
SAXException

processInstruction

protected int processInstruction(AbstractInstruction inst,
                                 SAXEvent event)
                          throws SAXException
Process an instruction. This method should be overridden for debug purposes.

Parameters:
inst - The instruction which should be processed
event - The current event
Returns:
see AbstractInstruction.process(net.sf.joost.stx.Context)
Throws:
SAXException - in case of parse-errors

processEvent

private void processEvent()
                   throws SAXException
Processes the upper most event on the event stack.

Throws:
SAXException

processLastElement

private void processLastElement(boolean hasChildren)
                         throws SAXException
Process last element start (stored as lastElement in startElement)

Throws:
SAXException

processCharacters

private void processCharacters()
                        throws SAXException
Process a text node (from several consecutive characters events)

Throws:
SAXException

processAttributes

private void processAttributes(Attributes attrs)
                        throws SAXException
Simulate events for each of the attributes of the current element. This method will be called due to an stx:process-attributes instruction.

Parameters:
attrs - the attributes to be processed
Throws:
SAXException

processSiblings

private void processSiblings()
                      throws SAXException
Check and process pending templates whose processing was suspended by an stx:process-siblings instruction

Throws:
SAXException

clearProcessSiblings

private void clearProcessSiblings()
                           throws SAXException
Clear all consecutive pending stx:process-siblings instructions on the top of dataStack. Does nothing if there's no stx:process-siblings pending.

Throws:
SAXException

clearProcessSiblings

private void clearProcessSiblings(Processor.Data stopData,
                                  boolean clearLast)
                           throws SAXException
Clear consecutive pending stx:process-siblings instructions on the top of dataStack until the passed object is encountered.

Parameters:
stopData - data for the last stx:process-siblings instruction
clearLast - true if the template in stopData itself must be cleared
Throws:
SAXException

startExternDocument

private void startExternDocument()
                          throws SAXException
Emits a startDocument event to an external handler (in Context.targetHandler), followed by all necessary namespace declarations (startPrefixMapping events).

Throws:
SAXException

endExternDocument

private void endExternDocument()
                        throws SAXException
Emits an endDocument event to an external handler (in Context.targetHandler), preceded by all necessary namespace undeclarations (endPrefixMapping events).

Throws:
SAXException

startDocument

public void startDocument()
                   throws SAXException
Specified by:
startDocument in interface ContentHandler
Overrides:
startDocument in class XMLFilterImpl
Throws:
SAXException

endDocument

public void endDocument()
                 throws SAXException
Specified by:
endDocument in interface ContentHandler
Overrides:
endDocument in class XMLFilterImpl
Throws:
SAXException

startElement

public void startElement(String uri,
                         String lName,
                         String qName,
                         Attributes attrs)
                  throws SAXException
Specified by:
startElement in interface ContentHandler
Overrides:
startElement in class XMLFilterImpl
Throws:
SAXException

endElement

public void endElement(String uri,
                       String lName,
                       String qName)
                throws SAXException
Specified by:
endElement in interface ContentHandler
Overrides:
endElement in class XMLFilterImpl
Throws:
SAXException

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException
Specified by:
characters in interface ContentHandler
Overrides:
characters in class XMLFilterImpl
Throws:
SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException
Specified by:
ignorableWhitespace in interface ContentHandler
Overrides:
ignorableWhitespace in class XMLFilterImpl
Throws:
SAXException

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException
Specified by:
processingInstruction in interface ContentHandler
Overrides:
processingInstruction in class XMLFilterImpl
Throws:
SAXException

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException
Specified by:
startPrefixMapping in interface ContentHandler
Overrides:
startPrefixMapping in class XMLFilterImpl
Throws:
SAXException

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException
Specified by:
endPrefixMapping in interface ContentHandler
Overrides:
endPrefixMapping in class XMLFilterImpl
Throws:
SAXException

setDocumentLocator

public void setDocumentLocator(Locator locator)
Store the locator in the context object

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

startDTD

public void startDTD(String name,
                     String publicId,
                     String systemId)
Specified by:
startDTD in interface LexicalHandler

endDTD

public void endDTD()
Specified by:
endDTD in interface LexicalHandler

startEntity

public void startEntity(String name)
                 throws SAXException
Specified by:
startEntity in interface LexicalHandler
Throws:
SAXException

endEntity

public void endEntity(String name)
               throws SAXException
Specified by:
endEntity in interface LexicalHandler
Throws:
SAXException

startCDATA

public void startCDATA()
                throws SAXException
Specified by:
startCDATA in interface LexicalHandler
Throws:
SAXException

endCDATA

public void endCDATA()
              throws SAXException
Specified by:
endCDATA in interface LexicalHandler
Throws:
SAXException

comment

public void comment(char[] ch,
                    int start,
                    int length)
             throws SAXException
Specified by:
comment in interface LexicalHandler
Throws:
SAXException

getEventStack

public Stack getEventStack()
Returns a reference to the event stack.

Returns:
the event stack

getDataStack

protected Processor.DataStack getDataStack()
Returns a reference to the data stack.

Returns:
the data stack

getContext

public Context getContext()
Returns a ref to the current context of the processing.

Returns:
the current context

getEmitter

public Emitter getEmitter()
Returns a ref to the registered emitter

Returns:
the emitter

getLastElement

protected SAXEvent getLastElement()
Returns a ref to the last element (look ahead)

Returns:
the last element