org.apache.commons.jelly.parser
Class XMLParser

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      org.apache.commons.jelly.parser.XMLParser

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler

public class XMLParser
extends org.xml.sax.helpers.DefaultHandler

XMLParser parses the XML Jelly format. The SAXParser and XMLReader portions of this code come from Digester.

Version:

$Revision: 219726 $

Author:

James Strachan

Field Summary

protected ClassLoader	classLoader The class loader to use for instantiating application objects.
protected ErrorHandler	errorHandler The application-supplied error handler that is notified when parsing warnings, errors, or fatal errors occur.
protected static SAXParserFactory	factory The SAXParserFactory that is created the first time we need it.
protected Locator	locator The Locator associated with our parser.
protected Map	namespaces Registered namespaces we are currently processing.
protected SAXParser	parser The SAXParser we will use to parse the input stream.
protected XMLReader	reader The XMLReader used to parse digester rules.
protected boolean	useContextClassLoader Do we want to use the Context ClassLoader when loading classes for instantiating new objects? Default is false.
protected boolean	validating Do we want to use a validating parser?

Constructor Summary

XMLParser()
Construct a new XMLParser with default properties.

XMLParser(SAXParser parser)
Construct a new XMLParser, allowing a SAXParser to be passed in.

XMLParser(XMLReader reader)
Construct a new XMLParser, allowing an XMLReader to be passed in.

Method Summary

protected void	addExpressionScript(ScriptBlock script, Expression expression) Adds the given Expression object to the current Script.
protected void	addTextScript(String text, boolean start) Adds the text to the current script block parsing any embedded expressions into ExpressionScript objects.
void	characters(char[] buffer, int start, int length) Process notification of character data received from the body of an XML element.
protected void	configure() This method is called only once before parsing occurs which allows tag libraries to be registered and so forth
protected void	configureStaticTagAttributes(TagScript script, Attributes list)
protected void	configureTagScript(TagScript aTagScript) Configure a newly created TagScript instance before any Expressions are created
protected Expression	createConstantExpression(String tagName, String attributeName, String attributeValue)
protected ExpressionFactory	createExpressionFactory()
protected SAXException	createSAXException(Exception e) Create a SAX exception which also understands about the location in the digester file where the exception occurs
protected SAXException	createSAXException(String message) Create a SAX exception which also understands about the location in the digester file where the exception occurs
protected SAXException	createSAXException(String message, Exception e) Create a SAX exception which also understands about the location in the file where the exception occurs
protected TagScript	createStaticTag(String namespaceURI, String localName, String qName, Attributes list) Factory method to create a static Tag that represents some static content.
protected TagScript	createTag(String namespaceURI, String localName, Attributes list) Factory method to create new Tag script for the given namespaceURI and name or return null if this is not a custom Tag.
void	endDocument() Process notification of the end of the document being reached.
void	endElement(String namespaceURI, String localName, String qName) Process notification of the end of an XML element being reached.
void	endPrefixMapping(String prefix) Process notification that a namespace prefix is going out of scope.
void	error(SAXParseException exception) Forward notification of a parsing error to the application supplied error handler, if any, otherwise throw a SAXException with the error.
void	fatalError(SAXParseException exception) Forward notification of a fatal parsing error to the application supplied error handler, if any, otherwise throw a SAXException with the error.
String	findNamespaceURI(String prefix) Return the currently mapped namespace URI for the specified prefix, if any; otherwise return null.
ClassLoader	getClassLoader() Return the class loader to be used for instantiating application objects when required.
JellyContext	getContext()
protected String	getCurrentURI()
ErrorHandler	getErrorHandler() Return the error handler for this XMLParser.
ExpressionFactory	getExpressionFactory()
protected Properties	getJellyProperties() A helper method which loads the static Jelly properties once on startup
org.apache.commons.logging.Log	getLogger() Return the current Logger associated with this instance of the XMLParser
SAXParser	getParser() Return the SAXParser we will use to parse the input stream.
XMLReader	getReader() Deprecated. Use getXMLReader() instead, which can throw a SAXException if the reader cannot be instantiated
ScriptBlock	getScript() Returns the script that has just been created if this class is used as a SAX ContentHandler and passed into some XML processor or parser.
boolean	getUseContextClassLoader() Return the boolean as to whether the context classloader should be used.
boolean	getValidating() Return the validating parser flag.
XMLReader	getXMLReader() Return the XMLReader to be used for parsing the input document.
void	ignorableWhitespace(char[] buffer, int start, int len) Process notification of ignorable whitespace received from the body of an XML element.
void	notationDecl(String name, String publicId, String systemId) Receive notification of a notation declaration event.
Script	parse(File file) Parse the content of the specified file using this XMLParser.
Script	parse(InputSource input) Parse the content of the specified input source using this XMLParser.
Script	parse(InputStream input) Parse the content of the specified input stream using this XMLParser.
Script	parse(Reader reader) Parse the content of the specified reader using this XMLParser.
Script	parse(String uri) Parse the content of the specified URI using this XMLParser.
Script	parse(URL url) Parse the content of the specified file using this XMLParser.
void	processingInstruction(String target, String data) Process notification of a processing instruction that was encountered.
void	setClassLoader(ClassLoader classLoader) Set the class loader to be used for instantiating application objects when required.
void	setContext(JellyContext context)
void	setDefaultNamespaceURI(String namespace) Set the jelly namespace to use for unprefixed elements.
void	setDocumentLocator(Locator locator) Set the document locator associated with our parser.
void	setErrorHandler(ErrorHandler errorHandler) Set the error handler for this XMLParser.
void	setEscapeByDefault(boolean escapeByDefault)
void	setExpressionFactory(ExpressionFactory expressionFactory) Sets the expression factory used to evaluate tag attributes
void	setLogger(org.apache.commons.logging.Log log) Set the current logger for this XMLParser.
void	setUseContextClassLoader(boolean use) Determine whether to use the Context ClassLoader (the one found by calling Thread.currentThread().getContextClassLoader()) to resolve/load classes.
void	setValidating(boolean validating) Set the validating parser flag.
void	skippedEntity(String name) Process notification of a skipped entity.
void	startDocument() Process notification of the beginning of the document being reached.
void	startElement(String namespaceURI, String localName, String qName, Attributes list) Process notification of the start of an XML element being reached.
void	startPrefixMapping(String prefix, String namespaceURI) Process notification that a namespace prefix is coming in to scope.
void	unparsedEntityDecl(String name, String publicId, String systemId, String notation) Receive notification of an unparsed entity declaration event.
void	warning(SAXParseException exception) Forward notification of a parse warning to the application supplied error handler (if any).

