uk.ac.sheffield.jast.xml

Class XMLSchema

java.lang.Object

uk.ac.sheffield.jast.xml.Content

uk.ac.sheffield.jast.xml.Document

uk.ac.sheffield.jast.xml.XMLSchema

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Iterable<Content>

public class XMLSchema
extends Document

XMLSchema is a kind of document denoting an XML Schema Definition (XSD). XMLSchema is a specialised subclass of Document, representing an XML Schema Definition (XSD). This kind of document declares a grammar that can be used to validate one or more XML Documents that are expected to conform to the grammar. XMLSchema imposes constraints on what contents may be added; and it offers an API for validating other XML Documents. After compiling the grammar, it is possible to call accept(document), which returns true if the document is valid, and false otherwise;, or to call validate(document), which succeeds silently, but raises a SemanticError exception if the document is invalid (fails to conform to the grammar).

The internal constraints imposed by XMSchema are designed to ensure that the root Element is named "schema" and that it declares itself part of the W3C XML Schema namespace. It may use the prefixes "xs:" or "xsd:" and declares whether these are to be used by default in all Elements, or Attributes, in the schema document. It ensures that any declared target namespace matches the default namespace. It also ensures that every top-level definition in the schema has a name. The XMLSchema class is so-named with the "XML-" prefix, to allow for other kinds of schema to be added in future, such as RelaxNG.

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>	grammars The possibly-multiple roots of the grammar trees represented by this XMLSchema.
private static Doctype	schemaDoctype The non-normative W3C Doctype specification for an XML schema.

Fields inherited from class uk.ac.sheffield.jast.xml.Content

ATTRIBUTE, COMMENT, DATA, DECLARATION, DOCTYPE, DOCUMENT, ELEMENT, INSTRUCTION, TEXT, UNDEFINED

Constructor Summary

Constructors

Constructor and Description
XMLSchema() Creates a default empty XMLSchema with the standard XML Declaration.
XMLSchema(Document document) Creates an XMLSchema from an existing Document.

Method Summary

Modifier and Type	Method and Description
boolean	accept(Document document) Reports whether this XMLSchema accepts a given Document as valid.
boolean	accept(Element element) Reports whether this XMLSchema accepts a root Element as valid.
private void	addRootAttributes(ElementRule rule) Adds extra permissible AttributeRules to each top-level ElementRule.
private void	checkElementNames(Element root) Checks the names of the elements in this schema.
private void	checkNamespaces(Element root) Checks this XMLSchema for valid use of XML namespaces.
XMLSchema	clone() Clones this XMLSchema node.
void	compileGrammar() Compiles the grammar represented by this XMLSchema.
private void	error(java.lang.String message) Raises a SemanticError with this XMLSchema as the context.
ElementRule	getGrammar(java.lang.String identifier) Accesses the top ElementRule for a named Element whose grammar is defined by this XMLSchema.
XMLSchema	setDeclaration(Declaration declaration) Sets the XML declaration associated with this XMLSchema.
XMLSchema	setDoctype(Doctype doctype) Sets the optional XML Doctype associated with this XMLSchema.
XMLSchema	setEncoding(java.lang.String encoding) Sets the character encoding associated with this Document.
XMLSchema	setRootElement(Element root) Sets the root Element of this XMLSchema.
XMLSchema	setVersion(java.lang.String version) Sets the XML version associated with this Document.
void	validate(Document document) Validates a given Document, raising a SemanticError if it is invalid.
void	validate(Element element) Validates a root Element, raising a SemanticError if it is invalid.

Methods inherited from class uk.ac.sheffield.jast.xml.Document

addContent, getContents, getDeclaration, getDoctype, getEncoding, getRootElement, getType, getVersion, hasContents, isStandalone, isWellFormed, removeContent, setParent

Methods inherited from class uk.ac.sheffield.jast.xml.Content

addAttribute, addContent, descendants, descendants, detach, getAttributes, getComment, getContent, getContent, getContent, getContents, getDocument, getIdentifier, getParent, getText, iterator, iterator, removeContent, removeContents, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

schemaDoctype

private static final Doctype schemaDoctype

The non-normative W3C Doctype specification for an XML schema. This uses the prefix "xs" rather than "xsd".

