org.openxml.parser

Class ContentParser

java.lang.Object

org.openxml.parser.StreamParser

org.openxml.parser.ContentParser

All Implemented Interfaces:

EntityResolver, Locator, Parser

Direct Known Subclasses:

HTMLSAXParser, XMLSAXParser

public abstract class ContentParser
extends StreamParser
implements Parser

Implements layers 3 of the parser architecture, the handling of XML/HTML document content. This level also implements the SAX parser interface for setting document handler, etc.

This parser is created by a derived class. The init(org.xml.sax.InputSource) method must be called before the parser is used or re-used (the parser is re-entrant).

Author:

Assaf Arkin

See Also:

Parser, StreamParser, TokenParser, FastString

Field Summary

Fields

Modifier and Type	Field and Description
protected DocumentTypeImpl	_docType Holds the DTD document for this document or null.
protected DocumentHandler	_documentHandler Reference to document handler.
protected DTDHandler	_dtdHandler Reference to DTD handler.
protected EntityResolver	_entityResolver Reference to external entity resolver.
protected FastString	_nodeText Holds the contents of text node collected between elements and other non-textual nodes.

Fields inherited from class org.openxml.parser.StreamParser

_curChar, _tokenText, CR, EOF, LF, SPACE, TOKEN_CDATA, TOKEN_CLOSE_TAG, TOKEN_COMMENT, TOKEN_DTD, TOKEN_ENTITY_REF, TOKEN_EOF, TOKEN_OPEN_TAG, TOKEN_PE_REF, TOKEN_PI, TOKEN_SECTION, TOKEN_SECTION_END, TOKEN_TEXT, VALIDITY, WELL_FORMED

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ContentParser() Protected constructor only accessible from derived class.

Method Summary

Modifier and Type	Method and Description
protected void	enterElementState(String tagName, int lineNumber, boolean elementContent)
protected org.openxml.parser.ElementState	getElementState()
protected org.openxml.parser.ElementState	getPreviousState(org.openxml.parser.ElementState state)
protected void	init(InputSource input) Initializes the parser to parse a new document.
protected abstract boolean	isHtml()
protected boolean	isTokenSpace()
protected org.openxml.parser.ElementState	leaveElementState()
void	parse(String systemId)
protected void	parseAttrEntity(String name) Parses an internal general entity into the attribute value.
protected boolean	parseAttributes(String tagName) Parses the attribute list of an XML/HTML open tag and calls the proper events for this element using the attribute list.
protected void	parseContentEntity() Parses an internal or external general entity into XML/HTML contents.
protected boolean	parseDocumentDecl(boolean XMLDecl) Parses the document declaration for XML documents and external entities, returning the standalone status and changing the character encoding (if necessary).
protected EntityImpl	parseGeneralEntity(EntityImpl entity) Parses the general entity, returning the entity as parsed.
protected int	readTokenContent() Reads and returns a single content token.
protected int	readTokenEntity() Reads general entity reference token or character reference.
protected int	readTokenEntity(boolean ignoreError)
protected int	readTokenMarkup() Reads markup token.
protected int	readTokenPERef() Reads parameter entity reference token.
InputSource	resolveEntity(String publicId, String systemId)
void	setDocumentHandler(DocumentHandler handler)
void	setDTDHandler(DTDHandler handler)
void	setEntityResolver(EntityResolver resolver)
protected String	slicePITokenText() Slices processing instruction text into target and instruction code.

Methods inherited from class org.openxml.parser.StreamParser

canReadName, close, error, fatalError, format, format, format, getColumnNumber, getErrorHandler, getLastException, getLineNumber, getPublicId, getReader, getSystemId, isClosed, isNamePart, isNamePartFirst, isSpace, isTokenAllSpace, isWarning, message, pushBack, pushBack, pushBack, pushBackToken, readChar, readTokenName, readTokenNameCur, readTokenQuoted, setEncoding, setErrorHandler, setLocale, skipSpace, warning

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.xml.sax.Parser

parse, setErrorHandler, setLocale

Field Detail

_docType

protected DocumentTypeImpl _docType

Holds the DTD document for this document or null.

_nodeText

protected FastString _nodeText

Holds the contents of text node collected between elements and other non-textual nodes. Consists of all plain text and resolved entities.