Methods inherited from class org.xml.sax.helpers.DefaultHandler

resolveEntity

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

classLoader

protected ClassLoader classLoader

The class loader to use for instantiating application objects. If not specified, the context class loader, or the class loader used to load XMLParser itself, is used, based on the value of the useContextClassLoader variable.

useContextClassLoader

protected boolean useContextClassLoader

Do we want to use the Context ClassLoader when loading classes for instantiating new objects? Default is false.

errorHandler

protected ErrorHandler errorHandler

The application-supplied error handler that is notified when parsing warnings, errors, or fatal errors occur.

factory

protected static SAXParserFactory factory

The SAXParserFactory that is created the first time we need it.

parser

protected SAXParser parser

The SAXParser we will use to parse the input stream.

reader

protected XMLReader reader

The XMLReader used to parse digester rules.

locator

protected Locator locator

The Locator associated with our parser.

namespaces

protected Map namespaces

Registered namespaces we are currently processing. The key is the namespace prefix that was declared in the document. The value is an ArrayStack of the namespace URIs this prefix has been mapped to -- the top Stack element is the most current one. (This architecture is required because documents can declare nested uses of the same prefix for different Namespace URIs).

validating

protected boolean validating

Do we want to use a validating parser?

Constructor Detail

XMLParser

public XMLParser()

Construct a new XMLParser with default properties.

XMLParser

public XMLParser(SAXParser parser)

Construct a new XMLParser, allowing a SAXParser to be passed in. This allows XMLParser to be used in environments which are unfriendly to JAXP1.1 (such as WebLogic 6.0). Thanks for the request to change go to James House (james@interobjective.com). This may help in places where you are able to load JAXP 1.1 classes yourself.

XMLParser

public XMLParser(XMLReader reader)

Construct a new XMLParser, allowing an XMLReader to be passed in. This allows XMLParser to be used in environments which are unfriendly to JAXP1.1 (such as WebLogic 6.0). Note that if you use this option you have to configure namespace and validation support yourself, as these properties only affect the SAXParser and emtpy constructor.

Method Detail

setEscapeByDefault

