uk.ac.sheffield.jast

Class XMLReader

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.BasicReader

uk.ac.sheffield.jast.XMLReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

XSDReader

public class XMLReader
extends BasicReader

XMLReader is a pull-parser that constructs a classic XML syntax tree. XMLReader is an efficient recursive descent pull-parser that constructs a classic XML syntax tree out of Java nodes that directly model the XML types and attributes. XMLReader creates a tree rooted in the node Document, consisting of types such as Declaration, Doctype, Element, Attribute and Text. XMLReader uses the standard construction API for XML nodes, which are provided in the sub-package uk.ac.sheffield.jast.xml.

XMLReader uses the low-level token scanner XMLScanner to supply it with integer tokens, members of the Tokens class, that represent different recognised XML events. It consumes these events and, where events are associated with segmented text, it consumes the associated text. The resulting model is returned as an instance of Document, which by default is compact (discarding formatting whitespace surrounding XML elements). XMLReader may be requested to preserve full native format (keeping all original layout text as extra Text nodes).

By default, XMLReader will return a well-formed XML Document, or report that the XML syntax was faulty. XMLReader may be requested to validate the Document, to ensure that it conforms to some grammar defined by a Doctype, or an XML schema, so long as the Document refers to these. It may also be instructed to expand new entity references as part of a Doctype. XMLReader implements the Closeable interface by virtue of inheriting from BasicReader.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
protected Document	document The top-level Document constructed by this reader.
private boolean	hasDoctype Flag indicating whether the Document ha a Doctype node.
private boolean	hasElement Flag indicating whether the Document has a root Element.
private boolean	rawLayout A flag describing whether to preserve the native format of the XML.

Fields inherited from class uk.ac.sheffield.jast.BasicReader

lastToken, lexicon, scanner, validation

Constructor Summary

Constructors

Constructor and Description
XMLReader(java.io.File file) Creates an XMLReader reading from a file, using the default UTF-8 character encoding.
XMLReader(java.io.File file, java.lang.String encoding) Creates an XMLReader reading from a file, using the specified character encoding.
XMLReader(java.io.InputStream stream, java.lang.String encoding) Creates an XMLReader reading from a basic input stream, using the specified character encoding.
XMLReader(java.io.Reader reader, java.lang.String encoding) Creates an XMLReader reading from a character reader, using the specified character encoding.
XMLReader(java.net.URL url) Creates an XMLReader reading from a URL, using the default ISO-8859-1 (Latin-1) character encoding specified for the MIME-type text/xml.
XMLReader(java.net.URL url, java.lang.String encoding) Creates an XMLReader reading from a URL, using the specified character encoding.

Method Summary

Modifier and Type	Method and Description
protected Content	parseAnyContent() Parses one kind of XML content.
protected Attribute	parseAttribute() Parses an XML attribute.
protected Comment	parseComment() Parses an XML comment.
protected Declaration	parseDeclaration() Parses the XML Declaration.
protected Doctype	parseDoctype() Parses a doctype declaration.
protected void	parseDocumentBody() Parses the rest of the Document after any required Declaration (for XML files) or Doctype (for HTML files).
protected Element	parseElement() Parses an XML element.
protected Data	parseEscapedData() Parses some escaped character data.
protected Instruction	parseInstruction() Parses an optional XML processing instruction.
protected Text	parseTextContent() Parses some text content.
void	preserveLayout(boolean value) Instructs this XMLReader whether to preserve, or ignore layout text.
Document	readDocument() Parses XML data from the input source and creates a classic Java XML syntax tree.
protected void	validate(Document document) Validates the Document using its own XMLSchema.

Methods inherited from class uk.ac.sheffield.jast.BasicReader

checkEncoding, close, endOfStream, getContext, getEncoding, getLexicon, getLineNumber, parseQuotedValue, setLexicon, setValidation

Methods inherited from class uk.ac.sheffield.jast.Logging

encodingError, semanticError, syntaxError

Methods inherited from class java.lang.Object

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

Field Detail

document

protected Document document

The top-level Document constructed by this reader.

rawLayout

private boolean rawLayout

A flag describing whether to preserve the native format of the XML. By default, this is false (i.e. layout space will be discarded).

hasElement

private boolean hasElement