grammars

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

The possibly-multiple roots of the grammar trees represented by this XMLSchema. Whereas a Doctype always compiles to a single-rooted tree, an XMLSchema may describe several different, or overlapping trees. In order to validate a Document, you must first identify the correct ElementRule root.

Constructor Detail

XMLSchema

public XMLSchema()

Creates a default empty XMLSchema with the standard XML Declaration. The standard XML Declaration uses XML version 1.0 and the UTF-8 character set. This constructor is used by parsers that build the XMLSchema incrementally.

XMLSchema

public XMLSchema(Document document)
          throws SemanticError

Creates an XMLSchema from an existing Document. This constructor may be used to convert an existing Document, which is understood to contain an XML schema, into an instance of XMLSchema. The contents of the Document are cloned, before being added to this XMLSchema, to uphold the single parent rule. Rather than read a Document and then convert it to an XMLSchema, it is more efficient to read an XMLSchema directly, using an XSDReader.

Parameters:

document - the Document.

Throws:

SemanticError - if the document does not contain an XML schema.

Method Detail

error

private void error(java.lang.String message)
            throws SemanticError

Raises a SemanticError with this XMLSchema as the context.

Parameters:

message - the desired error message.

Throws:

SemanticError - containing this message.

clone

public XMLSchema clone()

Clones this XMLSchema node. Returns a deep copy of this XMLSchema, in which the content list has been recursively cloned.

Overrides:

clone in class Document

Returns:

a clone of this Document node.

setDeclaration

public XMLSchema setDeclaration(Declaration declaration)
                         throws SemanticError

Sets the XML declaration associated with this XMLSchema. The given Declaration is inserted at the head of this XMLSchema's contents, replacing any default XML declaration. Invokes the inherited method but retypes the result to XMLSchema.

Overrides:

setDeclaration in class Document

Parameters:

declaration - the new XML declaration.

Returns:

this XMLSchema.

Throws:

SemanticError - if an invalid XML declaration is supplied.

setDoctype

public XMLSchema setDoctype(Doctype doctype)

Sets the optional XML Doctype associated with this XMLSchema. W3C suggest non-normative Doctype for an XML schema; although it is rare to bother using it. Ensures that any Doctype, if added, is the suggested one.

Overrides:

setDoctype in class Document

Parameters:

doctype - the Doctype node.

Returns:

this XMLSchema.

setRootElement

public XMLSchema setRootElement(Element root)
                         throws SemanticError

Sets the root Element of this XMLSchema. The root Element may be named "schema" (and declare a default "xmlns" namespace), or be named "xs:schema", or "xsd:schema" (and declare a corresponding "xmlns:xs" or "xmlns:xsd" namespace). If either elements or attributes are declared "qualified", then they must share the same namespace prefix. There must be at least one namespace declaration referring to the namespace for W3C XMLSchema. The globally-defined rules in the schema must have a "name" attribute, for the sake of indexing.

Overrides:

setRootElement in class Document

Parameters:

root - the root Element.

Returns:

this XMLSchema.

Throws:

SemanticError - if the root is not a valid schema root.

setVersion

public XMLSchema setVersion(java.lang.String version)

Sets the XML version associated with this Document. Invokes the inherited method, but returns an XMLSchema.

Overrides:

setVersion in class Document

Parameters:

version - the XML version, typically "1.0".

Returns:

this XMLSchema.

setEncoding

public XMLSchema setEncoding(java.lang.String encoding)

Sets the character encoding associated with this Document. Invokes the inherited method, but returns an XMLSchema.

Overrides:

setEncoding in class Document

Parameters:

encoding - the character encoding, for example "UTF-8".

Returns:

this XMLSchema.

getGrammar

public ElementRule getGrammar(java.lang.String identifier)
                       throws SemanticError

Accesses the top ElementRule for a named Element whose grammar is defined by this XMLSchema. This XMLSchema may contain many global ElementRules, any one of which could be used as the top rule in some grammar. This method retrieves the ElementRule that should match a particular named Element; and adds to this rule four AttributeRules for the optional "xmlns", "xmlns:xsi", "xsi:schemaLocation" and "xsi:noNamespaceSchemaLocation" attributes, which need not be defined in the schema, but which are permissible in a root element.