public void setEscapeByDefault(boolean escapeByDefault)

parse

public Script parse(File file)
             throws IOException,
                    SAXException

Parse the content of the specified file using this XMLParser. Returns the root element from the object stack (if any).

Parameters:

file - File containing the XML data to be parsed

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

parse

public Script parse(URL url)
             throws IOException,
                    SAXException

Parse the content of the specified file using this XMLParser. Returns the root element from the object stack (if any).

Parameters:

url - URL containing the XML data to be parsed

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

parse

public Script parse(InputSource input)
             throws IOException,
                    SAXException

Parse the content of the specified input source using this XMLParser. Returns the root element from the object stack (if any).

Parameters:

input - Input source containing the XML data to be parsed

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

parse

public Script parse(InputStream input)
             throws IOException,
                    SAXException

Parse the content of the specified input stream using this XMLParser. Returns the root element from the object stack (if any). (Note: if reading a File or URL, use one of the URL-based parse methods instead. This method will not be able to resolve any relative paths inside a DTD.)

Parameters:

input - Input stream containing the XML data to be parsed

Returns:

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

parse

public Script parse(Reader reader)
             throws IOException,
                    SAXException

Parse the content of the specified reader using this XMLParser. Returns the root element from the object stack (if any). (Note: if reading a File or URL, use one of the URL-based parse methods instead. This method will not be able to resolve any relative paths inside a DTD.)

Parameters:

reader - Reader containing the XML data to be parsed

Returns:

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

parse

public Script parse(String uri)
             throws IOException,
                    SAXException

Parse the content of the specified URI using this XMLParser. Returns the root element from the object stack (if any).

Parameters:

uri - URI containing the XML data to be parsed

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

findNamespaceURI

public String findNamespaceURI(String prefix)

Return the currently mapped namespace URI for the specified prefix, if any; otherwise return null. These mappings come and go dynamically as the document is parsed.

Parameters:

prefix - Prefix to look up

getContext

public JellyContext getContext()

setContext

public void setContext(JellyContext context)

setDefaultNamespaceURI

public void setDefaultNamespaceURI(String namespace)

Set the jelly namespace to use for unprefixed elements. Will be overridden by an explicit namespace in the XML document.

Parameters:

namespace - jelly namespace to use (e.g. 'jelly:core')

getClassLoader

public ClassLoader getClassLoader()

Return the class loader to be used for instantiating application objects when required. This is determined based upon the following rules:

• The class loader set by setClassLoader(), if any
• The thread context class loader, if it exists and the useContextClassLoader property is set to true
• The class loader used to load the XMLParser class itself.

setClassLoader

public void setClassLoader(ClassLoader classLoader)

Set the class loader to be used for instantiating application objects when required.

Parameters:

classLoader - The new class loader to use, or null to revert to the standard rules

getUseContextClassLoader

public boolean getUseContextClassLoader()

Return the boolean as to whether the context classloader should be used.

setUseContextClassLoader

public void setUseContextClassLoader(boolean use)

Determine whether to use the Context ClassLoader (the one found by calling Thread.currentThread().getContextClassLoader()) to resolve/load classes. If not using Context ClassLoader, then the class-loading defaults to using the calling-class' ClassLoader.

Parameters:

use - determines whether to use JellyContext ClassLoader.

getErrorHandler

public ErrorHandler getErrorHandler()

Return the error handler for this XMLParser.

setErrorHandler

public void setErrorHandler(ErrorHandler errorHandler)

Set the error handler for this XMLParser.

Parameters:

errorHandler - The new error handler

getLogger

public org.apache.commons.logging.Log getLogger()

Return the current Logger associated with this instance of the XMLParser

setLogger

public void setLogger(org.apache.commons.logging.Log log)

Set the current logger for this XMLParser.

getExpressionFactory

public ExpressionFactory getExpressionFactory()

Returns:

the expression factory used to evaluate tag attributes

setExpressionFactory

public void setExpressionFactory(ExpressionFactory expressionFactory)

Sets the expression factory used to evaluate tag attributes

getParser

public SAXParser getParser()

Return the SAXParser we will use to parse the input stream. If there is a problem creating the parser, return null.

getReader

public XMLReader getReader()

Deprecated. Use getXMLReader() instead, which can throw a SAXException if the reader cannot be instantiated

By setting the reader in the constructor, you can bypass JAXP and be able to use digester in Weblogic 6.0.

getXMLReader