Flag indicating whether the Document has a root Element. This is used to check the well-formedness of the document as it is parsed.

hasDoctype

private boolean hasDoctype

Flag indicating whether the Document ha a Doctype node. This is used to check the well-formedness of the document as it is parsed.

Constructor Detail

XMLReader

public XMLReader(java.io.File file)
          throws java.io.FileNotFoundException,
                 java.io.UnsupportedEncodingException

Creates an XMLReader reading from a file, using the default UTF-8 character encoding. Creates a XMLScanner reading from the file with the UTF-8 encoding.

Parameters:

file - the input text file.

Throws:

java.io.FileNotFoundException - if the file cannot be found or opened.

java.io.UnsupportedEncodingException - if UTF-8 is not supported.

XMLReader

public XMLReader(java.io.File file,
                 java.lang.String encoding)
          throws java.io.FileNotFoundException,
                 java.io.UnsupportedEncodingException

Creates an XMLReader reading from a file, using the specified character encoding. Recognised encodings include UTF-8, UTF-16, ISO-8859-1 (Latin-1) and others. Creates a XMLScanner reading from the file with the given encoding.

Parameters:

file - the input file.

encoding - the name of the character encoding.

Throws:

java.io.FileNotFoundException - if the file cannot be found or opened.

java.io.UnsupportedEncodingException - if the character encoding is not supported.

XMLReader

public XMLReader(java.net.URL url)
          throws java.io.IOException,
                 java.io.UnsupportedEncodingException

Creates an XMLReader reading from a URL, using the default ISO-8859-1 (Latin-1) character encoding specified for the MIME-type text/xml. Creates a XMLScanner reading from the URL with the ISO-8859-1 encoding.

Parameters:

url - the absolute URL giving the location of the XML data.

Throws:

java.io.IOException - if the attempt to connect to the URL and open an input stream to read from it fails.

java.io.UnsupportedEncodingException - if ISO-8859-1 is not supported.

XMLReader

public XMLReader(java.net.URL url,
                 java.lang.String encoding)
          throws java.io.IOException,
                 java.io.UnsupportedEncodingException

Creates an XMLReader reading from a URL, using the specified character encoding. Recognised encodings include UTF-8, UTF-16, ISO-8859-1 (Latin-1) and others. Creates a parser reading from the URL with the given encoding.

Parameters:

url - the absolute URL giving the location of the XML data.

encoding - the name of the character encoding.

Throws:

java.io.IOException - if the attempt to connect to the URL and open an input stream to read from it fails.

java.io.UnsupportedEncodingException - if the character encoding is not supported.

XMLReader

public XMLReader(java.io.InputStream stream,
                 java.lang.String encoding)
          throws java.io.UnsupportedEncodingException

Creates an XMLReader reading from a basic input stream, using the specified character encoding. Creates a XMLScanner reading from the basic input stream with the given encoding.

Parameters:

stream - the basic InputStream.

encoding - the name of the character encoding.

Throws:

java.io.UnsupportedEncodingException - if the character encoding is not supported.

XMLReader

public XMLReader(java.io.Reader reader,
                 java.lang.String encoding)

Creates an XMLReader reading from a character reader, using the specified character encoding. The character encoding should match that used by the Reader. Creates a XMLScanner reading from the reader, with the given encoding.

Parameters:

reader - the character Reader.

encoding - the name of the character encoding.

Method Detail

preserveLayout

public void preserveLayout(boolean value)

Instructs this XMLReader whether to preserve, or ignore layout text. If set to false (the default), all formatting white space is discarded. If set to true, extra Text nodes are constructed for all layout.

Parameters:

value - true, to retain a Document with all original layout text.

readDocument

public Document readDocument()
                      throws java.io.UnsupportedEncodingException,
                             java.io.IOException,
                             SyntaxError,
                             SemanticError

Parses XML data from the input source and creates a classic Java XML syntax tree. This is the main entry point into this XMLReader.

Returns:

the root Document of the XML syntax tree.

Throws:

java.io.UnsupportedEncodingException - if an encoding fault occurs.

java.io.IOException - if any other I/O error occurs.

SyntaxError - if the XML syntax is faulty.

SemanticError - if model constraints are broken.

parseDocumentBody

protected void parseDocumentBody()
                          throws java.io.IOException,
                                 SyntaxError

