uk.ac.sheffield.jast.valid

Class DTDReader

java.lang.Object

uk.ac.sheffield.jast.Logging

uk.ac.sheffield.jast.BasicReader

uk.ac.sheffield.jast.valid.DTDReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class DTDReader
extends BasicReader

DTDReader is a pull-parser that compiles a DTD grammar rule tree. DTDReader is an efficient recursive descent pull-parser that compiles a collection of GrammarRules from an external DTD grammar file, or from the internal grammar subset stored in a Doctype node. DTDReader creates a grammar rule tree rooted in an ElementRule, the top production of the DTD grammar. The rule body consists of SequenceRule, SelectionRule, or IterationRule compound productions; or TextContentRule, AnyContentRule, or EmptyContentRule simple productions, along with other GrammarRules provided in the sub-package uk.ac.sheffield.jast.valid.

As well as parsing ELEMENT and ATTLIST declarations, DTDReader also parses ENTITY declarations that refer to additional character entities, defining special encoded characters, or defining string entities, defining special boilerplate text to expand in the main XML document. These entities are added to the Lexicon supplied by another reader or builder that requested this DTDReader. This allows the other reader or builder to read a main XML document containing these additional entity references.

DTDReader uses the low-level token scanner DTDScanner to supply it with integer tokens, members of the Tokens class, that represent different recognised DTD 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 the top ElementRule, which is typically stored in a Doctype node. It is also possible to access the grammar as a list of ElementRule productions. This is used to transfer the external grammar subset from one DTDReader to another, when the latter wishes to merge this with the internal grammar subset, which it is about to read. DTDReader 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
private java.util.Map<java.lang.String,ElementRule>	dictionary The dictionary mapping from Element names to the ElementRule rules defining the elements concerned.
private static java.util.Set<java.lang.String>	legalTypes Secret set of legal types for ATTLIST attributes.

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

lastToken, lexicon, scanner, validation

Constructor Summary

Constructors

Constructor and Description
DTDReader(java.io.File file, Lexicon lexicon, java.lang.String encoding) Creates a DTDReader to read an external grammar from a file, updating a Lexicon supplied by some other XML or AST reader.
DTDReader(java.io.File file, java.lang.String encoding) Creates a DTDReader to read an external grammar from a file, updating an internal Lexicon.
DTDReader(java.io.Reader reader, Lexicon lexicon, java.lang.String encoding) Creates a DTDReader to read an internal grammar from a character Reader, updating a Lexicon supplied by some other XML or AST reader.
DTDReader(java.net.URL url, Lexicon lexicon, java.lang.String encoding) Creates a DTDReader to read an external grammar from a URL, updating a Lexicon supplied by some other XML or AST reader.
DTDReader(java.net.URL url, java.lang.String encoding) Creates a DTDReader to read an external grammar from a URL, updating an internal Lexicon.

Method Summary

Modifier and Type	Method and Description
private ElementRule	getGrammar() Returns a tree of grammar rules, rooted in the top ElementRule that was parsed.
java.util.List<ElementRule>	getProductions() Returns the list of ElementRule grammar productions recorded by this DTDReader.
private void	parseAnyRule() Parses any single DTD grammar rule.
private void	parseAttlistRule() Parses an ATTLIST definition.
private void	parseComment() Parses an XML comment.
private GrammarRule	parseCompoundBody() Parses a compound grammar rule body term.
private GrammarRule	parseElementBody() Parses an element grammar rule body term.
private void	parseElementRule() Parses an ELEMENT definition.
private void	parseEntityRule() Parses an ENTITY definition.
private GrammarRule	parseMixedBody() Parses a mixed-content compound grammar rule body.
private GrammarRule	parseMultiplicity(GrammarRule rule) Parses an optional multiplicity mark adjoining a grammar rule body term.
private java.lang.String	readExternalEntity(java.lang.String uri) Read the value of an external entity from a URI.
ElementRule	readGrammar() Parses the DTD grammar, compiling a tree of GrammarRules and updating a Lexicon with new entity definitions.
void	setProductions(java.util.List<ElementRule> productions) Installs an ordered list of ElementRule grammar productions in this DTDReader.

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

legalTypes

private static final java.util.Set<java.lang.String> legalTypes

Secret set of legal types for ATTLIST attributes. NOTATION types must be followed by an enum range of the allowed types.

dictionary

private java.util.Map<java.lang.String,ElementRule> dictionary

The dictionary mapping from Element names to the ElementRule rules defining the elements concerned. This DTDReader indexes rules in a dictionary, so that it may map occurrences of the same Element name to the same ElementRule. The first entry added to this map is assumed to be the root ElementRule.

Constructor Detail

DTDReader

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

Creates a DTDReader to read an external grammar from a file, updating an internal Lexicon. This supports processing an external DTD file without reference to any current XML DOM-tree. After processing the file, the created Lexicon and the parsed GrammarRules may be accessed.

