org.apache.openjpa.lib.meta
Class XMLMetaDataParser

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      org.apache.openjpa.lib.meta.XMLMetaDataParser

All Implemented Interfaces:

MetaDataParser, ContentHandler, DTDHandler, EntityResolver, ErrorHandler, LexicalHandler

Direct Known Subclasses:

CFMetaDataParser, XMLSchemaParser

public abstract class XMLMetaDataParser
extends DefaultHandler
implements LexicalHandler, MetaDataParser

Custom SAX parser used by the system to quickly parse metadata files. Subclasses should handle the processing of the content.

Author:

Abe White

Constructor Summary

XMLMetaDataParser()

Method Summary

protected void	addComments(Object obj) Add current comments to the given entity.
protected void	addResult(Object result) Add a result to be returned from the current parse.
void	characters(char[] ch, int start, int length)
void	clear() Clears the cache of parsed resource names.
void	comment(char[] ch, int start, int length)
protected ClassLoader	currentClassLoader() Return the class loader to use when resolving resources and loading classes.
protected String[]	currentComments() Array of comments for the current node, or empty array if none.
protected int	currentDepth() Return the parse depth.
protected String	currentLocation() Return the current location within the source file.
protected String	currentText() Return the text value within the current node.
void	endCDATA()
void	endDTD()
protected abstract void	endElement(String name) Override this method marking the end of some element.
void	endElement(String uri, String name, String qName)
void	endEntity(String name)
void	error(SAXParseException se)
void	fatalError(SAXParseException se)
protected void	finish() Override this method to finish up after a parse; this is only called if no errors are encountered during parsing.
ClassLoader	getClassLoader() Classloader to use for class name resolution.
protected Reader	getDocType() Override this method to return any DOCTYPE declaration that should be dynamically included in xml documents that will be validated.
protected SAXException	getException(Localizer.Message msg) Returns a SAXException with the source file name and the given error message.
protected SAXException	getException(Localizer.Message msg, Throwable cause) Returns a SAXException with the source file name and the given error message.
protected SAXException	getException(String msg) Returns a SAXException with the source file name and the given error message.
LexicalHandler	getLexicalHandler() The lexical handler that should be registered with the SAX parser used by this class.
Location	getLocation() The XML document location.
Log	getLog() The log to write to.
boolean	getParseComments() Whether to parse element comments.
boolean	getParseText() Whether to parse element text.
List	getResults() Return the results from the last parse.
protected Object	getSchemaSource() Implement to return the XML schema source for the document.
protected File	getSourceFile() Return the file of the source being parsed.
boolean	getSourceIsSystemId() Whether to use the source name as the XML system id.
protected String	getSourceName() Return the name of the source file being parsed.
String	getSuffix() Expected suffix for metadata resources, or null if unknown.
protected void	ignoreContent(boolean ignoreEnd) Ignore all content below the current element.
boolean	isCaching() Whether parsed resource names are cached to avoid duplicate parsing.
boolean	isValidating() Whether this is a validating parser.
void	parse(Class cls, boolean topDown) Parse all possible metadata locations for the given class, going top-down or bottom-up.
void	parse(File file) Parse the given file, which may be a directory, in which case it will be scanned recursively for metadata files.
void	parse(MetaDataIterator itr) Parse the metadata supplied by the given iterator.
void	parse(Reader xml, String sourceName) Parse the metadata in the given reader.
void	parse(String rsrc) Parse the given resource.
void	parse(URL url) Parse the given resource.
protected boolean	parsed(String src) Return true if the given source is parsed.
protected void	parseNewResource(Reader xml, String sourceName) Parse a previously-unseen source.
protected void	reset() Override this method to clear any state and ready the parser for a new document.
void	setCaching(boolean caching) Whether parsed resource names are cached to avoid duplicate parsing.
void	setClassLoader(ClassLoader loader) Classloader to use for class name resolution.
void	setDocumentLocator(Locator locator)
void	setLexicalHandler(LexicalHandler lh) The lexical handler that should be registered with the SAX parser used by this class.
void	setLocation(Location location) The XML document location.
void	setLog(Log log) The log to write to.
void	setParseComments(boolean comments) Whether to parse element comments.
void	setParseText(boolean text) Whether to parse element text.
void	setSourceIsSystemId(boolean systemId) Whether to use the source name as the XML system id.
void	setSuffix(String suffix) Expected suffix for metadata resources, or null if unknown.
void	setValidating(boolean validating) Whether this is a validating parser.
void	startCDATA()
void	startDTD(String name, String publicId, String systemId)
protected abstract boolean	startElement(String name, Attributes attrs) Override this method marking the start of some element.
void	startElement(String uri, String name, String qName, Attributes attrs)
void	startEntity(String name)

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