public XMLReader getXMLReader()
                       throws SAXException

Return the XMLReader to be used for parsing the input document.

Throws:

SAXException - if no XMLReader can be instantiated

getValidating

public boolean getValidating()

Return the validating parser flag.

setValidating

public void setValidating(boolean validating)

Set the validating parser flag. This must be called before parse() is called the first time.

Parameters:

validating - The new validating parser flag.

getScript

public ScriptBlock getScript()

Returns the script that has just been created if this class is used as a SAX ContentHandler and passed into some XML processor or parser.

Returns:

the ScriptBlock created if SAX events are piped into this class, which must include a startDocument() and endDocument()

startDocument

public void startDocument()
                   throws SAXException

Process notification of the beginning of the document being reached.

Specified by:

startDocument in interface ContentHandler

Overrides:

startDocument in class org.xml.sax.helpers.DefaultHandler

Throws:

SAXException - if a parsing error is to be reported

endDocument

public void endDocument()
                 throws SAXException

Process notification of the end of the document being reached.

Specified by:

endDocument in interface ContentHandler

Overrides:

endDocument in class org.xml.sax.helpers.DefaultHandler

Throws:

SAXException - if a parsing error is to be reported

startElement

public void startElement(String namespaceURI,
                         String localName,
                         String qName,
                         Attributes list)
                  throws SAXException

Process notification of the start of an XML element being reached.

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class org.xml.sax.helpers.DefaultHandler

Parameters:

namespaceURI - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.

localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.

qName - The qualified name (with prefix), or the empty string if qualified names are not available.\

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

Throws:

SAXException - if a parsing error is to be reported

characters

public void characters(char[] buffer,
                       int start,
                       int length)
                throws SAXException

Process notification of character data received from the body of an XML element.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class org.xml.sax.helpers.DefaultHandler

Parameters:

buffer - The characters from the XML document

start - Starting offset into the buffer

length - Number of characters from the buffer

Throws:

SAXException - if a parsing error is to be reported

endElement

public void endElement(String namespaceURI,
                       String localName,
                       String qName)
                throws SAXException

Process notification of the end of an XML element being reached.

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class org.xml.sax.helpers.DefaultHandler

Parameters:

namespaceURI - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.

localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.

qName - The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.

Throws:

SAXException - if a parsing error is to be reported

startPrefixMapping

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

Process notification that a namespace prefix is coming in to scope.

Specified by:

startPrefixMapping in interface ContentHandler

Overrides:

startPrefixMapping in class org.xml.sax.helpers.DefaultHandler

Parameters:

prefix - Prefix that is being declared

namespaceURI - Corresponding namespace URI being mapped to

Throws:

SAXException - if a parsing error is to be reported

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Process notification that a namespace prefix is going out of scope.

Specified by:

endPrefixMapping in interface ContentHandler

Overrides:

endPrefixMapping in class org.xml.sax.helpers.DefaultHandler

Parameters:

prefix - Prefix that is going out of scope

Throws:

SAXException - if a parsing error is to be reported

ignorableWhitespace

public void ignorableWhitespace(char[] buffer,
                                int start,
                                int len)
                         throws SAXException

Process notification of ignorable whitespace received from the body of an XML element.

Specified by:

ignorableWhitespace in interface ContentHandler

Overrides:

ignorableWhitespace in class org.xml.sax.helpers.DefaultHandler

Parameters:

buffer - The characters from the XML document

start - Starting offset into the buffer

len - Number of characters from the buffer

Throws:

SAXException - if a parsing error is to be reported

processingInstruction

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

Process notification of a processing instruction that was encountered.

Specified by:

processingInstruction in interface ContentHandler

Overrides:

processingInstruction in class org.xml.sax.helpers.DefaultHandler

Parameters:

target - The processing instruction target

data - The processing instruction data (if any)

Throws:

SAXException - if a parsing error is to be reported

setDocumentLocator

public void setDocumentLocator(Locator locator)

Set the document locator associated with our parser.

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

setDocumentLocator in class org.xml.sax.helpers.DefaultHandler

Parameters:

locator - The new locator

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

Process notification of a skipped entity.

Specified by:

skippedEntity in interface ContentHandler

Overrides:

skippedEntity in class org.xml.sax.helpers.DefaultHandler

Parameters:

name - Name of the skipped entity

Throws:

SAXException - if a parsing error is to be reported

notationDecl

