uk.ac.sheffield.jast

Class XMLScanner

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.BasicScanner

uk.ac.sheffield.jast.XMLScanner

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class XMLScanner
extends BasicScanner

XMLScanner is an efficient XML token scanner for any XML pull-parser. XMLScanner reads from any kind of input source and buffers tokens that represent recognised XML events and associated data that was segmented. Each recognised event is buffered as an integer token, a member of the Tokens class; and some tokens are associated with a segmented portion of text, which is buffered in a parallel queue. Pull-parsers which consume these tokens call getToken() to access the next token, and getText() to access any associated text.

XMLScanner is designed to buffer between 1-20 tokens on each call to getToken(), which allows parsers to work with the token stream during read-cycles from the underlying input stream. Pull-parsers are therefore faster than the equivalent combination of the push-parser XMLParser and one of the Builder classes; although the latter offer more possibilities for customised model-building. XMLScanner implements the Closeable interface by virtue of inheriting from BasicScanner.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

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

encoding, input, lastChar, symbolStack, textQueue, tokenQueue

Constructor Summary

Constructors

Constructor and Description
XMLScanner(java.io.File file, java.lang.String encoding) Creates a XMLScanner reading from a file, using a specified character encoding.
XMLScanner(java.io.InputStream stream, java.lang.String encoding) Creates a XMLScanner reading from a basic InputStream, using a specified character encoding.
XMLScanner(java.io.Reader reader, java.lang.String encoding) Creates a XMLScanner reading from a character Reader, using a specified character encoding.
XMLScanner(java.net.URL url, java.lang.String encoding) Creates a XMLScanner reading from a URL, using a specified character encoding.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getContext() Returns the XML context in which a syntax error is detected.
protected void	scanAnyContent() Scans the input stream for arbitrary XML content, populating the token stream.
private void	scanAttribute() Scans an attribute-value pair.
private void	scanCloseElement() Scans an XML element closing tag.
private void	scanComment() Scans an XML comment.
private void	scanDeclaration() Scans the opening XML declaration.
private void	scanDoctype() Scans a Doctype declaration.
private void	scanEscapedData() Scans escaped character data inside a CDATA section.
private void	scanInstruction() Scans an XML processing instruction.
private void	scanOpenElement() Scans an XML element opening tag.
private void	scanTextContent() Scans non-markup content as PCDATA text.

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

close, endOfStream, getEncoding, getLineNumber, getText, getToken, scanEntityReference, scanExactly, scanKeyword, scanNameToken, scanQuotedValue, skipSpace

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

Constructor Detail

XMLScanner

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

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

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.

XMLScanner

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

Creates a XMLScanner reading from a URL, using a specified character encoding. Recognised encodings include UTF-8, UTF-16, ISO-8859-1 (Latin-1) and others. Creates a LineNumberReader reading from an InputStreamReader with the given encoding, reading from a basic InputStream created by the URL's openStream() method.

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.

XMLScanner

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

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

Parameters:

stream - the basic InputStream.

encoding - the name of the character encoding.

Throws:

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

XMLScanner

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

Creates a XMLScanner reading from a character Reader, using a specified character encoding. Recognised encodings include UTF-8, UTF-16, ISO-8859-1 (Latin-1) and others. The character encoding must match that used by the Reader, for consistency. Wraps the supplied Reader with a LineNumberReader, to track the location of possible XML syntax errors.

Parameters:

reader - the character Reader.

encoding - the name of the character encoding.

Method Detail

getContext

public java.lang.String getContext()

Returns the XML context in which a syntax error is detected. This is in the form of a path leading to the current node in which the syntax error was detected, in the style of XPath.

Overrides:

getContext in class BasicScanner

Returns:

the context, in the style of XPath.

scanAnyContent

protected void scanAnyContent()
                       throws java.io.UnsupportedEncodingException,
                              java.io.IOException,
                              SyntaxError

Scans the input stream for arbitrary XML content, populating the token stream. Scans one complete XML artifact, whether an opening or closing tag, a declaration or instruction, a doctype, escaped character data, plain text, or an entity reference.

Overrides:

scanAnyContent in class BasicScanner

Throws:

java.io.UnsupportedEncodingException - if a decoding fault occurs.

java.io.IOException - if an input stream error is detected.

SyntaxError - if an XML syntax error is detected.

scanDeclaration

private void scanDeclaration()
                      throws java.io.UnsupportedEncodingException,
                             java.io.IOException,
                             SyntaxError

Scans the opening XML declaration. This is invoked if no previous token has been requested, so the input stream has not yet been read. Reads the lookahead character. If this is not '<', then an encoding error is detected; otherwise processes the declaration. Queues START_DECLARATION, a NAME_TOKEN for the target (which must be "xml" or "XML"), followed by tokens for attributes, and eventually END_DECLARATION.

