uk.ac.sheffield.jast.valid

Class XSDCompiler

java.lang.Object

uk.ac.sheffield.jast.valid.XSDCompiler

public class XSDCompiler
extends java.lang.Object

XSDCompiler is an analyser that compiles a grammar from an XML Schema. An XSDCompiler analyses the definitions provided in an XML Schema and compiles these into a graph of GrammarRules. The XML Schema document will have been read by XMLReader, and its root "schema" Element will be passed to XSDCompiler. The XSDCompiler must decode the document grammar expressed in the XML Schema, which may be presented in several different contrasting styles.

For example, in the "Russian Doll" style, the schemaRoot has one global element definition and all other definitions are local, contained in a nested tree. In the "Salami" style, all element definitions are global at the top level, but their internal type structure uses references to refer to other elements. In the "Venetian Blind" style, there is a single global element definition, with all other elements defined locally; however the types of each element are separately defined in the global namespace. The job of XSDCompiler is to build either a single-rooted tree of grammar rules, or a multiple-rooted graph of shared rules, where the Schema provides more than one possible entry point into the grammar.

The result of processing the schemaRoot is an XML grammar, represented as a graph of GrammarRule objects. XSDCompiler verifies that each GrammarRule is properly defined, such that every element identifier encountered in a production also has a corresponding ElementRule definition; and it verifies that the grammar is fully connected, such that no unreachable ElementRule objects exist.

Version:

2.5

Author:

Anthony J H Simons, Haoxiang Chao

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Map<java.lang.String,AttributeRule>	attributeRules A dictionary of global AttributeRule objects, indexed by XSD attribute name.
private java.util.Map<java.lang.String,ElementRule>	elementRules A dictionary of ElementRule objects, indexed by XSD element name.
private Element	schemaRoot The XML schema root analysed by this XSDCompiler.
private java.util.Map<java.lang.String,Filter>	simpleFilters A dictionary of Filter objects, indexed by XSD simple type name.

Constructor Summary

Constructors

Constructor and Description
XSDCompiler(XMLSchema schema) Creates an XSDCompiler to analyse the given XML Schema.

Method Summary

Modifier and Type	Method and Description
private AttributeRule	analyseAttribute(Element node) Creates an AttributeRule for an XSD attribute node.
private java.util.List<GrammarRule>	analyseAttributeGroupRef(Element node) Creates a list of AttributeRules for an XSD attributeGroup reference.
private AttributeRule	analyseAttributeRef(Element node) Looks up a global XSD attribute reference.
private CompoundRule	analyseComplexContent(Element node) Creates a CompoundRule for an XSD complexContent node.
private java.util.List<GrammarRule>	analyseComplexType(Element node) Creates a List of GrammarRules corresponding to an XSD complex type.
private GrammarRule	analyseCompoundContent(Element node) Creates a GrammarRule for some nested XSD element or compound node.
private CompoundRule	analyseCompoundType(Element node) Creates a CompoundRule for a given XSD sequence, choice, or all node.
private void	analyseDocument(Element node) Analyses the top-level global definitions under the XSD schemaRoot node.
private ElementRule	analyseElement(Element node) Creates an ElementRule for an XSD element node.
private ElementRule	analyseElementRef(Element node) Looks up a global XSD element reference.
private Filter	analyseEnumeration(Element node) Creates a RangeFilter for an XSD restriction which contains XSD enumeration children nodes.
private CompoundRule	analyseGroupRef(Element node) Creates a CompoundRule for an XSD group reference.
private Filter	analyseListType(Element node) Determines what filter to return for an XSD list or XSD union type.
private GrammarRule	analyseMultiplicity(Element node) Secret method that optionally creates an IterationRule if one is needed.
private Filter	analysePattern(Element node) Creates a PatternFilter for an XSD restriction which contains an XSD pattern child node.
private Filter	analyseRestriction(Element node) Creates a RestrictFilter or a WidthFilter for any other kind of XSD restriction.
private java.util.List<GrammarRule>	analyseSimpleContent(Element node) Creates a list of GrammarRules for an XSD simpleContent node.
private Filter	analyseSimpleType(Element node) Determines the Filter to use for any XSD simple type.
private java.lang.String	getContext(Content node) Returns the context of an error message as an XPath-style string.
private Element	lookup(java.lang.String elementKind, java.lang.String nameValue) Searches the schemaRoot for an Element of a given kind, with a given value for its name attribute.
private int	parseOccurrence(java.lang.String value) Converts an occurrence attribute value into an integer multiplicity.
java.util.Map<java.lang.String,ElementRule>	readGrammar() Analyses the grammar specified by the XML Schema to build a grammar rooted in one or more ElementRules.
private void	semanticError(java.lang.String message, Element node) Throws a SemanticError giving full diagnostic information.

Methods inherited from class java.lang.Object

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

Field Detail

schemaRoot

private Element schemaRoot

The XML schema root analysed by this XSDCompiler. This is the root Element of the XMLSchema, which was supplied at construction.

elementRules

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

