uk.ac.sheffield.jast.valid

Class GrammarRule

java.lang.Object

uk.ac.sheffield.jast.valid.GrammarRule

Direct Known Subclasses:

AnyElementRule, CompoundRule, ElementRule, SimpleRule

public abstract class GrammarRule
extends java.lang.Object

GrammarRule is the abstract ancestor of all kinds of XML grammar rules. GrammarRule and its subclasses model the BNF-style grammar describing the allowed sequencing, selection and iteration of Element nodes in an XML syntax tree, and also the specification of all required, or permitted, Attribute nodes. GrammarRules are connected in a hierarchy, which models the desired BNF grammar exactly. The top GrammarRule should always be an ElementRule. This rule validates the root Element node of the XML tree, and, through its rule children, recursively validates the entire document.

An XML document is validated in one of two ways. Clients may invoke the top ElementRule's method accept(root) on the root Element of an XML syntax tree. This returns true, if the tree is valid with respect to the rules, or false if the tree is invalid. Alternatively, clients may invoke validate(root) on the root Element, which succeeds silently if the tree is valid, or raises a SemanticError exception giving the errorReason for the mismatch, if the tree is invalid.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private static Content	errorContext Stores the last context where mismatch occurred.
private static java.lang.String	errorReason Stores the last global reason for the mismatch.
protected java.lang.String	identifier The identifying label of this GrammarRule.
protected GrammarRule	parent The parent GrammarRule for this GrammarRule.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	GrammarRule(java.lang.String identifier) Creates a GrammarRule, with the given identifier.

Method Summary

Modifier and Type	Method and Description
boolean	accept(Element node) Reports whether this GrammarRule accepts the given XML Element node.
void	addChildRule(GrammarRule rule) Adds a child rule to this GrammarRule.
protected void	clearError() Secret method to clear the latest mismatch error.
protected int	getChildIndex() Returns the child index at which the next GrammarRule starts matching.
private java.lang.String	getContext() Returns the XML errorContext in which a semantic error is detected.
java.lang.String	getIdentifier() Returns the identifying label of this GrammarRule.
java.util.List<GrammarRule>	getRuleChildren() Returns the immediate GrammarRule children of this GrammarRule.
boolean	isAttributeRule() Reports whether this GrammarRule is an attribute rule.
boolean	isElementRule() Reports whether this GrammarRule is an element rule.
boolean	isNestingRule() Reports whether this GrammarRule is allowed to be nested inside other CompoundRule rules.
void	restrict(Filter filter) Adds a value, range or type restriction to this GrammarRule.
protected void	setChildIndex(int index) Sets the child index at which the next GrammarRule starts matching.
protected void	setError(java.lang.String reason, Content context) Secret method to record the latest mismatch error.
protected void	setParent(GrammarRule rule) Secret method to install the parent GrammarRule of this GrammarRule.
void	validate(Element root) Validates a given XML document tree starting at an Element root node.

Methods inherited from class java.lang.Object

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

Field Detail

errorContext

private static Content errorContext

Stores the last context where mismatch occurred.

errorReason

private static java.lang.String errorReason

Stores the last global reason for the mismatch.

identifier

protected java.lang.String identifier

The identifying label of this GrammarRule. Rules are labelled after their Element or Attribute; or after their grammar production.

parent

protected GrammarRule parent

The parent GrammarRule for this GrammarRule. All GrammarRules must have a chain of back references via their parents to the dominating ElementRule, which defines the scope of the children nodes to be validated by this rule.

Constructor Detail

GrammarRule

protected GrammarRule(java.lang.String identifier)

Creates a GrammarRule, with the given identifier.

Parameters:

identifier - the identifier of this GrammarRule.

Method Detail

getContext

private java.lang.String getContext()

Returns the XML errorContext in which a semantic error is detected. This is in the form of a path leading to the errorContext in which the semantic error was detected, in the style of XPath.

Returns:

the errorContext, in the style of XPath.

setError

protected void setError(java.lang.String reason,
                        Content context)

Secret method to record the latest mismatch error. If no previous error has been set, records the context of the error and the reason; otherwise does nothing. This allows the most nested failure to be reported when the rule-stack unwinds to the top level.

Parameters:

reason - a reason for the mismatch.

context - the node at which matching failed.

clearError

protected void clearError()

Secret method to clear the latest mismatch error. This allows for backtracking, in which alternative productions may clear the errors set by previous productions, when the alternative subsequently succeeds.

