com.ibm.xml.framework
Interface XMLValidationHandler

public abstract interface XMLValidationHandler

This class defines the interface between the scanner and a validator. As the scanner scans the XML content, it will call these methods to validate the data as it goes. It is assumed that the implementation of the interface will use the provided XMLParser object to gain access to the element declaration and string pools required to interpret the passed element and attribute indexes.

Version:

Revision: 52 1.7 src/com/ibm/xml/framework/XMLValidationHandler.java, parser, xml4j2, xml4j2_0_0

See Also:

XMLParser

Method Summary

void	checkAttributes(int elementIndex, int firstAttrIndex) Check that the attributes for an element are valid.
int	checkContent(int elementIndex, int childCount, int[] children) Check that the content of an element is valid.
void	checkIDRefNames() Check that all ID references were to ID attributes present in the document.
void	checkRootElementName(int elementNameIndex) Check that the root element name is valid.
void	reset(ParserState parserState) Reset the handler.
int	whatCanGoHere(int elementIndex, boolean fullyValid, InsertableElementsInfo info) Returns information about which elements can be placed at a particular point in the passed element's content model.

Method Detail

reset

public void reset(ParserState parserState)

Reset the handler.

Parameters:

parserState - The parser state to use for the next parse call.

checkRootElementName

public void checkRootElementName(int elementNameIndex)
                          throws java.lang.Exception

Check that the root element name is valid. This method is called when the scanner sees the root element of the target XML document. It will pass the element name index of the root element, which the validator must confirm was the root name indicated in the DTD (or one of the valid roots indicated by a Schema.)

Parameters:

elementNameIndex - The index within the StringPool of the root element name.

checkAttributes

public void checkAttributes(int elementIndex,
                            int firstAttrIndex)
                     throws java.lang.Exception

Check that the attributes for an element are valid. This method is called as a convenience. The scanner will do any required checks for well-formedness on the attributes, as well as fill out any defaulted ones. However, if the validator has any other constraints or semantics it must enforce, it can use this API to do so. The scanner provides the element index (within the decl pool, i.e. not the name index which is within the string pool), and the index of the first attribute within the attribute pool that holds the attributes of the element. By this time, all defaulted attributes are present and all fixed values have been confirmed. For most validators, this will be a no-op.

Parameters:

elementIndex - The index within the ElementDeclPool of this element.

firstAttrIndex - The index within the AttrPool of the first attribute of this element, or -1 if there are no attributes.

checkContent

public int checkContent(int elementIndex,
                        int childCount,
                        int[] children)
                 throws java.lang.Exception

Check that the content of an element is valid. This is the method of primary concern to the validator. This method is called upon the scanner reaching the end tag of an element. At that time, the element's children must be structurally validated, so it calls this method. The index of the element being checked (in the decl pool), is provided as well as an array of element name indexes of the children. The validator must confirm that this element can have these children in this order. This can also be called to do 'what if' testing of content models just to see if they would be valid. Note that the element index is an index into the element decl pool, whereas the children indexes are name indexes, i.e. into the string pool. A -1 in the children array indicates a PCDATA node. All other indexes will be positive and represent child elements. The count can be zero, since some elements have the EMPTY content model and that must be confirmed.

Parameters:

elementIndex - The index within the ElementDeclPool of this element.

childCount - The number of entries in the children array.

children - The children of this element. Each integer is an index within the StringPool of the child element name. An index of -1 is used to indicate an occurrence of non-whitespace character data.

Returns:

-1 if fully valid, else the 0 based index of the child that first failed.

checkIDRefNames

public void checkIDRefNames()
                     throws java.lang.Exception

Check that all ID references were to ID attributes present in the document. This method is a convenience call that allows the validator to do any id ref checks above and beyond those done by the scanner. The scanner does the checks specificied in the XML spec, i.e. that ID refs refer to ids which were eventually defined somewhere in the document. If the validator is for a Schema perhaps, which defines id semantics beyond those of the XML specificiation, this is where that extra checking would be done. For most validators, this is a no-op.

whatCanGoHere

public int whatCanGoHere(int elementIndex,
                         boolean fullyValid,
                         InsertableElementsInfo info)
                  throws java.lang.Exception

Returns information about which elements can be placed at a particular point in the passed element's content model. See the InsertableElementsInfo class for details on the input and output information required. Note that the incoming content model to test must be valid at least up to the insertion point. If not, then -1 will be returned and the info object will not have been filled in. If, on return, the info.isValidEOC flag is set, then the 'insert after' elemement is a valid end of content, i.e. nothing needs to be inserted after it to make the parent element's content model valid.

Parameters:

elementIndex - The index within the ElementDeclPool of the element which is being querying.

fullyValid - Only return elements that can be inserted and still maintain the validity of subsequent elements past the insertion point (if any). If the insertion point is at the end, and this is true, then only elements that can be legal final states will be returned.

info - An object that contains the required input data for the method, and which will contain the output information if successful.

Returns:

-1 if successful, else the zero based index of the first element which failed before the insertion point.