de.ispsoft.jaxme.jaxb
Interface Validator

All Known Implementing Classes:

ValidatorImpl

Deprecated. Soon to be replaced with javax.xml.bind.Validator

public interface Validator

The Validator class is responsible for controlling the validation of content trees during runtime.

note: all api's related to fail-fast were removed until we figure out how it should work - all other references to fail-fast should be ignored until further notice

Three Forms of Validation

Unmarshal-Time Validation

This form of validation enables a client application to receive information about validation errors and warnings detected while unmarshalling XML data into a Java content tree and is completely orthogonal to the other types of validation. To enable or disable it, see the javadoc for Unmarhaller.setValidating. All JAXB Providers are required to support this operation.

On-Demand Validation

This form of validation enables a client application to receive information about validation errors and warnings detected in the Java content tree. At any point, client applications can call the Validator.validate method on the Java content tree (or any sub-tree of it). All JAXB Providers are required to support this operation.

Fail-Fast Validation

This form of validation enables a client application to receive immediate feedback about modifications to the Java content tree that violate type constraints on Java Properties as defined in the specification. JAXB Providers are not required support this type of validation. Of the JAXB Providers that do support this type of validation, some may require you to decide at schema compile time whether or not a client application will be allowed to request fail-fast validation at runtime.

The Validator class is responsible for managing On-Demand Validation and Fail-Fast Validation. The Unmarshaller class is responsible for managing Unmarshal-Time Validation during the unmarshal operations.

Using the Default EventHandler

If the client application does not set an event handler on their Validator or Unmarshaller prior to calling the validate or unmarshal methods, then a default event handler will receive notification of any errors or warnings encountered. The default event handler will cause the unmarshal and validate operations to halt after encountering the first error or fatal error (but will attempt to continue after receiving warnings).

Handling Validation Events

There are three ways to handle events encountered during the unmarshal and validate operations:

Use the default event handler

The default event handler will be used if you do not specify one via the setEventHandler API's on Validator and Unmarshaller.

Implement and register a custom event handler

Client applications that require sophisticated event processing can implement the ValidationEventHandler interface and register it with the Unmarshaller and/or Validator.

For convenience, a specialized event handler is provided that simply collects any ValidationEvent objects created during the unmarshal and validate operations and returns them to the client application as a java.util.Collection.

Validation and Well-Formedness

Validation events are handled differently depending on how the client application is configured to process them as described in the previous section. However, there are certain cases where a JAXB Provider indicates that it is no longer able to reliably detect and report errors. In these cases, the JAXB Provider will set the severity of the ValidationEvent to FATAL_ERROR to indicate that the unmarshal or validate operation should be terminated. The default event handler and ValidationEventCollector utility class must terminate processing after being notified of a fatal error. Client applications that supply their own ValidationEventHandler should also terminate processing after being notified of a fatal error. If not, unexpected behaviour may occur.

Since:

JAXB1.0

Version:

$Revision: 1.3 $ $Date: 2003/01/10 02:39:00 $

Author:

• Ryan Shoemaker, Sun Microsystems, Inc.
• Kohsuke Kawaguchi, Sun Microsystems, Inc.
• Joe Fialli, Sun Microsystems, Inc.

See Also:

JAXBContext, Unmarshaller, ValidationEventHandler, ValidationEvent

Method Summary

ValidationEventHandler	getEventHandler() Deprecated. Return the current event handler or the default event handler if one hasn't been set.
void	setEventHandler(ValidationEventHandler handler) Deprecated. Allow an application to register a validation event handler.
boolean	validate(java.lang.Object subrootObj) Deprecated. Validate the Java content tree starting at subrootObj.
boolean	validateRoot(java.lang.Object rootObj) Deprecated. Validate the Java content tree rooted at rootObj.

Method Detail

setEventHandler

public void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException

Deprecated.

Allow an application to register a validation event handler.

The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to validate. If the client application does not register a validation event handler before invoking the validate method, then validation events will be handled by the default event handler which will terminate the validate operation after the first error or fatal error is encountered.

Parameters:

handler - the validation event handler

Throws:

JAXBException - if an error was encountered while setting the event handler

getEventHandler

public ValidationEventHandler getEventHandler()
                                       throws JAXBException

Deprecated.

Return the current event handler or the default event handler if one hasn't been set.

Returns:

the current ValidationEventHandler or the default event handler if it hasn't been set

Throws:

JAXBException - if an error was encountered while getting the current event handler

validate

public boolean validate(java.lang.Object subrootObj)

Deprecated.

Validate the Java content tree starting at subrootObj.

Client applications can use this method to validate Java content trees on-demand at runtime. This method can be used to validate any arbitrary subtree of the Java content tree. Global constraint checking will not be performed as part of this operation (i.e. ID/IDREF constraints).

TODO: what happens if the client passes a random java.lang.Object into this method? Throw a runtime exception?

Parameters:

subrootObj - the obj to begin validation at

Returns:

true if the subtree rooted at subrootObj is valid, false otherwise

validateRoot

public boolean validateRoot(java.lang.Object rootObj)

Deprecated.

Validate the Java content tree rooted at rootObj.

Client applications can use this method to validate Java content trees on-demand at runtime. This method is used to validate an entire Java content tree. Global constraint checking will be performed as part of this operation (i.e. ID/IDREF constraints).

TODO: what happens if the client passes a random java.lang.Object into this method? Throw a runtime exception?

Parameters:

rootObj - the root obj to begin validation at

Returns:

true if the tree rooted at rootObj is valid, false otherwise