getChildIndex

protected int getChildIndex()

Returns the child index at which the next GrammarRule starts matching. All rules perform matching in the context of a sequence of Element children of some parent Element node. This method reports where in this sequence the next GrammarRule should start matching. Fetches the child index from the dominating ElementRule.

Returns:

the child index.

setChildIndex

protected void setChildIndex(int index)

Sets the child index at which the next GrammarRule starts matching. All rules perform matching in the context of a sequence of Element children of some parent Element node. This method allows a rule to set the index of the last-matched child in this sequence. Sets the child index in the dominating ElementRule.

Parameters:

index - the child index.

setParent

protected void setParent(GrammarRule rule)

Secret method to install the parent GrammarRule of this GrammarRule. Each GrammarRule must maintain a back reference to its parent rule in a chain leading to the dominating ElementRule. Sets the parent back reference of this rule to the given GrammarRule, unless the back-reference has already been set, in which case it is left unchanged, and this method has no effect. Every rule may have at most one parent rule.

Conceptually, all the subsidiary GrammarRules in a production form a unique tree under their dominating ElementRule. ElementRule rules break this principle, since they may be added to more than one compound rule, and so are shared in a graph. However, it is of no consequence that ElementRule retains only the first of its parents, since its back-reference is never used (the matching algorithm only tracks back to the nearest dominating ElementRule).

Parameters:

rule - the parent GrammarRule of this rule.

accept

public boolean accept(Element node)

Reports whether this GrammarRule accepts the given XML Element node. This method is invoked when checking that an XML Element conforms to a given grammar specification. By default, returns false. Subclasses override this method and may accept or reject the node.

Parameters:

node - an XML Element node, possibly the root of an XML tree.

Returns:

true, if the node and its subtree matches this rule.

validate

public void validate(Element root)
              throws SemanticError

Validates a given XML document tree starting at an Element root node. This method invokes accept(node) and terminates silently if validation succeeds. Otherwise, it raises a SemanticError with a message describing the nature and errorContext of the mismatch.

Parameters:

root - the root Element of a Document.

Throws:

SemanticError - if validation fails.

addChildRule

public void addChildRule(GrammarRule rule)

Adds a child rule to this GrammarRule. Some kinds of GrammarRule may add one, or several child rules, whereas others have no children. By default, this method does nothing.

Parameters:

rule - the child rule to add.

getRuleChildren

public java.util.List<GrammarRule> getRuleChildren()

Returns the immediate GrammarRule children of this GrammarRule. Some kinds of GrammarRule may contain one or more children, representing the grammar production described by this GrammarRule. By default, returns the empty list of GrammarRules.

Returns:

the GrammarRule children of this rule.

getIdentifier

public java.lang.String getIdentifier()

Returns the identifying label of this GrammarRule. Rules are labelled after the Element or Attribute identifier which they match; or after the type name of their grammar production.

Returns:

the identifying label of this GrammarRule.

isAttributeRule

public boolean isAttributeRule()

Reports whether this GrammarRule is an attribute rule. By default, this is false. AttributeRule overrides this to return true. This method is used to filter rule children that are added to ElementRule, so that AttributeRule rules are stored separately from other kinds of GrammarRule production rule.

Returns:

true, if this GrammarRule is an AttributeRule.

isElementRule

public boolean isElementRule()

Reports whether this GrammarRule is an element rule. By default, this is false. ElementRule overrides this to return true. This method is used to filter rule children that are added to certain GrammarRules. ElementRule may not add an ElementRule child directly; UnorderedRule and MixedContentRule may only add ElementRule children.

Returns:

true, if this GrammarRule is an ElementRule.

isNestingRule

public boolean isNestingRule()

Reports whether this GrammarRule is allowed to be nested inside other CompoundRule rules. By default, this is true. SimpleRule overrides this to return false. This method is used to prevent certain rules, including EmptyContentRule, AnyContentRule, TextContentRule and AttributeRule, from being nested inside CompoundRules.

Returns:

true, if this GrammarRule is allowed to be nested.

restrict

public void restrict(Filter filter)

Adds a value, range or type restriction to this GrammarRule. Some kinds of rule, such as ElementRule, AttributeRule, TextContentRule and MixedContentRule, may add restrictions. By default, this method does nothing.

Parameters:

filter - the restriction to add.