This is a state variable. Methods that use it directly or indirectly must be alert to its present state and usage and must reset it as needed. General value on entry/exit is specified in the method comment.

_documentHandler

protected DocumentHandler _documentHandler

Reference to document handler. Used to build the document contents based on the SAX document handler. Can be null and can change mid-parsing.

_dtdHandler

protected DTDHandler _dtdHandler

Reference to DTD handler. Used to build the document contents based on the SAX DTD handler. Can be null and can change mid-parsing.

_entityResolver

protected EntityResolver _entityResolver

Reference to external entity resolver. Used to locate external entitys based on the SAX entity resolver. Can be null and can change mid-parsing.

Constructor Detail

ContentParser

protected ContentParser()

Protected constructor only accessible from derived class.

Method Detail

init

protected void init(InputSource input)
             throws SAXException,
                    IOException

Initializes the parser to parse a new document. Must be called before any parsing occurs. See StreamParser.init(org.xml.sax.InputSource).

Parameters:

input - The input source to parse

Throws:

SAXException - The input source cannot be used

IOException

setDTDHandler

public final void setDTDHandler(DTDHandler handler)

Specified by:

setDTDHandler in interface Parser

setDocumentHandler

public final void setDocumentHandler(DocumentHandler handler)

Specified by:

setDocumentHandler in interface Parser

setEntityResolver

public final void setEntityResolver(EntityResolver resolver)

Specified by:

setEntityResolver in interface Parser

parse

public final void parse(String systemId)
                 throws SAXException,
                        IOException

Specified by:

parse in interface Parser

Throws:

SAXException

IOException

resolveEntity

public final InputSource resolveEntity(String publicId,
                                       String systemId)
                                throws IOException,
                                       SAXException

Specified by:

resolveEntity in interface EntityResolver

Overrides:

resolveEntity in class StreamParser

Throws:

IOException

SAXException

readTokenContent

protected final int readTokenContent()
                              throws SAXException

Reads and returns a single content token. The token's code is returned and the token's text is available in StreamParser._tokenText. No valid character is held in StreamParser._curChar on entry or on exit. Returned token is suitable for document contents in either XML or HTML document or external entity. StreamParser.TOKEN_EOF indicates the end of the input stream.

Plain text is returned as a StreamParser.TOKEN_TEXT token. Text that is part of the element contents may be returned as multiple tokens, or text tokens interwined with entity reference tokens (of type StreamParser.TOKEN_ENTITY_REF).

For specific information about token processing, see readTokenMarkup() and readTokenEntity().

Returns:

The token code

Throws:

SAXException - A parsing error has been encountered, and based on it severity, an exception is thrown to terminate parsing

See Also:

StreamParser._tokenText, readTokenMarkup(), readTokenEntity()

parseContentEntity

protected final void parseContentEntity()
                                 throws SAXException

Parses an internal or external general entity into XML/HTML contents. Called when an entity reference is encountered in the element contents. StreamParser._tokenText contains the entity name on entry. Events are fired to store the entity's value in the document contents.

If the entity is unparsed general, or not found, an error is issued.

If the entity could not be found or could not be parsed, an error is issued The contents of the parsed entity is duplicated and placed in the document either through node cloning or SAX events If the parsed entity contains an entity reference, it is parsed recursively according to the same rules

Throws:

SAXException - A parsing error has been encountered, and based on it severity, an exception is thrown to terminate parsing

parseGeneralEntity

protected final EntityImpl parseGeneralEntity(EntityImpl entity)
                                       throws SAXException

Parses the general entity, returning the entity as parsed. An existing EntityImpl is passed to the method. On exit, the same entity (parsed) is returned, or null to indicate that the entity could not be parsed.

The following rules govern how the entity is parsed:

• If the entity's state is EntityImpl.STATE_PARSED, then the entity has been parsed before, and is returned.
• If the entity's state is EntityImpl.STATE_NOT_FOUND, then the entity could not be found, and null is returned. There is no need to issue an error again.
• If the entity's state is EntityImpl.STATE_PARSING, then the entity is being parsed: this is a circular reference, an error is issued and null is returned.
• If the entity's state is EntityImpl.STATE_DECLARED, then the entity is being parsed. For an external entity, the entity source is being located using HolderFinder. If the entity source could not be found or could not be opened, the entity state is set to EntityImpl.STATE_NOT_FOUND, an error is issued and null returned. For an internal entity, the entity source is created from it's value.
• If the entity's state is EntityImpl.STATE_DECLARED and the entity source could be located, an XMLParser is created and used to parse the entity. If no fatal errors are encountered when parsing, the entity is returned. Well formed errors are treated as if generated by the current parser.
• If the entity's state is EntityImpl.STATE_DECLARED and a fatal error was issued while parsing the entity with an XMLParser, then a fatal error is issued and an exception raised.

Well formed and validity errors issued by the external entity parser are reported directly to this parser and treated by the error mode of this entity. Fatal and I/O exceptions will terminate parsing with a fatal error.

Parameters:

entity - The entity to parse

Returns:

The entity if parsed, null if could not be parsed

Throws:

SAXException - A parsing error has been encountered, and based on it severity, an exception is thrown to terminate parsing

parseAttributes

protected boolean parseAttributes(String tagName)
                           throws SAXException

Parses the attribute list of an XML/HTML open tag and calls the proper events for this element using the attribute list. If this element is empty (XML only), returns true and calls both element start and end events. If this is an opening tag (all tags for HTML), returns false

On entry the element's tag name and optional whitespaces have been read. On exit, all attributes have been read including the closing mark. No valid character is held in StreamParser._curChar on entry or on exit.

Parameters:

tagName - Name of element being parsed

xml - True if parsing an XML document, false for HTML

Returns:

True if an open tag is parsed, false if an empty tag or any HTML tag

Throws:

SAXException - A parsing error has been encountered, and based on it severity, an exception is thrown to terminate parsing

parseAttrEntity

protected final void parseAttrEntity(String name)
                              throws SAXException

Parses an internal general entity into the attribute value. Called by parseAttributes(java.lang.String) when an entity reference is encountered in the attribute value. StreamParser._tokenText contains the entity name on entry and the parsed value on exit.

If the entity is external, unparsed general or not found, an error is issued and nothing is placed in the attribute value.

Throws:

SAXException - A parsing error has been encountered, and based on it severity, an exception is thrown to terminate parsing

isTokenSpace

protected final boolean isTokenSpace()

enterElementState

protected final void enterElementState(String tagName,
                                       int lineNumber,
                                       boolean elementContent)

getElementState

protected final org.openxml.parser.ElementState getElementState()

leaveElementState

protected final org.openxml.parser.ElementState leaveElementState()

getPreviousState

protected final org.openxml.parser.ElementState getPreviousState(org.openxml.parser.ElementState state)

isHtml

protected abstract boolean isHtml()

readTokenMarkup

protected final int readTokenMarkup()
                             throws SAXException

Reads markup token. Returns the token code and the token value in StreamParser._tokenText. The preceding '<' has been consumed prior to calling this method. No valid character is held in StreamParser._curChar on entry or exit.

The following rules govern how tokens are parsed and which code is returned:

• StreamParser.TOKEN_OPEN_TAG returned for opening tag. Opening tag is '<' immediately followed by valid tag name (returned as token text) and optional whitespace. Attributes and terminating '>' are not read by this method. A whitespace between the '<' and tag name is reported as an error; an empty tag name will never be returned.
  
• StreamParser.TOKEN_CLOSE_TAG returned for closing tag. Closing tag is '</' followed by valid tag name (returned as token text) and '>'. All text following the tag name until the terminating '>' is ignored; a whitespace between the '<' and tag name is reported as an error; an empty tag name will never be returned.
  
• StreamParser.TOKEN_COMMENT returned for comment. Comment is terminated with '<!--' and '-->'. All text inbetween is consumed, and returned as token text.
  
• StreamParser.TOKEN_CDATA returned for CDATA section. Section starts with '<![CDATA[' and ends with ']]>'. All text inbetween is consumed and returned as token text.
  
• StreamParser.TOKEN_PI returned for processing instruction. Processing instruction is terminated with '<?' and '?>'. All text inbetween is consumed, and returned as token text.
  