Parameters:

identifier - the identifier of the root Element.

Returns:

the top ElementRule of the grammar.

Throws:

SemanticError - if no such ElementRule exists.

addRootAttributes

private void addRootAttributes(ElementRule rule)

Adds extra permissible AttributeRules to each top-level ElementRule. Schema instance documents may reference a default 'xmlns' namespace, the 'xmlns:xsi' schemaRoot instance namespace, the 'xsi:schemaLocation' and the 'xsi:noNamespaceSchemaLocation' schemaRoot locations.

Parameters:

rule - the XSD schemaRoot node.

compileGrammar

public void compileGrammar()
                    throws SemanticError

Compiles the grammar represented by this XMLSchema. This method may be invoked to compile the contents of this XMLSchema into a set of internal grammar rules, which may be used to validate a Document. It uses an XSDCompiler to build one or more GrammarRule trees from the Element and Attribute declarations in this XMLSchema. Compilation may be invoked explicitly or implicitly, before this XMLSchema is used to validate a Document. This method ignores any subsequent request to recompile the grammar and returns immediately.

Throws:

SemanticError - if this Schema is inconsistent.

accept

public boolean accept(Document document)
               throws SemanticError

Reports whether this XMLSchema accepts a given Document as valid. Reports whether the root Element of the Document is valid, with respect to the compiled grammar rules of this XMLSchema. Raises a SemanticError if no global rule exists for the root Element. Compiles the grammar, if this has not already been done.

Parameters:

document - a Document.

Returns:

true, if the Document is valid, with respect to this schema.

Throws:

SemanticError - if no grammar is defined for the root Element.

accept

public boolean accept(Element element)
               throws SemanticError

Reports whether this XMLSchema accepts a root Element as valid. If the element is defined in one of this XMLSchema's global element definitions, reports whether it is valid. Raises a SemanticError if no global rule exists for the Element. Compiles the grammar, if this has not already been done.

Parameters:

element - an Element.

Returns:

true, if the Element is valid, with respect to this schema.

Throws:

SemanticError - if no global rule exists for the Element.

validate

public void validate(Document document)
              throws SemanticError

Validates a given Document, raising a SemanticError if it is invalid. If the Document's root element is defined in one of this XMLSchema's global element definitions, validates it, succeeding silently and reporting failure as a SemanticError. Raises a SemanticError if the element is invalid, or no global rule exists for the Element. Compiles the grammar, if this has not already been done.

Parameters:

document - a Document.

Throws:

SemanticError - if the Document is invalid, with respect to this schema, or no global rule exists for the root Element.

validate

public void validate(Element element)
              throws SemanticError

Validates a root Element, raising a SemanticError if it is invalid. If the element is defined in one of this XMLSchema's global element definitions, validates it, succeeding silently and reporting failure as a SemanticError. Raises a SemanticError if the element is invalid, or no global rule exists for the Element. Compiles the grammar, if this has not already been done.

Parameters:

element - an Element.

Throws:

SemanticError - if the element is invalid, or no global rule exists for it.

checkElementNames

private void checkElementNames(Element root)
                        throws SemanticError

Checks the names of the elements in this schema. The root may be called "schema" and declare a default "xmlns" namespace, or be called "xs:schema" and declare an explicit "xmlns:xs" namespace, or be called "xsd:schema" and declare an explicit "xmlns:xsd" namespace. Every globally defined entity in this schema must furthermore have an attribute called "name", so that it may be indexed.

Parameters:

root - the root Element.

Throws:

SemanticError - if any condition is violated.

checkNamespaces

private void checkNamespaces(Element root)

Checks this XMLSchema for valid use of XML namespaces. Either, this XMLSchema declares an explicit namespace, typically "xmnls:xs" or "xmlns:xsd", or it must have a default "xmlns" namespace. If it declares the optional "targetNamespace" attribute, then it must have an "xmlns" default namespace with the same value. If it declares "elementFormDefault" (or "attributeFormDefault") to be "qualified", then the entire schema will be checked to ensure that all elements (or all attributes) have the relevant namespace prefix.

Parameters:

root - the root schema Element.