< prev index next >
src/java.xml.bind/share/classes/javax/xml/bind/Validator.java
Print this page
*** 26,36 ****
package javax.xml.bind;
/**
* As of JAXB 2.0, this class is deprecated and optional.
* <p>
! * The <tt>Validator</tt> class is responsible for controlling the validation
* of content trees during runtime.
*
* <p>
* <a name="validationtypes"></a>
* <b>Three Forms of Validation</b><br>
--- 26,36 ----
package javax.xml.bind;
/**
* As of JAXB 2.0, this class is deprecated and optional.
* <p>
! * The {@code Validator} class is responsible for controlling the validation
* of content trees during runtime.
*
* <p>
* <a name="validationtypes"></a>
* <b>Three Forms of Validation</b><br>
*** 67,89 ****
* </dd>
* </dl>
* </blockquote>
*
* <p>
! * The <tt>Validator</tt> class is responsible for managing On-Demand Validation.
! * The <tt>Unmarshaller</tt> class is responsible for managing Unmarshal-Time
* Validation during the unmarshal operations. Although there is no formal
* method of enabling validation during the marshal operations, the
! * <tt>Marshaller</tt> may detect errors, which will be reported to the
! * <tt>ValidationEventHandler</tt> registered on it.
*
* <p>
* <a name="defaulthandler"></a>
* <b>Using the Default EventHandler</b><br>
* <blockquote>
* If the client application does not set an event handler on their
! * <tt>Validator</tt>, <tt>Unmarshaller</tt>, or <tt>Marshaller</tt> prior to
* calling the validate, unmarshal, or marshal methods, then a default event
* handler will receive notification of any errors or warnings encountered.
* The default event handler will cause the current operation to halt after
* encountering the first error or fatal error (but will attempt to continue
* after receiving warnings).
--- 67,89 ----
* </dd>
* </dl>
* </blockquote>
*
* <p>
! * The {@code Validator} class is responsible for managing On-Demand Validation.
! * The {@code Unmarshaller} class is responsible for managing Unmarshal-Time
* Validation during the unmarshal operations. Although there is no formal
* method of enabling validation during the marshal operations, the
! * {@code Marshaller} may detect errors, which will be reported to the
! * {@code ValidationEventHandler} registered on it.
*
* <p>
* <a name="defaulthandler"></a>
* <b>Using the Default EventHandler</b><br>
* <blockquote>
* If the client application does not set an event handler on their
! * {@code Validator}, {@code Unmarshaller}, or {@code Marshaller} prior to
* calling the validate, unmarshal, or marshal methods, then a default event
* handler will receive notification of any errors or warnings encountered.
* The default event handler will cause the current operation to halt after
* encountering the first error or fatal error (but will attempt to continue
* after receiving warnings).
*** 96,123 ****
* There are three ways to handle events encountered during the unmarshal,
* validate, and marshal operations:
* <dl>
* <dt>Use the default event handler</dt>
* <dd>The default event handler will be used if you do not specify one
! * via the <tt>setEventHandler</tt> API's on <tt>Validator</tt>,
! * <tt>Unmarshaller</tt>, or <tt>Marshaller</tt>.
* </dd>
*
* <dt>Implement and register a custom event handler</dt>
* <dd>Client applications that require sophisticated event processing
! * can implement the <tt>ValidationEventHandler</tt> interface and
! * register it with the <tt>Unmarshaller</tt> and/or
! * <tt>Validator</tt>.
* </dd>
*
* <dt>Use the {@link javax.xml.bind.util.ValidationEventCollector ValidationEventCollector}
* utility</dt>
* <dd>For convenience, a specialized event handler is provided that
! * simply collects any <tt>ValidationEvent</tt> objects created
* during the unmarshal, validate, and marshal operations and
* returns them to the client application as a
! * <tt>java.util.Collection</tt>.
* </dd>
* </dl>
* </blockquote>
*
* <p>
--- 96,123 ----
* There are three ways to handle events encountered during the unmarshal,
* validate, and marshal operations:
* <dl>
* <dt>Use the default event handler</dt>
* <dd>The default event handler will be used if you do not specify one
! * via the {@code setEventHandler} API's on {@code Validator},
! * {@code Unmarshaller}, or {@code Marshaller}.
* </dd>
*
* <dt>Implement and register a custom event handler</dt>
* <dd>Client applications that require sophisticated event processing
! * can implement the {@code ValidationEventHandler} interface and
! * register it with the {@code Unmarshaller} and/or
! * {@code Validator}.
* </dd>
*
* <dt>Use the {@link javax.xml.bind.util.ValidationEventCollector ValidationEventCollector}
* utility</dt>
* <dd>For convenience, a specialized event handler is provided that
! * simply collects any {@code ValidationEvent} objects created
* during the unmarshal, validate, and marshal operations and
* returns them to the client application as a
! * {@code java.util.Collection}.
* </dd>
* </dl>
* </blockquote>
*
* <p>
*** 129,141 ****
* 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, validate, or marshal operations
* should be terminated. The default event handler and
! * <tt>ValidationEventCollector</tt> utility class must terminate processing
* after being notified of a fatal error. Client applications that supply their
! * own <tt>ValidationEventHandler</tt> should also terminate processing after
* being notified of a fatal error. If not, unexpected behaviour may occur.
* </blockquote>
*
* <p>
* <a name="supportedProps"></a>
--- 129,141 ----
* 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, validate, or marshal operations
* should be terminated. The default event handler and
! * {@code ValidationEventCollector} utility class must terminate processing
* after being notified of a fatal error. Client applications that supply their
! * own {@code ValidationEventHandler} should also terminate processing after
* being notified of a fatal error. If not, unexpected behaviour may occur.
* </blockquote>
*
* <p>
* <a name="supportedProps"></a>
*** 193,250 ****
*/
public ValidationEventHandler getEventHandler()
throws JAXBException;
/**
! * Validate the Java content tree starting at <tt>subrootObj</tt>.
* <p>
* 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 <b>will not
* </b> be performed as part of this operation (i.e. ID/IDREF constraints).
*
* @param subrootObj the obj to begin validation at
* @throws JAXBException if any unexpected problem occurs during validation
* @throws ValidationException
* If the {@link ValidationEventHandler ValidationEventHandler}
! * returns false from its <tt>handleEvent</tt> method or the
! * <tt>Validator</tt> is unable to validate the content tree rooted
! * at <tt>subrootObj</tt>
* @throws IllegalArgumentException
* If the subrootObj parameter is null
! * @return true if the subtree rooted at <tt>subrootObj</tt> is valid, false
* otherwise
* @deprecated since JAXB2.0
*/
public boolean validate( Object subrootObj ) throws JAXBException;
/**
! * Validate the Java content tree rooted at <tt>rootObj</tt>.
* <p>
* 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 <b>will</b> be performed as
* part of this operation (i.e. ID/IDREF constraints).
*
* @param rootObj the root obj to begin validation at
* @throws JAXBException if any unexpected problem occurs during validation
* @throws ValidationException
* If the {@link ValidationEventHandler ValidationEventHandler}
! * returns false from its <tt>handleEvent</tt> method or the
! * <tt>Validator</tt> is unable to validate the content tree rooted
! * at <tt>rootObj</tt>
* @throws IllegalArgumentException
* If the rootObj parameter is null
! * @return true if the tree rooted at <tt>rootObj</tt> is valid, false
* otherwise
* @deprecated since JAXB2.0
*/
public boolean validateRoot( Object rootObj ) throws JAXBException;
/**
* Set the particular property in the underlying implementation of
! * <tt>Validator</tt>. This method can only be used to set one of
* the standard JAXB defined properties above or a provider specific
* property. Attempting to set an undefined property will result in
* a PropertyException being thrown. See <a href="#supportedProps">
* Supported Properties</a>.
*
--- 193,250 ----
*/
public ValidationEventHandler getEventHandler()
throws JAXBException;
/**
! * Validate the Java content tree starting at {@code subrootObj}.
* <p>
* 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 <b>will not
* </b> be performed as part of this operation (i.e. ID/IDREF constraints).
*
* @param subrootObj the obj to begin validation at
* @throws JAXBException if any unexpected problem occurs during validation
* @throws ValidationException
* If the {@link ValidationEventHandler ValidationEventHandler}
! * returns false from its {@code handleEvent} method or the
! * {@code Validator} is unable to validate the content tree rooted
! * at {@code subrootObj}
* @throws IllegalArgumentException
* If the subrootObj parameter is null
! * @return true if the subtree rooted at {@code subrootObj} is valid, false
* otherwise
* @deprecated since JAXB2.0
*/
public boolean validate( Object subrootObj ) throws JAXBException;
/**
! * Validate the Java content tree rooted at {@code rootObj}.
* <p>
* 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 <b>will</b> be performed as
* part of this operation (i.e. ID/IDREF constraints).
*
* @param rootObj the root obj to begin validation at
* @throws JAXBException if any unexpected problem occurs during validation
* @throws ValidationException
* If the {@link ValidationEventHandler ValidationEventHandler}
! * returns false from its {@code handleEvent} method or the
! * {@code Validator} is unable to validate the content tree rooted
! * at {@code rootObj}
* @throws IllegalArgumentException
* If the rootObj parameter is null
! * @return true if the tree rooted at {@code rootObj} is valid, false
* otherwise
* @deprecated since JAXB2.0
*/
public boolean validateRoot( Object rootObj ) throws JAXBException;
/**
* Set the particular property in the underlying implementation of
! * {@code Validator}. This method can only be used to set one of
* the standard JAXB defined properties above or a provider specific
* property. Attempting to set an undefined property will result in
* a PropertyException being thrown. See <a href="#supportedProps">
* Supported Properties</a>.
*
*** 262,272 ****
public void setProperty( String name, Object value )
throws PropertyException;
/**
* Get the particular property in the underlying implementation of
! * <tt>Validator</tt>. This method can only be used to get one of
* the standard JAXB defined properties above or a provider specific
* property. Attempting to get an undefined property will result in
* a PropertyException being thrown. See <a href="#supportedProps">
* Supported Properties</a>.
*
--- 262,272 ----
public void setProperty( String name, Object value )
throws PropertyException;
/**
* Get the particular property in the underlying implementation of
! * {@code Validator}. This method can only be used to get one of
* the standard JAXB defined properties above or a provider specific
* property. Attempting to get an undefined property will result in
* a PropertyException being thrown. See <a href="#supportedProps">
* Supported Properties</a>.
*
< prev index next >