org.codehaus.stax2.validation
Class XMLValidator

java.lang.Object
  extended by org.codehaus.stax2.validation.XMLValidator
Direct Known Subclasses:
DTDValidatorBase, RelaxNGValidator, ValidatorPair

public abstract class XMLValidator
extends java.lang.Object

Class that defines interface that individual (possibly) stateful validator instances have to implement, and that both XMLStreamReader and XMLStreamWriter instances can call to validate xml documents.

Validator instances are created from and by non-stateful XMLValidationSchema instances. A new validator instance has to be created for each document read or written, ie. can not be shared or reused, unlike schema instances which can be.


Field Summary
static int CONTENT_ALLOW_ANY_TEXT
          This value indicates that any textual content (plain PCTEXT) is allowed, and that validator is not going to do any validation for it.
static int CONTENT_ALLOW_NONE
          This value indicates that no content whatsoever is legal within current context, that is, where the only legal content to follow is the closing end tag -- not even comments or processing instructions are allowed.
static int CONTENT_ALLOW_UNDEFINED
          This value is a placeholder that should never be returned by validators, but that can be used internally as an uninitialized value.
static int CONTENT_ALLOW_VALIDATABLE_TEXT
          This value indicates that textual content is allowed, but that the validator needs to be called to let it do actual content-based validation.
static int CONTENT_ALLOW_WS
          This value indicates that only white space text content is allowed, not other kinds of text.
 
Constructor Summary
protected XMLValidator()
           
 
Method Summary
abstract  java.lang.String getAttributeType(int index)
          Method for getting schema-specified type of an attribute, if information is available.
abstract  int getIdAttrIndex()
          Method for finding out the index of the attribute that is of type ID; derived from DTD, W4C Schema, or some other validation source.
abstract  int getNotationAttrIndex()
          Method for finding out the index of the attribute (collected using the attribute collector; having DTD/Schema-derived info in same order) that is of type NOTATION.
abstract  XMLValidationSchema getSchema()
          Returns the schema instance that created this validator object, if known (and applicable).
 java.lang.String getSchemaType()
          Returns type of schema that was used to construct this validator instance.
abstract  java.lang.String validateAttribute(java.lang.String localName, java.lang.String uri, java.lang.String prefix, char[] valueChars, int valueStart, int valueEnd)
          Callback method called on validator to give it a chance to validate the value of an attribute, as well as to normalize its value if appropriate (remove leading/trailing/intervening white space for certain token types etc.).
abstract  java.lang.String validateAttribute(java.lang.String localName, java.lang.String uri, java.lang.String prefix, java.lang.String value)
          Callback method called on validator to give it a chance to validate the value of an attribute, as well as to normalize its value if appropriate (remove leading/trailing/intervening white space for certain token types etc.).
abstract  int validateElementAndAttributes()
          Method called after calling validateAttribute(java.lang.String, java.lang.String, java.lang.String, java.lang.String) on all attributes (if any), but before starting to handle element content.
abstract  int validateElementEnd(java.lang.String localName, java.lang.String uri, java.lang.String prefix)
          Method called right after encountering an element close tag.
abstract  void validateElementStart(java.lang.String localName, java.lang.String uri, java.lang.String prefix)
           
abstract  void validateText(char[] cbuf, int textStart, int textEnd, boolean lastTextSegment)
          Method called to validate textual content.
abstract  void validateText(java.lang.String text, boolean lastTextSegment)
          Method called to validate textual content.
abstract  void validationCompleted(boolean eod)
          Method called when the validation is completed; either due to the input stream ending, or due to an explicit 'stop validation' request by the application (via context object).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONTENT_ALLOW_NONE

public static final int CONTENT_ALLOW_NONE
This value indicates that no content whatsoever is legal within current context, that is, where the only legal content to follow is the closing end tag -- not even comments or processing instructions are allowed. This is the case for example for elements that DTD defines to have EMPTY content model.

See Also:
Constant Field Values

CONTENT_ALLOW_WS

public static final int CONTENT_ALLOW_WS
This value indicates that only white space text content is allowed, not other kinds of text. Other events may be allowed; validator will deal with element validation.

See Also:
Constant Field Values

CONTENT_ALLOW_VALIDATABLE_TEXT

public static final int CONTENT_ALLOW_VALIDATABLE_TEXT
This value indicates that textual content is allowed, but that the validator needs to be called to let it do actual content-based validation. Other event types are ok, and elements will need to be validated by the validator as well.

See Also:
Constant Field Values

CONTENT_ALLOW_ANY_TEXT

public static final int CONTENT_ALLOW_ANY_TEXT
This value indicates that any textual content (plain PCTEXT) is allowed, and that validator is not going to do any validation for it. It will, however, need to be called with respect to element events.

See Also:
Constant Field Values

CONTENT_ALLOW_UNDEFINED

public static final int CONTENT_ALLOW_UNDEFINED
This value is a placeholder that should never be returned by validators, but that can be used internally as an uninitialized value.

See Also:
Constant Field Values
Constructor Detail

XMLValidator

protected XMLValidator()
Method Detail

getSchemaType

public java.lang.String getSchemaType()
Returns type of schema that was used to construct this validator instance.

Returns:
One of external schema identifier values (such as XMLValidationSchema.SCHEMA_ID_DTD).

getSchema

public abstract XMLValidationSchema getSchema()
Returns the schema instance that created this validator object, if known (and applicable). May return null for some instances: specifically, ValidatorPair will return null since it 'contains' multiple validators and generally does not have just one parent or owner schema.


validateElementStart