Throws:

java.io.EOFException - if the input stream contains no data.

java.io.IOException - if an input stream error occurs.

java.io.UnsupportedEncodingException - if a decoding fault occurs.

SyntaxError - if there is whitespace before the XML declaration, or if the XML contains syntax errors.

scanInstruction

private void scanInstruction()
                      throws java.io.IOException,
                             SyntaxError

Scans an XML processing instruction. Scans the target and following data expressed in attribute-format (only). Queues START_INSTRUCTION, then a NAME_TOKEN for the target, followed by tokens for attributes, followed eventually by END_INSTRUCTION.

Throws:

java.io.IOException - if an input stream error is detected.

SyntaxError - if an XML syntax error is detected.

scanDoctype

private void scanDoctype()
                  throws java.io.IOException,
                         SyntaxError

Scans a Doctype declaration. Scans the exact symbol 'DOCTYPE' and the target, followed by the PUBLIC or PRIVATE identifier, followed by one or more quoted values. Optionally scans the internal grammar between '[]' as text. Queues START_DOCTYPE, NAME_TOKEN for the target element, NAME_TOKEN for the public or system identifier, followed by tokens for one or two quoted value-strings, followed optionally by ESCAPE_TEXT, followed by END_DOCTYPE.

Throws:

java.io.IOException - if an input stream error is detected.

java.io.EOFException - if premature end of input is detected.

SyntaxError - if an XML syntax error is detected.

scanComment

private void scanComment()
                  throws java.io.IOException,
                         SyntaxError

Scans an XML comment. Scans the opening bracket "<--" and then arbitrary comment text, until the closing bracket "-->". Within the comment text, the String "--" is illegal. Queues START_COMMENT, ESCAPE_TEXT and END_COMMENT.

Throws:

java.io.IOException - if an input stream error is detected.

java.io.EOFException - if premature end of input is detected.

SyntaxError - if an XML syntax error is detected.

scanOpenElement

private void scanOpenElement()
                      throws java.io.IOException

Scans an XML element opening tag. Scans the element's name token, which may be any legal Unicode identifier apart from the reserved name "xml", then scans an optional list of attributes. If the tag is self-closing, ends the element. Queues START_OPENING, NAME_TOKEN, followed by tokens for the attributes, and eventually one of END_OPENING or END_CLOSING, depending on whether the tag is open, or self-closing.

Throws:

java.io.IOException - if an input stream error is detected.

SyntaxError - if an XML syntax error is detected.

scanCloseElement

private void scanCloseElement()
                       throws java.io.IOException,
                              SyntaxError

Scans an XML element closing tag. Scans the element's name token and checks that this matches the corresponding opening tag on the symbol stack. Queues START_CLOSING, NAME_TOKEN and END_CLOSING.

Throws:

java.io.IOException - if an input stream error is detected.

SyntaxError - if an XML syntax error is detected.

scanAttribute

private void scanAttribute()
                    throws java.io.IOException,
                           SyntaxError

Scans an attribute-value pair. Scans the attribute's name token, skipping any white space surrounding the equals '=' sign, which must be present, then scans a quoted value-string. Queues a NAME_TOKEN, then OPEN_QUOTE followed by one or more occurrences of PRINT_TEXT and ENTITY_REF, followed finally by CLOSE_QUOTE.

Throws:

java.io.IOException - if an input stream error is detected.

SyntaxError - if an XML syntax error is detected.

scanTextContent

private void scanTextContent()
                      throws java.io.IOException,
                             SyntaxError

Scans non-markup content as PCDATA text. Scans for legal textual content, up until the next '<' tag or '&' entity reference. The '>' character is illegal in PCDATA. If the end of input is encountered, assumes that this is the legitimate end of the input data. Special markup characters, such as '<' or '&' must be escaped as XML entity references, if they are to be included in the scanned text. Depending on whether the scanned text contains printing characters or layout whitespace, queues PRINT_TEXT or SPACE_TEXT.

Throws:

java.io.IOException - if an input stream error is detected.

SyntaxError - if an XML syntax error is detected.

scanEscapedData

private void scanEscapedData()
                      throws java.io.IOException,
                             SyntaxError

Scans escaped character data inside a CDATA section. The escaped character data may not contain "]]>" which indicates the end of the CDATA section. Otherwise, the character data may include arbitrary characters and symbols. Queues START_CDATA, followed by ESCAPE_TEXT and END_CDATA.

Throws:

java.io.IOException - if an input stream error is detected.

java.io.EOFException - if premature end of input is detected.

SyntaxError - if an XML syntax error is detected.