endDocument, endPrefixMapping, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLMetaDataParser

public XMLMetaDataParser()

Method Detail

getParseText

public boolean getParseText()

Whether to parse element text.

setParseText

public void setParseText(boolean text)

Whether to parse element text.

getParseComments

public boolean getParseComments()

Whether to parse element comments.

setParseComments

public void setParseComments(boolean comments)

Whether to parse element comments.

getLocation

public Location getLocation()

The XML document location.

getLexicalHandler

public LexicalHandler getLexicalHandler()

The lexical handler that should be registered with the SAX parser used by this class. Since the org.xml.sax.ext package is not a required part of SAX2, this handler might not be used by the parser.

setLexicalHandler

public void setLexicalHandler(LexicalHandler lh)

The lexical handler that should be registered with the SAX parser used by this class. Since the org.xml.sax.ext package is not a required part of SAX2, this handler might not be used by the parser.

setLocation

public void setLocation(Location location)

The XML document location.

getSourceIsSystemId

public boolean getSourceIsSystemId()

Whether to use the source name as the XML system id.

setSourceIsSystemId

public void setSourceIsSystemId(boolean systemId)

Whether to use the source name as the XML system id.

isValidating

public boolean isValidating()

Whether this is a validating parser.

setValidating

public void setValidating(boolean validating)

Whether this is a validating parser.

getSuffix

public String getSuffix()

Expected suffix for metadata resources, or null if unknown.

setSuffix

public void setSuffix(String suffix)

Expected suffix for metadata resources, or null if unknown.

isCaching

public boolean isCaching()

Whether parsed resource names are cached to avoid duplicate parsing.

setCaching

public void setCaching(boolean caching)

Whether parsed resource names are cached to avoid duplicate parsing.

getLog

public Log getLog()

The log to write to.

setLog

public void setLog(Log log)

The log to write to.

getClassLoader

public ClassLoader getClassLoader()

Classloader to use for class name resolution.

setClassLoader

public void setClassLoader(ClassLoader loader)

Classloader to use for class name resolution.

Specified by:

setClassLoader in interface MetaDataParser

getResults

public List getResults()

Description copied from interface: MetaDataParser

Return the results from the last parse.

Specified by:

getResults in interface MetaDataParser

parse

public void parse(String rsrc)
           throws IOException

Description copied from interface: MetaDataParser

Parse the given resource.

Specified by:

parse in interface MetaDataParser

Throws:

IOException

parse

public void parse(URL url)
           throws IOException

Description copied from interface: MetaDataParser

Parse the given resource.

Specified by:

parse in interface MetaDataParser

Throws:

IOException

parse

public void parse(File file)
           throws IOException

Description copied from interface: MetaDataParser

Parse the given file, which may be a directory, in which case it will be scanned recursively for metadata files.

Specified by:

parse in interface MetaDataParser

Throws:

IOException

parse

public void parse(Class cls,
                  boolean topDown)
           throws IOException

Description copied from interface: MetaDataParser

Parse all possible metadata locations for the given class, going top-down or bottom-up. If the class is null, only top-level locations will be parsed.

Specified by:

parse in interface MetaDataParser

Throws:

IOException

parse

public void parse(Reader xml,
                  String sourceName)
           throws IOException

Description copied from interface: MetaDataParser

Parse the metadata in the given reader.

Specified by:

parse in interface MetaDataParser

Parameters:

xml - reader containing the metadata to parse

sourceName - the name of the source being parsed, for use in error messages

Throws:

IOException

parse

public void parse(MetaDataIterator itr)
           throws IOException

Description copied from interface: MetaDataParser

Parse the metadata supplied by the given iterator.

Specified by:

parse in interface MetaDataParser

Throws:

IOException

parseNewResource

protected void parseNewResource(Reader xml,
                                String sourceName)
                         throws IOException

Parse a previously-unseen source. All parsing methods delegate to this one.

Throws:

IOException

parsed

protected boolean parsed(String src)

Return true if the given source is parsed. Otherwise, record that it will be parsed.

clear

public void clear()

Description copied from interface: MetaDataParser

Clears the cache of parsed resource names.

Specified by:

clear in interface MetaDataParser

error

public void error(SAXParseException se)
           throws SAXException

Specified by:

error in interface ErrorHandler

Overrides:

error in class DefaultHandler

Throws:

SAXException

fatalError

public void fatalError(SAXParseException se)
                throws SAXException

Specified by:

fatalError in interface ErrorHandler

Overrides:

fatalError in class DefaultHandler

Throws:

SAXException

setDocumentLocator

public void setDocumentLocator(Locator locator)

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

setDocumentLocator in class DefaultHandler

startElement

public void startElement(String uri,
                         String name,
                         String qName,
                         Attributes attrs)
                  throws SAXException

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class DefaultHandler

Throws:

SAXException

endElement

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

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class DefaultHandler

Throws:

SAXException

characters

public void characters(char[] ch,
                       int start,
                       int length)

Specified by:

characters in interface ContentHandler

Overrides:

characters in class DefaultHandler

comment

public void comment(char[] ch,
                    int start,
                    int length)
             throws SAXException

Specified by:

comment 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

startDTD

public void startDTD(String name,
                     String publicId,
                     String systemId)
              throws SAXException

Specified by:

startDTD in interface LexicalHandler

Throws:

SAXException

endDTD

public void endDTD()
            throws SAXException

Specified by:

endDTD in interface LexicalHandler

Throws:

SAXException

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

startElement

protected abstract boolean startElement(String name,
                                        Attributes attrs)
                                 throws SAXException

Override this method marking the start of some element. If this method returns false, the content of the element and the end element event will be ignored.

Throws:

SAXException

endElement

protected abstract void endElement(String name)
                            throws SAXException

Override this method marking the end of some element.

Throws:

SAXException

addResult

protected void addResult(Object result)

Add a result to be returned from the current parse.

finish

protected void finish()

Override this method to finish up after a parse; this is only called if no errors are encountered during parsing. Subclasses should call super.finish() to resolve superclass state.

reset

protected void reset()

Override this method to clear any state and ready the parser for a new document. Subclasses should call super.reset() to clear superclass state.

getSchemaSource

protected Object getSchemaSource()
                          throws IOException

Implement to return the XML schema source for the document. Returns null by default. May return:

• String pointing to schema URI.
• InputStream containing schema contents.
• InputSource containing schema contents.
• File containing schema contents.
• Array of any of the above elements.

Throws:

IOException

getDocType

protected Reader getDocType()
                     throws IOException

Override this method to return any DOCTYPE declaration that should be dynamically included in xml documents that will be validated. Returns null by default.

Throws:

IOException

getSourceName

protected String getSourceName()

Return the name of the source file being parsed.

getSourceFile

protected File getSourceFile()

Return the file of the source being parsed.

addComments

protected void addComments(Object obj)

Add current comments to the given entity. By default, assumes entity is Commentable.

currentComments

protected String[] currentComments()

Array of comments for the current node, or empty array if none.

currentText

protected String currentText()

Return the text value within the current node.

currentLocation

protected String currentLocation()

Return the current location within the source file.

currentDepth

protected int currentDepth()

Return the parse depth. Within the root element, the depth is 0, within the first nested element, it is 1, and so forth.

currentClassLoader

protected ClassLoader currentClassLoader()

Return the class loader to use when resolving resources and loading classes.

ignoreContent

protected void ignoreContent(boolean ignoreEnd)

Ignore all content below the current element.

Parameters:

ignoreEnd - whether to ignore the end element event

getException

protected SAXException getException(String msg)

Returns a SAXException with the source file name and the given error message.

getException

protected SAXException getException(Localizer.Message msg)

Returns a SAXException with the source file name and the given error message.

getException

protected SAXException getException(Localizer.Message msg,
                                    Throwable cause)

Returns a SAXException with the source file name and the given error message.