A dictionary of ElementRule objects, indexed by XSD element name. All ElementRule objects must be indexed, since they may be defined and used out of order.

attributeRules

private java.util.Map<java.lang.String,AttributeRule> attributeRules

A dictionary of global AttributeRule objects, indexed by XSD attribute name. Only globally-defined AttributeRules are placed here.

simpleFilters

private java.util.Map<java.lang.String,Filter> simpleFilters

A dictionary of Filter objects, indexed by XSD simple type name. Only globally-defined Filters are placed here.

Constructor Detail

XSDCompiler

public XSDCompiler(XMLSchema schema)

Creates an XSDCompiler to analyse the given XML Schema. Stores the XML Schema and also determines the root Element of the grammar.

Parameters:

schema - the XML Schema.

Method Detail

readGrammar

public java.util.Map<java.lang.String,ElementRule> readGrammar()
                                                        throws SemanticError

Analyses the grammar specified by the XML Schema to build a grammar rooted in one or more ElementRules.

Returns:

a map of top-level ElementRules, indexed by name.

Throws:

SemanticError - if the XSD contains semantic errors.

semanticError

private void semanticError(java.lang.String message,
                           Element node)
                    throws SemanticError

Throws a SemanticError giving full diagnostic information.

Parameters:

message - the error message.

node - the erroneous schemaRoot Element.

Throws:

SemanticError - deliberately.

getContext

private java.lang.String getContext(Content node)

Returns the context of an error message as an XPath-style string.

Parameters:

node - the context of an error.

Returns:

an XPath style String.

lookup

private Element lookup(java.lang.String elementKind,
                       java.lang.String nameValue)

Searches the schemaRoot for an Element of a given kind, with a given value for its name attribute. Creates a compound filter for the Element, using a NameFilter to select the element kind and a PropertyFilter to select the attribute. The PropertyFilter contains a NameFilter for the "name" attribute, and a ValueFilter for the specific value of this attribute.

Parameters:

elementKind - the name of the kind of Element.

nameValue - the value of the Element's name.

Returns:

the first matching Element from the schemaRoot.

analyseDocument

private void analyseDocument(Element node)

Analyses the top-level global definitions under the XSD schemaRoot node. This is the workhorse method that drives the analysis of the whole schemaRoot. It processes global data in the order: simple types, then attributes (which can have simple types), and finally elements (which can have simple or complex types). The only nodes requiring forward declaration are XSD element nodes and references, and XSD attribute references. XSD complexType, group and attributeGroup definitions are not pre-processed, but are re-analysed on demand. This is so that each ElementRule eventually builds a separate grammar tree. Grammar trees may not be shared among multiple ElementRules.

Parameters:

node - the XSD schemaRoot node.

analyseElementRef

private ElementRule analyseElementRef(Element node)

Looks up a global XSD element reference. Must find or create the ElementRule, whether or not the XSD element has been seen before.

Parameters:

node - the XSD element node.

Returns:

an ElementRule.

analyseElement

private ElementRule analyseElement(Element node)

Creates an ElementRule for an XSD element node. Expects the element's type to be either a simple type or a complex type, which may or may not have yet been defined. If the XSD element defines its type locally, installs this definition, otherwise leaves an entry in the dictionary of unresolved types.

Parameters:

node - the XSD element node.

Returns:

an ElementRule.

analyseAttributeRef

private AttributeRule analyseAttributeRef(Element node)

Looks up a global XSD attribute reference. Must find or create the AttributeRule, whether or not the attribute has been seen before.

Parameters:

node - the XSD attribute node.

Returns:

an AttributeRule.

analyseAttribute

private AttributeRule analyseAttribute(Element node)

Creates an AttributeRule for an XSD attribute node. Expects the attribute's type to be either an existing user-defined simple type, or a built-in XSD type. The type may be defined locally, or must have already been defined globally. If the attribute is required, sets this flag in the rule.

Parameters:

node - the XSD attribute node.

Returns:

an AttributeRule.

analyseComplexType

private java.util.List<GrammarRule> analyseComplexType(Element node)

Creates a List of GrammarRules corresponding to an XSD complex type. The children of XSD complexType may be any XSD node from: attribute, attributeGroup, simpleContent, complexContent, or one of the compound groups sequence, choice or all. These each return different kinds of GrammarRules. Whereas many AttributeRules are permissible, only one other GrammarRule is allowed in the result.

Parameters:

node - the XSD complexType node.

Returns:

a list of GrammarRules.

analyseCompoundType

private CompoundRule analyseCompoundType(Element node)

Creates a CompoundRule for a given XSD sequence, choice, or all node. Recursively processes the children of the XSD sequence, etc. node and attaches these children to the returned CompoundRule.

Parameters:

node - the XSD sequence, choice or all node.

Returns:

a CompoundRule with its children attached.

analyseCompoundContent

private GrammarRule analyseCompoundContent(Element node)

Creates a GrammarRule for some nested XSD element or compound node. The node is either a local XSD element, group ref, sequence or choice node, which has been found as part of the body of another compound type. The node may also have some multiplicity specification using minOccurs or maxOccurs: if so, then the nested rule for the node is wrapped in a further IterationRule.

