com.thaiopensource.relaxng.match
Interface Matcher

public interface Matcher

Represents the state of matching an XML document against a RELAX NG pattern. The XML document is considered as a linear sequence of events of different kinds. For each kind of event E in the sequence, a call must be made to a corresponding method matchE on the Matcher object. The kinds of event are:

• StartDocument
• StartTagOpen
• AttributeName
• AttributeValue
• StartTagClose
• Text
• EndTag

The method calls must occur in an order corresponding to a well-formed XML document. In a well-formed document the sequence of events matches the following grammar:

 document ::= StartDocument element
 element ::= startTag child* EndTag
 startTag ::= StartTagOpen attribute* StartTagClose
 attribute ::= AttributeName AttributeValue
 child ::= element | Text
 

Text events must be maximal. Two consecutive Text events are not allowed.

Each method matchE returns false if matching the event against the document resulted in an error and true otherwise. If it returned false, then the error message can be obtained using getErrorMessage. In either case, the state of the Matcher changes so the Matcher is prepared to match the next event.

The copy() and equals() methods allow applications to perform incremental revalidation.

Method Summary

Matcher	copy() Return a copy of the current Matcher.
boolean	equals(java.lang.Object obj) Return true if obj is an equivalent Matcher.
java.lang.String	getErrorMessage() Return the current error message.
boolean	isTextTyped() Return true if text may be typed in the current state, false otherwise.
boolean	isValidSoFar() Return true if the document is valid so far.
boolean	matchAttributeName(Name name)
boolean	matchAttributeValue(java.lang.String value, ValidationContext vc) Match an attribute value.
boolean	matchEndTag(ValidationContext vc) Match an end-tag.
boolean	matchStartDocument() This can only generate an error if the schema was equivalent to notAllowed.
boolean	matchStartTagClose() Match the close of a start-tag (the > character that ends the start-tag).
boolean	matchStartTagOpen(Name name)
boolean	matchText(java.lang.String string, ValidationContext vc, boolean nextTagIsEndTag) Match a text event.
boolean	matchUntypedText() An optimization of matchText.
java.util.Vector	possibleAttributes(java.util.Vector knownNames) Return a Vector of the names of attributes that are valid in the current state.
java.util.Vector	possibleStartTags(java.util.Vector knownNames) Return a Vector of the names of elements whose start-tags are valid in the current state.

Method Detail

copy

Matcher copy()

Return a copy of the current Matcher. Future changes to the state of the copy will not affect this and vice-versa.

Returns:

a Matcher that is a copy of this

equals

boolean equals(java.lang.Object obj)

Return true if obj is an equivalent Matcher.

Overrides:

equals in class java.lang.Object

matchStartDocument

boolean matchStartDocument()

This can only generate an error if the schema was equivalent to notAllowed.

Returns:

false if there was an error, true otherwise

matchStartTagOpen

boolean matchStartTagOpen(Name name)

matchAttributeName

boolean matchAttributeName(Name name)

matchAttributeValue

boolean matchAttributeValue(java.lang.String value,
                            ValidationContext vc)

Match an attribute value. The validation context must include all the namespace declarations in the start-tag including those that lexically follow the attribute.

Parameters:

value - the attribute value, normalized in accordance with XML 1.0

vc - a validation context

Returns:

false if there was an error, true otherwise

matchStartTagClose

boolean matchStartTagClose()

Match the close of a start-tag (the > character that ends the start-tag). This may cause an error if there are required attributes that have not been matched.

Returns:

false if there was an error, true otherwise

matchText

boolean matchText(java.lang.String string,
                  ValidationContext vc,
                  boolean nextTagIsEndTag)

Match a text event. All text between two tags must be collected together: consecutive calls to matchText are not allowed unless separated by a call to matchStartTagOpen or matchEndTag. Calls to matchText can sometimes be optimized into calls to matchUntypedText.

Parameters:

string - the text to be matched

vc - a validation context

nextTagIsEndTag - true if the next event is an EndTag, false if it is a StartTagOpen

Returns:

false if there was an error, true otherwise

matchUntypedText

boolean matchUntypedText()

An optimization of matchText. Unlike matchText, matchUntypedText does not need to examine the text. If isTextTyped returns false, then in this state text that consists of whitespace may be ignored and text that contains non-whitespace characters may be processed using matchUntypedText. Furthermore it is not necessary to collect up all the text between tags; consecutive calls to matchUntypedText are allowed. matchUntypedText must not be used unless isTextTyped returns false.

Returns:

false if there was an error, true otherwise

isTextTyped

boolean isTextTyped()

Return true if text may be typed in the current state, false otherwise. If text may be typed, then a call to matchText must not be optimized to matchUntypedText.

Returns:

true if text may be typed, false otherwise

matchEndTag

boolean matchEndTag(ValidationContext vc)

Match an end-tag.

Parameters:

vc - a validation context

Returns:

false if there was an error, true otherwise

getErrorMessage

java.lang.String getErrorMessage()

Return the current error message. The current error message is changed by any matchE method that returns false. Initially, the current error message is null.

Returns:

a string with the current error message, or null if there has not yet been an error.

isValidSoFar

boolean isValidSoFar()

Return true if the document is valid so far. A document is valid so far if and only if no errors have yet been encountered.

Returns:

true if the document is valid so far, false otherwise

possibleStartTags

java.util.Vector possibleStartTags(java.util.Vector knownNames)

Return a Vector of the names of elements whose start-tags are valid in the current state. This must be called only in a state in which a call to matchStartTagOpen would be allowed. The members of the Vector have type com.thaiopensource.xml.util.Name. When an element pattern with a wildcard name-class is possible, then all Names in knownNames that are contained in the wildcard name-class will be included in the returned Vector. The returned list may contain duplicates. Does not modify knownNames.

Parameters:

knownNames - a Vector of names to be considered for wildcards, or null

Returns:

a Vector of names whose start-tags are possible

possibleAttributes

java.util.Vector possibleAttributes(java.util.Vector knownNames)

Return a Vector of the names of attributes that are valid in the current state. This must be called only in a state in which a call to matchAttributeName would be allowed. The members of the Vector have type com.thaiopensource.xml.util.Name. When an attribute pattern with a wildcard name-class is possible, then all Names in knownNames that are contained in the wildcard name-class will be included in the returned Vector. The returned list may contain duplicates. Does not modify knownNames.

Parameters:

knownNames - a Vector of names to be considered for wildcards, or null

Returns:

a Vector of names of attributes that are possible