Parameters:

file - the DTD file, from the local filesystem.

encoding - the expected character encoding, typically "UTF-8".

Throws:

java.io.UnsupportedEncodingException - if the DTD file's character encoding is not supported.

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

DTDReader

public DTDReader(java.io.File file,
                 Lexicon lexicon,
                 java.lang.String encoding)
          throws java.io.UnsupportedEncodingException,
                 java.io.FileNotFoundException

Creates a DTDReader to read an external grammar from a file, updating a Lexicon supplied by some other XML or AST reader. This supports processing an external DTD file that was referenced by some Doctype or Metadata, during the processing of the main XML file. The Lexicon is supplied by the other XML or AST reader, and will be updated with new entity definitions before the main XML file is processed.

Parameters:

file - the DTD file, from the local filesystem.

lexicon - the Lexicon from the XML or AST reader.

encoding - the expected character encoding, typically "UTF-8".

Throws:

java.io.UnsupportedEncodingException - if the DTD file's character encoding is not supported.

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

DTDReader

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

Creates a DTDReader to read an external grammar from a URL, updating an internal Lexicon. This supports processing an external DTD file, obtained via a URL, without reference to any current XML DOM-tree. After reading the DTD file, the created Lexicon and the parsed GrammarRules may be accessed.

Parameters:

url - the URL describing a path to a DTD file.

encoding - the expected character encoding is "ISO-8859-1".

Throws:

java.io.UnsupportedEncodingException - if the DTD file's character encoding is not supported.

java.io.IOException - if the URL is malformed or cannot be opened as a file.

DTDReader

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

Creates a DTDReader to read an external grammar from a URL, updating a Lexicon supplied by some other XML or AST reader. This supports processing an external DTD URL that was referenced by some Doctype or Metadata, during the processing of the main XML file. The Lexicon is supplied by the other XML or AST reader, and will be updated with new entity definitions before the main XML file is processed.

Parameters:

url - the URL describing a path to a DTD file.

lexicon - the Lexicon from the XML or AST reader.

encoding - the expected character encoding is "ISO-8859-1".

Throws:

java.io.UnsupportedEncodingException - if the DTD file's character encoding is not supported.

java.io.IOException - if the URL is malformed or cannot be opened as a file.

DTDReader

public DTDReader(java.io.Reader reader,
                 Lexicon lexicon,
                 java.lang.String encoding)
          throws java.io.UnsupportedEncodingException

Creates a DTDReader to read an internal grammar from a character Reader, updating a Lexicon supplied by some other XML or AST reader. This supports processing an internal grammar subset previously stored as a text String in some Doctype or Metadata, which can be scanned again using a StringReader. The Lexicon is supplied by the other XML or AST reader, and will be updated with new entity definitions before the main XML file is processed.

Parameters:

reader - a StringReader scanning the internal grammar subset.

lexicon - the Lexicon from the XML or AST reader.

encoding - the expected character encoding, typically "UTF-8".

Throws:

java.io.UnsupportedEncodingException - if the DTD file's character encoding is not supported.

Method Detail

readGrammar

public ElementRule readGrammar()
                        throws java.io.IOException,
                               SyntaxError,
                               SemanticError

Parses the DTD grammar, compiling a tree of GrammarRules and updating a Lexicon with new entity definitions. Analyses the DTD grammar, whether internal or external, and creates a dictionary of ElementRules linked to other kinds of GrammarRule, representing the production of the ElementRule. Attaches AttributeRules to each ElementRule. Upon termination, checks for missing ElementRule definitions, and checks that the grammar is fully connected. Returns the first ElementRule, assumed to be the top rule of the grammar tree.

Returns:

the top ElementRule.

Throws:

java.io.IOException - if the DTD grammar cannot be read.

SyntaxError - if the DTD syntax is faulty.

SemanticError - if the grammar is not complete.

getGrammar

private ElementRule getGrammar()

Returns a tree of grammar rules, rooted in the top ElementRule that was parsed. If the parsed DTD grammar was not fully-connected from the top ElementRule, the returned tree will be a partial grammar and may not contain every ElementRule encountered during parsing.

Returns:

the top ElementRule of the grammar.

getProductions

public java.util.List<ElementRule> getProductions()

Returns the list of ElementRule grammar productions recorded by this DTDReader. This will return all ElementRules, even if the grammar is not fully-connected. This method is used to transfer a partial DTD grammar out of this DTDReader. Typically, the external grammar subset is accessed this way by another DTDReader, which supplements it by reading the internal grammar subset.

Returns:

the list of ElementRule productions.

setProductions

public void setProductions(java.util.List<ElementRule> productions)

