com.thaiopensource.relaxng.match.Matcher Maven / Gradle / Ivy
Show all versions of wicketstuff-jing Show documentation
package com.thaiopensource.relaxng.match;
import com.thaiopensource.xml.util.Name;
import java.util.Set;
/**
* 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
* - EndDocument
*
*
* 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 EndDocument
* 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.
* Matching text is special, and is done with matchTextBeforeStartTag
* or matchTextBeforeEndTag, according as the Text event is
* followed by a StartTagOpen or an EndTag event. Callers may optionally choose
* to optimize calls to matchTextBeforeStartTag
* or matchTextBeforeEndTag into calls to matchUntypedText,
* but this is only allowed when isTextTyped returns false.
*
* 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.
*/
public interface Matcher {
/**
* Return a copy of the current Matcher.
* Future changes to the state of the copy will not affect this and vice-versa.
*
* @return a Matcher that is a copy of this
*/
Matcher copy();
/**
* Return a copy of this Matcher reset to its starting state.
* @return a new Matcher
*/
Matcher start();
/**
* Test whether obj is an equivalent Matcher.
* @return true if they are obj is known to be equivalent, false otherwise
*/
boolean equals(Object obj);
/**
* Return a hashCode for the Matcher. This is consistent with equals.
* @return a hash code
*/
int hashCode();
/**
* Match a StartDocument event. This can only generate an error if the schema was
* equivalent to notAllowed.
*
* @return false if there was an error, true otherwise
*/
boolean matchStartDocument();
/**
* Match an EndDocument event.
*
* @return false if there was an error, true otherwise
*/
boolean matchEndDocument();
/**
* Match a StartTagOpen event.
* @param name the element name
* @param qName the element qName (may be empty or null if unknown)
* @param context the MatchContext
* @return false if there was an error, true otherwise
*/
boolean matchStartTagOpen(Name name, String qName, MatchContext context);
/**
* Match an AttributeName event.
*
* @param name the attribute name
* @param qName the attribute qName (may be empty or null if unknown)
* @param context the MatchContext
* @return false if there was an error, true otherwise
*/
boolean matchAttributeName(Name name, String qName, MatchContext context);
/**
* Match an AttributeValue event.
* The MatchContext must include all the namespace declarations in the start-tag
* including those that lexically follow the attribute.
*
* @param value the attribute value, normalized in accordance with XML 1.0
* @param name the attribute name (included for use in error messages)
* @param qName the attribute qName (included for use in error messages)
* @param context the MatchContext
* @return false if there was an error, true otherwise
*/
boolean matchAttributeValue(String value, Name name, String qName, MatchContext context);
/**
* Match a StartTagClose event. This corresponds to the > character
* that ends the start-tag).
* It may cause an error if there are required attributes that have not been matched.
* The parameters are used to generate error messages.
*
* @param name the element name
* @param qName the element qName (may be null or empty)
* @param context the MatchContext
* @return false if there was an error, true otherwise
*/
boolean matchStartTagClose(Name name, String qName, MatchContext context);
/**
* Match a Text event that occurs immediately before an EndTag event.
* All text between two tags must be collected together: consecutive
* calls to matchTextBeforeEndTag/matchTextBeforeStartTag are not
* allowed unless separated by a call to matchStartTagOpen or matchEndTag.
* Calls to matchTextBeforeEndTag can sometimes be optimized into
* calls to matchUntypedText.
*
* @param string the text to be matched
* @param name the name of the parent element (i.e. the name of the element of the following
* EndTag event)
* @param qName the qName of the parent element
* @param context a match context
* @return false if there was an error, true otherwise
*/
boolean matchTextBeforeEndTag(String string, Name name, String qName, MatchContext context);
/**
* Match a Text event that occurs immediately before a StartTagOpen event.
* All text between two tags must be collected together: consecutive
* calls to matchTextBeforeEndTag/matchTextBeforeStartTag are not
* allowed unless separated by a call to matchStartTagOpen or matchEndTag.
* Calls to matchTextBeforeStartTag can sometimes be optimized into
* calls to matchUntypedText.
*
* @param string the text to be matched
* @param context a match context
* @return false if there was an error, true otherwise
*/
boolean matchTextBeforeStartTag(String string, MatchContext context);
/**
* An optimization of matchTextBeforeStartTag/matchTextBeforeEndTag.
* Unlike these functions, matchUntypedText does not
* need to examine the text.
* If isTextTyped returns false, then in this state
* text that consists of whitespace (' ', '\r', '\n', '\t') 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.
* @param context a match context
* @return false if there was an error, true otherwise
*/
boolean matchUntypedText(MatchContext context);
/**
* 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.
*
* @return true if text may be typed, false otherwise
*/
boolean isTextTyped();
/**
* Match an EndTag event.
*
* @param name the element name
* @param qName the elememt qname (may be empty or null if unknown)
* @param context a match context
* @return false if there was an error, true otherwise
*/
boolean matchEndTag(Name name, String qName, MatchContext context);
/**
* 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.
*
* @return a string with the current error message, or null if there has not yet
* been an error.
*/
String getErrorMessage();
/**
* 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.
*
* @return true if the document is valid so far, false otherwise
*/
boolean isValidSoFar();
/**
* Return a NameClass containing 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.
*
* @return a NameClass contains the names of elements whose start-tags are possible
*/
NameClass possibleStartTagNames();
/**
* Return a NameClass containing 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.
*
* @return a NameClass containing the names of attributes that are possible
*/
NameClass possibleAttributeNames();
/**
* Return a Set containing the names of attributes that are required in the
* current state. This must be called only in a state in
* which a call to matchAttributeName would be allowed. Note
* that in a schema such as attribute foo|bar { text } neither foo nor
* bar are considered required attributes; an attribute name x is required
* only if every matching pattern contains an attribute named x. Similarly,
* this function provides no information about wildcard attribute names.
* @return a non-null Set each member of which is a non-null Name corresponding
* to the name of a required attribute
* @see Name
*/
Set requiredAttributeNames();
Set requiredElementNames();
}