• StreamParser.TOKEN_DTD returned for DTD declaration. DTD declaration starts with '<!' immediately followed by a token name (returned as token text). All other declaration contents is not read by this method. A whitespace between the '<!' and the token name is not allowed; an empty declaration name is never returned.
  
• StreamParser.TOKEN_SECTION returned for DTD conditional section. Conditional section begins with '<![' and is not a CDATA section. Only the '<![' sequence is read and consumed by this method.

If no markup is found, the token code StreamParser.TOKEN_TEXT is returned, with '<' contained in StreamParser._tokenText and the input stream is not affected. An error is reported.

Returns:

The markup token code of StreamParser.TOKEN_TEXT

Throws:

SAXException - A parsing error has been encountered

readTokenEntity

protected final int readTokenEntity()
                             throws SAXException

Reads general entity reference token or character reference. Returns the token code StreamParser.TOKEN_ENTITY_REF and the entity name in StreamParser._tokenText. The preceding '&' has been consumed prior to calling this method, and the trailing ';' is consumed by this method. No valid character is held in StreamParser._curChar on entry or exit.

If no valid entity name is found, the token code StreamParser.TOKEN_TEXT is returned, with '&' contained in StreamParser._tokenText and the input stream is not affected.

A '#' sign indicates a character reference (either decimal or hexadecimal) which is read and stored in StreamParser._tokenText, and the token code StreamParser.TOKEN_TEXT is returned. If the character reference value is invalid, the token code StreamParser.TOKEN_TEXT is returned, with the invalid part contained in StreamParser._tokenText and the input stream is not affected.

If the entity reference or character reference is not terminated with a ';', a well-formed error is issued, and the name is returned as textual string instead of an entity reference.

Returns:

Token code either StreamParser.TOKEN_ENTITY_REF or StreamParser.TOKEN_TEXT

Throws:

SAXException - A parsing error has been encountered

readTokenEntity

protected final int readTokenEntity(boolean ignoreError)
                             throws SAXException

Throws:

SAXException

parseDocumentDecl

protected final boolean parseDocumentDecl(boolean XMLDecl)
                                   throws SAXException

Parses the document declaration for XML documents and external entities, returning the standalone status and changing the character encoding (if necessary). Errors are issued if the document declaration is invalid.

The document declaration is contained in a processing instruction that appears at the very beginning of the document or entity and begins with 'xml' (case sensitive). The processing instruction's full text is expected in the variable StreamParser._tokenText on entry.

The declaration for XML documents contains a version number, optional character encoding and optional standalone status. The default standalone status is false. The declaration for external entities and external subsets contains an optional version number, and mandatory character encoding.

Currently only XML version "1.0" is supported. The current character encoding is changed by calling StreamParser.setEncoding(java.lang.String).

Parameters:

XMLDecl - True if expecting XML document declaration, false if expecting external entity/subset declaration

Returns:

True if XML document is standalone

Throws:

SAXException - A parsing error has been encountered

slicePITokenText

protected final String slicePITokenText()
                                 throws SAXException

Slices processing instruction text into target and instruction code. Called with the processing instruction text in StreamParser._tokenText, returning the valid target name, and StreamParser._tokenText truncated to contain just the instruction code. If no valid target name is found, an empty name amd empty instruction are returned. StreamParser._curChar is undetermined on entry and exit and is used inside function.

Returns:

The target name

Throws:

SAXException - A parsing error has been encountered

readTokenPERef

protected final int readTokenPERef()
                            throws SAXException,
                                   IOException

Reads parameter entity reference token. Returns the token code StreamParser.TOKEN_PE_REF and the entity name in StreamParser._tokenText. The preceding '%' has been consumed prior to calling this method, and the trailing ';' is consumed by this method. No valid character is held in StreamParser._curChar on entry or exit.

If no valid entity name is found, the token code StreamParser.TOKEN_TEXT is returned, with '%' contained in StreamParser._tokenText and the input stream is not affected.

If the entity reference is not terminated with a ';', a well-formed error is issued, but the entity reference is still regarded valid.

Returns:

Token code either StreamParser.TOKEN_PE_REF or StreamParser.TOKEN_TEXT

Throws:

SAXException - A parsing error has been encountered, and based on it severity, an exception is thrown to terminate parsing

IOException - An I/O exception has been encountered when reading from the input stream