Installs an ordered list of ElementRule grammar productions in this DTDReader. If this DTDReader has not yet parsed a DTD, the first ElementRule in the list of productions will become the top rule of the grammar. This method is used to transfer a partial DTD grammar into this DTDReader. Typically, the external grammar subset from another DTDReader is installed in this way, before parsing the internal grammar subset. Grammar rules that are added later, or parsed later, take precedence over those parsed earlier.

Parameters:

productions - a list of ElementRule productions.

parseAnyRule

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

Parses any single DTD grammar rule.

Throws:

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

SyntaxError - if the DTD syntax is faulty.

parseComment

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

Parses an XML comment. Ignores the comment.

Throws:

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

SyntaxError - if the XML syntax is faulty.

parseEntityRule

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

Parses an ENTITY definition. Reads the acronym for the entity reference and the expansion to store against it in the Lexicon. If the entity is external, uses the SYSTEM identifier to locate a file to read the value of the expansion. Adds a new entity reference to the Lexicon.

Throws:

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

SyntaxError - if the DTD syntax is faulty.

parseAttlistRule

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

Parses an ATTLIST definition. Reads the element ID and retrieves the corresponding ElementRule from the dictionary, creating the rule if none exists, and adds one or more AttributeRules to this ElementRule. For each AttributeRule, determines whether the attribute is compulsory or optional, adds a Filter for the type or the expected range, and if the value is fixed, adds a ValueFilter. Later attribute definitions will override earlier definitions of the same named attribute in the same element (to support internal and external grammar subsets).

Throws:

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

SyntaxError - if the XML syntax is faulty.

parseElementRule

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

Parses an ELEMENT definition. Reads the element ID and retrieves the corresponding ElementRule from the dictionary, creating the rule if none exists. Expects the grammar either to be a compound, surrounded by parentheses, or one of the keywords EMPTY or ANY. If the grammar is compound, delegates to another method to parse the compound rule and installs this as the grammar of the ElementRule. If the keyword is ANY, installs an AnyContentRule, or if the keyword is EMPTY, installs an EmptyContentRule as the grammar of the ElementRule.

Throws:

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

SyntaxError - if the XML syntax is faulty.

parseCompoundBody

private GrammarRule parseCompoundBody()
                               throws java.io.IOException,
                                      SyntaxError

Parses a compound grammar rule body term. Parses a series of terms enclosed in parentheses. Sequence terms are separated by commas, while selection terms are separated by vertical bars. The terms may be nested compound terms, or simple element terms. The compound expression may be followed by a multiplicity marker, indicating an iterated term.

Returns:

one of a SequenceRule, SelectionRule or IterationRule.

Throws:

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

SyntaxError - if the XML syntax is faulty.

parseMixedBody

private GrammarRule parseMixedBody()
                            throws java.io.IOException,
                                   SyntaxError

Parses a mixed-content compound grammar rule body. The first term must be a PCDATA term. If this is the only term, returns a simple TextContentRule. Otherwise, expects the remaining terms to be Element terms, separated by '|' and for the compound body to have a '*' zero-to-many multiplicity marker; and returns a MixedContentRule.

Returns:

a TextContentRule or a MixedContentRule.

Throws:

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

SyntaxError - if the XML syntax is faulty.

parseElementBody

private GrammarRule parseElementBody()
                              throws java.io.IOException,
                                     SyntaxError

Parses an element grammar rule body term. Reads the element ID and retrieves the corresponding ElementRule from the dictionary, creating the rule if none exists. If the element definition is followed by a multiplicity mark, wraps the ElementRule with an IterationRule.

Returns:

an ElementRule or an IterationRule.

Throws:

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

SyntaxError - if the XML syntax is faulty.

parseMultiplicity

private GrammarRule parseMultiplicity(GrammarRule rule)
                               throws java.io.IOException,
                                      SyntaxError

Parses an optional multiplicity mark adjoining a grammar rule body term. If the next token indicates a multiplicity, returns an IterationRule wrapping the argument rule. Otherwise, returns the argument rule unchanged.

Parameters:

rule - a GrammarRule.

Returns:

an IterationRule, or the GrammarRule.

Throws:

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

SyntaxError - if the XML syntax is faulty.

readExternalEntity

private java.lang.String readExternalEntity(java.lang.String uri)
                                     throws java.io.IOException

Read the value of an external entity from a URI. After performing some security checks, attempts to open the file or URL referenced by the URI string. The contents of the file are converted to a String, which is returned as the expansion for an entity reference. Opens all file and URL streams using "ISO-5589-1" since it is likely that strange characters will be required.

The security risks associated with external entities are well known. They can include seeking to access privileged files on the host machine (password or startup files), or denial-of-service attacks that open file resources and do not release them. The security checks in place require entities to be stored in simple ".txt" text files; and file-reading times out after one second.

Parameters:

uri - the URI of the external entity's expansion.

Returns:

arbitrary String data.

Throws:

java.io.IOException - if the external file cannot be read.