public abstract void validateElementStart(java.lang.String localName,
                                          java.lang.String uri,
                                          java.lang.String prefix)
                                   throws XMLValidationException
Throws:
XMLValidationException

validateAttribute

public abstract java.lang.String validateAttribute(java.lang.String localName,
                                                   java.lang.String uri,
                                                   java.lang.String prefix,
                                                   java.lang.String value)
                                            throws XMLValidationException
Callback method called on validator to give it a chance to validate the value of an attribute, as well as to normalize its value if appropriate (remove leading/trailing/intervening white space for certain token types etc.).

Returns:
Null, if the passed value is fine as is; or a String, if it needs to be replaced. In latter case, caller will replace the value before passing it to other validators. Also, if the attribute value is accessible via caller (as is the case for stream readers), caller should return this value, instead of the original one.
Throws:
XMLValidationException

validateAttribute

public abstract java.lang.String validateAttribute(java.lang.String localName,
                                                   java.lang.String uri,
                                                   java.lang.String prefix,
                                                   char[] valueChars,
                                                   int valueStart,
                                                   int valueEnd)
                                            throws XMLValidationException
Callback method called on validator to give it a chance to validate the value of an attribute, as well as to normalize its value if appropriate (remove leading/trailing/intervening white space for certain token types etc.).

Parameters:
valueChars - Character array that contains value (possibly along with some other text)
valueStart - Index of the first character of the value in in valueChars array
valueEnd - Index of the character AFTER the last character; so that the length of the value String is valueEnd - valueStart
Returns:
Null, if the passed value is fine as is; or a String, if it needs to be replaced. In latter case, caller will replace the value before passing it to other validators. Also, if the attribute value is accessible via caller (as is the case for stream readers), caller should return this value, instead of the original one.
Throws:
XMLValidationException

validateElementAndAttributes

public abstract int validateElementAndAttributes()
                                          throws XMLValidationException
Method called after calling validateAttribute(java.lang.String, java.lang.String, java.lang.String, java.lang.String) on all attributes (if any), but before starting to handle element content.

Returns:
One of CONTENT_ALLOW_ constants, to indicate what kind of textual content is allowed at the scope returned to after the element has closed.
Throws:
XMLValidationException

validateElementEnd

public abstract int validateElementEnd(java.lang.String localName,
                                       java.lang.String uri,
                                       java.lang.String prefix)
                                throws XMLValidationException
Method called right after encountering an element close tag.

Returns:
One of CONTENT_ALLOW_ constants, to indicate what kind of textual content is allowed at the scope returned to after the element has closed.
Throws:
XMLValidationException

validateText

public abstract void validateText(java.lang.String text,
                                  boolean lastTextSegment)
                           throws XMLValidationException
Method called to validate textual content.

Note: this method is only guaranteed to be called when validateElementAndAttributes() for the currently open element returned CONTENT_ALLOW_VALIDATABLE_TEXT (or, in case of mixed content, validateElementEnd(java.lang.String, java.lang.String, java.lang.String), for the last enclosed element). Otherwise, validator context may choose not to call the method as an optimization.

Parameters:
text - Text content to validate
lastTextSegment - Whether this text content is the last text segment before a close element; true if it is, false if it is not, or no determination can be made. Can be used for optimizing validation -- if this is true, no text needs to be buffered since no more will be sent before the current element closes.
Throws:
XMLValidationException

validateText

public abstract void validateText(char[] cbuf,
                                  int textStart,
                                  int textEnd,
                                  boolean lastTextSegment)
                           throws XMLValidationException
Method called to validate textual content.

Note: this method is only guaranteed to be called when validateElementAndAttributes() for the currently open element returned CONTENT_ALLOW_VALIDATABLE_TEXT (or, in case of mixed content, validateElementEnd(java.lang.String, java.lang.String, java.lang.String), for the last enclosed element). Otherwise, validator context may choose not to call the method as an optimization.

Parameters:
cbuf - Character array that contains text content to validate
textStart - Index of the first character of the content to validate
textEnd - Character following the last character of the content to validate (that is, length of content to validate is textEnd - textStart).
lastTextSegment - Whether this text content is the last text segment before a close element; true if it is, false if it is not, or no determination can be made. Can be used for optimizing validation -- if this is true, no text needs to be buffered since no more will be sent before the current element closes.
Throws:
XMLValidationException

validationCompleted

public abstract void validationCompleted(boolean eod)
                                  throws XMLValidationException
Method called when the validation is completed; either due to the input stream ending, or due to an explicit 'stop validation' request by the application (via context object).

Parameters:
eod - Flag that indicates whether this method was called by the context due to the end of the stream (true); or by an application requesting end of validation (false).
Throws:
XMLValidationException

getAttributeType

public abstract java.lang.String getAttributeType(int index)
Method for getting schema-specified type of an attribute, if information is available. If not, validators can return null to explicitly indicate no information was available.


getIdAttrIndex

public abstract int getIdAttrIndex()
Method for finding out the index of the attribute that is of type ID; derived from DTD, W4C Schema, or some other validation source. Usually schemas explicitly specifies that at most one attribute can have this type for any element.

Returns:
Index of the attribute with type ID, in the current element, if one exists: -1 otherwise

getNotationAttrIndex

public abstract int getNotationAttrIndex()
Method for finding out the index of the attribute (collected using the attribute collector; having DTD/Schema-derived info in same order) that is of type NOTATION. DTD explicitly specifies that at most one attribute can have this type for any element.

Returns:
Index of the attribute with type NOTATION, in the current element, if one exists: -1 otherwise