javax.xml.bind
Class Validator

java.lang.Object
  |
  +--javax.xml.bind.Validator

public final class Validator

extends Object

A validator governs the process of validating a content tree. It supplies the central validation method, validate(ValidatableObject), methods for recording and resolving identifier references, and the internal logic required to validate global structural constraints.

The process of validating a content tree begins when the validate() method of the tree's root element object is invoked. This method creates a new validator and then proceeds to validate the content tree by invoking the validator's validate(ValidatableObject) method, passing the root object.

The validator's validate(ValidatableObject) method ensures that the following validation propositions are true of its argument object:

1. The object has not yet been visited during this validation, i.e., that it is not part of a cycle;

2. The object is locally valid, i.e., that its validateThis() method would not throw a LocalValidationException if invoked; and that

3. If the object implements the IdentifiableElement interface then its identifier, if not null, is unique among the identifiers so far encountered during this validation.

The validator's validate(ValidatableObject) method also invokes its argument's validate(Validator) method, passing the validator itself, in order to:

• Ensure that the above propositions are true of its argument's children in the content tree, if any; and to

• Arrange to ensure before the end of the validation process that the targets of any identifier-reference properties in the object have identifiers and are members of the content tree being validated.

Each validatable object's validate(Validator) method recursively validates the object's children, if any, by invoking the validator's validate(ValidatableObject) method upon them. It also invokes the validator's reference(IdentifiableElement) method upon the target of each identifier-reference property in the object.

If this recursive process completes successfully then the propositions defined above are known to hold for every object in the content tree. The root element object's validate() method then checks that the target of every identifier reference has an identifier and is a member of the content tree.

Validators are also used during the unmarshalling process to validate an content tree as it is being unmarshalled. The validation process is slightly different when carried out during unmarshalling, although the guarantees that it makes are identical. There is no need to check for cycles, in particular, since that proposition is guaranteed by the linear nature of the unmarshalling process. It is necessary, however, to arrange that identifiers referring to elements that have not yet been unmarshalled be resolved before the unmarshalling process is complete. This requirement is supported by the validator's reference(String, Validator.Patcher) method, which takes a patcher object that represents the unresolved reference. The unmarshalling process ensures that all references are resolved before it completes. It also ensures that all patchers are invoked with the targets of their references so that appropriate links can be installed in the objects referring to those targets.

This class does not have any public or protected constructors; it is intended only for use by the validation and unmarshalling processes.

Version:

1.16, 01/05/31

See Also:

ValidatableObject

Inner Class Summary

static class

Validator.Patcher A patcher represents an unresolved identifier reference.

Method Summary

void	reference(IdentifiableElement elt) Records the fact that a reference has been made to the given identifiable element object.
void	reference(String id, Validator.Patcher p) Records the fact that a reference has been made to an element object with the given identifier, and registers a patcher for later invocation.
void	validate(ValidatableObject vob) Validates the given object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

reference

public void reference(IdentifiableElement elt)
               throws MissingIdentifierException

Records the fact that a reference has been made to the given identifiable element object. This method arranges to ensure before the end of the validation process that the given object is a member of the content tree being validated.

Parameters:

elt - The referenced element object

Throws:

MissingIdentifierException - If the argument does not have an identifier

reference

public void reference(String id,
                      Validator.Patcher p)

Records the fact that a reference has been made to an element object with the given identifier, and registers a patcher for later invocation. This method arranges to ensure before the end of the unmarshalling process that the given identifier is resolved and that the patcher is invoked with the target of the reference.

Parameters:

id - The identifier value being referenced

patcher - The patcher to be invoked after the identifier is resolved

validate

public void validate(ValidatableObject vob)
              throws StructureValidationException

Validates the given object.

This method ensures that the validation propositions hold for the given object. It also invokes the given object's validate(Validator) method, passing this validator, in order to ensure that the propositions are true of the given object's children and to arrange to ensure before the end of the validation process that the targets of any identifier-reference properties in this object have identifiers and are members of the content tree being validated.

This method is not intended to be invoked outside of the validation process; its behavior when invoked in any other manner is unspecified.

Parameters:

vob - The object to be validated

Throws:

CycleException - If the object has already been visited during this validation, in which case there is a cycle in this content tree

DuplicateIdentifierException - If the object has an identifier that is the same as the identifier of some other object in this content tree

StructureValidationException - If some other validation failure is detected