Parses the rest of the Document after any required Declaration (for XML files) or Doctype (for HTML files). If automatic validation has been requested, validates the Document in memory.

Throws:

java.io.IOException - if any other I/O error occurs.

SyntaxError - if the XML syntax is faulty.

parseAnyContent

protected Content parseAnyContent()
                           throws java.io.IOException,
                                  SyntaxError

Parses one kind of XML content. Branches on the last token returned by the XMLScanner, indicating the type of the next content, and dispatches to a more specific routine to parse that kind of content.

Returns:

the Content.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

parseDeclaration

protected Declaration parseDeclaration()
                                throws java.io.UnsupportedEncodingException,
                                       java.io.IOException,
                                       SyntaxError

Parses the XML Declaration. Creates a Declaration node, and parses the "version", "encoding" and optional "standalone" attributes.

Returns:

the Declaration node.

Throws:

java.io.UnsupportedEncodingException - if the declared encoding does not match the token stream's actual encoding.

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

parseInstruction

protected Instruction parseInstruction()
                                throws java.io.IOException,
                                       SyntaxError

Parses an optional XML processing instruction. Creates an Instruction node, and recursively parses all attributes of this node. Note that JAST will only accept processing instructions whose internal data is supplied in regular attribute-value format.

Returns:

the Instruction node.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

parseDoctype

protected Doctype parseDoctype()
                        throws java.io.IOException,
                               SyntaxError,
                               SemanticError

Parses a doctype declaration. Creates a Doctype node, and stores the name of the root element. If a systemID is provided, stores the external doctype file name under the "system" attribute. If a publicID is provided, stores the formal public identifier under the "public" attribute and the external doctype file name under the "system" attribute. If an internal grammar is provided, stores this as the text content of the Doctype node.

Returns:

the Doctype node.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

SemanticError - if more than one doctype is declared.

parseElement

protected Element parseElement()
                        throws java.io.IOException,
                               SyntaxError,
                               SemanticError

Parses an XML element. Creates an Element node and stores its name. Parses any XML attributes in the opening tag of the element, then recursively parses any dependent contents of the element.

Returns:

the Element node.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

SemanticError - if the DOM is complete.

parseAttribute

protected Attribute parseAttribute()
                            throws java.io.IOException,
                                   SyntaxError

Parses an XML attribute. Recursively parses the attribute's quoted value, then creates an Attribute node with a name and value.

Returns:

the Attribute node.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

parseTextContent

protected Text parseTextContent()
                         throws java.io.IOException,
                                SyntaxError

Parses some text content. Creates a Text node with the parsed text as its text-content, unless the parsed text is whitespace that is being ignored. Decodes any embedded entity references in the parsed text.

Returns:

the Text node, or null if ignored.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

parseEscapedData

protected Data parseEscapedData()
                         throws java.io.IOException,
                                SyntaxError

Parses some escaped character data. Creates a Data node and stores the escaped data as the text-content of this node.

Returns:

the Data node.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

parseComment

protected Comment parseComment()
                        throws java.io.IOException,
                               SyntaxError

Parses an XML comment. Creates a Comment node and stores the escaped text as the text-content of this node.

Returns:

the Comment node.

Throws:

java.io.IOException - if the token stream fails.

SyntaxError - if the XML syntax is faulty.

validate

protected void validate(Document document)
                 throws java.io.UnsupportedEncodingException,
                        java.io.IOException,
                        SyntaxError,
                        SemanticError

Validates the Document using its own XMLSchema. If the Document's root Element has a "noNamespaceSchemaLocation" attribute, uses the value of this as the path to the XMLSchema; otherwise, if it has a "schemaLocation" attribute, expects this to be a namespace-qualified schema location and uses the second part of the value as the path. If the path is a URL, opens an XSDReader expecting Latin-1 encoding; otherwise, opens an XSDReader expecting the same encoding as the main XML document. Reads the XMLSchema, closes the reader and then compiles the grammar rules of the XMLSchema.

Parameters:

document - the Document.

Throws:

java.io.UnsupportedEncodingException - if an encoding fault occurs.

java.io.IOException - if any other I/O error occurs.

SyntaxError - if the XML syntax is faulty.

SemanticError - if schema constraints are broken.