Parameters:

node - an XSD element, group or compound specifier node.

Returns:

a CompoundRule or an ElementRule.

analyseGroupRef

private CompoundRule analyseGroupRef(Element node)

Creates a CompoundRule for an XSD group reference. Accesses the group referenced by this node, and creates a new CompoundRule for the child compound under the group node. This must always be a brand-new CompoundRule, since it will refer to a unique ElementRule ancestor.

Parameters:

node - the XSD group reference node.

Returns:

a CompoundRule.

analyseAttributeGroupRef

private java.util.List<GrammarRule> analyseAttributeGroupRef(Element node)

Creates a list of AttributeRules for an XSD attributeGroup reference. Accesses the attribute group referenced by this node, and creates a new list of AttributeRules. These could be shared (in future), since there is no need for AttributeRules to have unique parents.

Parameters:

node - the XSD attributeGroup reference node.

Returns:

a list of AttributeRules.

analyseSimpleContent

private java.util.List<GrammarRule> analyseSimpleContent(Element node)

Creates a list of GrammarRules for an XSD simpleContent node. This has one child node, either an XSD extension or restriction. For an extension, we expect to return a list of AttributeRules, but for a restriction, we expect to return a singleton list containing a TextContentRule that has been restricted with a Filter.

Parameters:

node - the XSD simpleContent node.

Returns:

a list of GrammarRules.

analyseComplexContent

private CompoundRule analyseComplexContent(Element node)

Creates a CompoundRule for an XSD complexContent node. This node may have a single XSD extension or restriction child node. For an extension, we extend the definition of some base type. For a restriction, we treat the restriction as the replacement type.

Parameters:

node - the XSD complexContent node.

Returns:

a CompoundRule.

analyseSimpleType

private Filter analyseSimpleType(Element node)

Determines the Filter to use for any XSD simple type. There are many different options. The most common kind of simple type definition contains a single XSD restriction child, which may define either an enumeration, a pattern or some other kind of restriction. These are handled in separate subroutines. Less common kinds of definition are XSD list, or XSD union types, which are handled in another subroutine.

Parameters:

node - the XSD simpleType node.

Returns:

a Filter which accepts this type.

analyseListType

private Filter analyseListType(Element node)
                        throws SemanticError

Determines what filter to return for an XSD list or XSD union type. For an XSD list node, creates a TypeFilter that will accept a list of at least one of the basic element type, which must be some XSD simple type (not another user-defined type). For an XSD union node, creates an OrFilter holding a disjunction of TypeFilters for each basic type, which must be of some XSD simple type (not another user-defined type).

Parameters:

node - the XSD list, or XSD union node.

Returns:

a TypeFilter, or an OrFilter.

Throws:

SemanticError - if the component types are not basic types.

analyseEnumeration

private Filter analyseEnumeration(Element node)

Creates a RangeFilter for an XSD restriction which contains XSD enumeration children nodes. Raises a SemanticError if the XSD restriction contains nodes of any other type.

Parameters:

node - the XSD restriction node.

Returns:

a RangeFilter.

analysePattern

private Filter analysePattern(Element node)

Creates a PatternFilter for an XSD restriction which contains an XSD pattern child node. Raises a SemanticError if the XSD restriction contains nodes of any other type.

Parameters:

node - the XSD restriction node.

Returns:

a PatternFilter.

analyseRestriction

private Filter analyseRestriction(Element node)

Creates a RestrictFilter or a WidthFilter for any other kind of XSD restriction. We have already handled XSD restrictions which contain XSD enumeration or XSD pattern nodes. This method handles the remaining cases, which limit the range, or limit the field width. Since several filters may be combined, the algorithm starts with a vanilla filter and then combines this using logical-AND with other filters limiting the upper or lower ranges.

Parameters:

node - the XSD restriction node

Returns:

a RestrictFilter or a WidthFilter

analyseMultiplicity

private GrammarRule analyseMultiplicity(Element node)
                                 throws SemanticError

Secret method that optionally creates an IterationRule if one is needed. Performs supplementary analysis of any XSD node to find out if it has any minimum or maximum occurrence constraints. If so, creates an IterationRule to wrap the rule created for the XSD node. If the node contains no occurrence constraints, or if these specify exactly one occurrence, returns null. Raises a SemanticError for values that cannot be parsed, or that do not form a valid iteration range.

Parameters:

node - an XSD grammar node.

Returns:

an IterationRule, or null if no iteration is required.

Throws:

SemanticError - if the occurrence constraint is invalid.

parseOccurrence

private int parseOccurrence(java.lang.String value)
                     throws java.lang.NumberFormatException

Converts an occurrence attribute value into an integer multiplicity. If the value is null, the property is undefined and so the default multiplicity of 1 is returned. If the value is "unbounded", returns the largest integer. Otherwise, converts the value to an integer.

Parameters:

value - the value of 'minOccurs' or 'maxOccurs'.

Returns:

a multiplicity count.

Throws:

java.lang.NumberFormatException - if the String cannot be converted into a number.