public void notationDecl(String name,
                         String publicId,
                         String systemId)

Receive notification of a notation declaration event.

Specified by:

notationDecl in interface DTDHandler

Overrides:

notationDecl in class org.xml.sax.helpers.DefaultHandler

Parameters:

name - The notation name

publicId - The public identifier (if any)

systemId - The system identifier (if any)

unparsedEntityDecl

public void unparsedEntityDecl(String name,
                               String publicId,
                               String systemId,
                               String notation)

Receive notification of an unparsed entity declaration event.

Specified by:

unparsedEntityDecl in interface DTDHandler

Overrides:

unparsedEntityDecl in class org.xml.sax.helpers.DefaultHandler

Parameters:

name - The unparsed entity name

publicId - The public identifier (if any)

systemId - The system identifier (if any)

notation - The name of the associated notation

error

public void error(SAXParseException exception)
           throws SAXException

Forward notification of a parsing error to the application supplied error handler, if any, otherwise throw a SAXException with the error.

Specified by:

error in interface ErrorHandler

Overrides:

error in class org.xml.sax.helpers.DefaultHandler

Parameters:

exception - The error information

Throws:

SAXException - if a parsing exception occurs

fatalError

public void fatalError(SAXParseException exception)
                throws SAXException

Forward notification of a fatal parsing error to the application supplied error handler, if any, otherwise throw a SAXException with the error.

Specified by:

fatalError in interface ErrorHandler

Overrides:

fatalError in class org.xml.sax.helpers.DefaultHandler

Parameters:

exception - The fatal error information

Throws:

SAXException - if a parsing exception occurs

warning

public void warning(SAXParseException exception)
             throws SAXException

Forward notification of a parse warning to the application supplied error handler (if any). Unlike XMLParser.error(SAXParseException) and XMLParser.fatalError(SAXParseException), this implementation will NOT throw a SAXException by default if no error handler is supplied.

Specified by:

warning in interface ErrorHandler

Overrides:

warning in class org.xml.sax.helpers.DefaultHandler

Parameters:

exception - The warning information

Throws:

SAXException - if a parsing exception occurs

configure

protected void configure()

This method is called only once before parsing occurs which allows tag libraries to be registered and so forth

getJellyProperties

protected Properties getJellyProperties()

A helper method which loads the static Jelly properties once on startup

createTag

protected TagScript createTag(String namespaceURI,
                              String localName,
                              Attributes list)
                       throws SAXException

Factory method to create new Tag script for the given namespaceURI and name or return null if this is not a custom Tag.

Throws:

SAXException

createStaticTag

protected TagScript createStaticTag(String namespaceURI,
                                    String localName,
                                    String qName,
                                    Attributes list)
                             throws SAXException

Factory method to create a static Tag that represents some static content.

Note that to if you use jelly:define taglib, these tags might turn out to be non-static during the runtime.

Throws:

SAXException

configureStaticTagAttributes

protected void configureStaticTagAttributes(TagScript script,
                                            Attributes list)
                                     throws JellyException

Throws:

JellyException

configureTagScript

protected void configureTagScript(TagScript aTagScript)

Configure a newly created TagScript instance before any Expressions are created

Parameters:

aTagScript -

addTextScript

protected void addTextScript(String text,
                             boolean start)
                      throws JellyException

Adds the text to the current script block parsing any embedded expressions into ExpressionScript objects.

Parameters:

start - If the text precedes a start element. Otherwise the text precedes an end element.

Throws:

JellyException

addExpressionScript

protected void addExpressionScript(ScriptBlock script,
                                   Expression expression)

Adds the given Expression object to the current Script.

createConstantExpression

protected Expression createConstantExpression(String tagName,
                                              String attributeName,
                                              String attributeValue)

createExpressionFactory

protected ExpressionFactory createExpressionFactory()

getCurrentURI

protected String getCurrentURI()

Returns:

the current context URI as a String or null if there is no current context defined on the JellyContext

createSAXException

protected SAXException createSAXException(String message,
                                          Exception e)

Create a SAX exception which also understands about the location in the file where the exception occurs

Returns:

the new exception

createSAXException

protected SAXException createSAXException(Exception e)

Create a SAX exception which also understands about the location in the digester file where the exception occurs

Returns:

the new exception

createSAXException

protected SAXException createSAXException(String message)

Create a SAX exception which also understands about the location in the digester file where the exception occurs

Returns:

the new exception