Package org.apache.ws.commons.schema.docpath

package org.apache.ws.commons.schema.docpath
This package is dedicated to walking an XML Document using the SAX API, and building a path through its XmlSchemaCollection to determine how the document conforms to its schema.

This is done in four steps:

  1. Build a state machine of the XmlSchemaCollection, represented as XmlSchemaStateMachineNodes.
  2. Start a SAX-based walk over the XML Document, either via SAXParser, when working with raw XML, or SaxWalkerOverDom when working with an Document.
  3. Use XmlSchemaPathFinder to build a series of XmlSchemaDocumentNodes and XmlSchemaPathNodes representing a valid walk through the XmlSchemaCollection.
  4. Add any application-specific information to the paths through the document using XmlSchemaDocumentNode.setUserDefinedContent(Object) and XmlSchemaPathNode.setUserDefinedContent(Object).

XmlSchemaStateMachineNode

XmlSchemaStateMachineNode represents a single node in the XmlSchema - either an element or a group - and the possible nodes that may follow (children of the element or group). Only one state machine node will be created by the XmlSchemaStateMachineGenerator for each XmlSchemaElement, meaning the XmlSchemaStateMachineNodes may loop back on themselves if an XML element is a child of itself.

XmlSchemaDocumentNode

As XmlSchemaStateMachineNodes represent the XML Schema, XmlSchemaDocumentNodes represent the XML Schema as applied to an XML Document. Each node represents all occurrences of the node in the XML Document, and a different set of children can be requested, one for each occurrence. Document nodes never loop back on themselves; if an element is a child of itself, a new document node instance will be created at each level in the tree.

As a result, the XmlSchemaDocumentNodes form a tree structure, starting with the root node of the document and working downward. User-defined content can be attached to each node in the tree using the XmlSchemaPathNode.setUserDefinedContent(Object). method.

XmlSchemaPathNode

Where XmlSchemaDocumentNodes represent the XML Schema structure used to describe the XML Document, XmlSchemaPathNodes define the actual walk through the XML Schema taken to represent that document.

Paths may go in four XmlSchemaPathNode.Directions:

  • XmlSchemaPathNode.Direction.CHILD: The path moves from the current node in the tree (an element or group) to one of its children.
  • XmlSchemaPathNode.Direction.PARENT: The path moves from the current node in the tree to its parent. If moving to the parent of an element, this closes the tag.
  • XmlSchemaPathNode.Direction.SIBLING: This initiates a new occurrence of the current (wildcard) element or group. If creating a sibling (wildcard) element, this closes the tag of the existing element and opens a new one of the same name.
  • XmlSchemaPathNode.Direction.CONTENT: This represents content inside an element (not children tags). This will either be the simple content of a simple element, or the text contained inside a mixed element. Mixed content may occur as either a direct child of the owning element, or inside one of the owning element's child groups.

XmlSchemaPathFinder

XmlSchemaPathFinder builds XmlSchemaDocumentNodes and XmlSchemaPathNodes from XmlSchemaStateMachineNode during a SAX walk of an XML document. In addition to confirming the XML Document conforms to its schema's structure, it will also confirm attribute and element content conform to its expected type.

Note: This is done entirely over a SAX walk, meaning the source need not be an XML Document at all. Any data structure that can be traversed via a SAX walk can be confirmed to conform against an expected XML Schema.

SaxWalkerOverDom

This allows SAX-based walks over Document objects. One can use this in conjunction with XmlSchemaPathFinder to confirm a document parsed using a DocumentBuilder conforms to its XML Schema.

DomBuilderFromSax

In the reverse direction, one can use DomBuilderFromSax to build an Document based on an XML Schema and a SAX walk over content that represents a document conforming to that XmlSchema . For best results, use XmlSchemaStateMachineGenerator to build a mapping of QNames to XmlSchemaStateMachineNodes. This is used by the DomBuilderFromSax to resolve ambiguities in how to generate the XML Document based on the schema.