/*
 * Copyright (c) 2003, 2020 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0, which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package jakarta.xml.bind;

/**
 * As of Jakarta XML Binding, this class is deprecated and optional.
 * <p>
 * The {@code Validator} class is responsible for controlling the validation
 * of content trees during runtime.
 *
 * <p>
 * <a id="validationtypes"></a>
 * <b>Three Forms of Validation</b><br>
 * <blockquote>
 *    <dl>
 *        <dt><b>Unmarshal-Time Validation</b></dt>
 *        <dd>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 
 *            {@link Unmarshaller#setValidating(boolean) Unmarshaller.setValidating}.
 *            All JAXB 1.0 Providers are required to support this operation.
 *        </dd>
 *
 *        <dt><b>On-Demand Validation</b></dt>
 *        <dd> 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 {@link Validator#validate(Object) Validator.validate} method
 *             on the Java content tree (or any sub-tree of it).  All JAXB 1.0
 *             Providers are required to support this operation.
 *        </dd>
 *
 *        <dt><b>Fail-Fast Validation</b></dt>
 *        <dd> 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.  Jakarta XML Binding Providers are not required support
 *             this type of validation.  Of the Jakarta XML Binding 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.
 *        </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 id="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).
 * </blockquote>
 *
 * <p>
 * <a id="handlingevents"></a>
 * <b>Handling Validation Events</b><br>
 * <blockquote>
 *   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 jakarta.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>
 * <b>Validation and Well-Formedness</b><br>
 * <blockquote>
 * <p>
 * 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 Jakarta XML Binding Provider indicates
 * that it is no longer able to reliably detect and report errors.  In these
 * cases, the Jakarta XML Binding 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 id="supportedProps"></a>
 * <b>Supported Properties</b><br>
 * <blockquote>
 * <p>
 * There currently are not any properties required to be supported by all 
 * Jakarta XML Binding Providers on Validator.  However, some providers may support 
 * their own set of provider specific properties.
 * </blockquote>
 * 
 * 
 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 
 * @see JAXBContext
 * @see Unmarshaller
 * @see ValidationEventHandler
 * @see ValidationEvent
 * @see jakarta.xml.bind.util.ValidationEventCollector
 * @since 1.6, JAXB 1.0
 * @deprecated since JAXB 2.0
 */
public interface Validator {

    /**
     * Allow an application to register a validation event handler.
     * <p>
     * The validation event handler will be called by the Jakarta XML Binding Provider if any
     * validation errors are encountered during calls to 
     * {@link #validate(Object) 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.
     * <p>
     * Calling this method with a null parameter will cause the Validator
     * to revert back to the default default event handler.
     *
     * @param handler the validation event handler
     * @throws JAXBException if an error was encountered while setting the
     *         event handler
     * @deprecated since JAXB2.0
     */
    public void setEventHandler( ValidationEventHandler handler )
        throws JAXBException;

    /**
     * Return the current event handler or the default event handler if one
     * hasn't been set.
     *
     * @return 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
     * @deprecated since JAXB2.0
     */
    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 Jakarta XML Binding 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>.
     *
     * @param name the name of the property to be set. This value can either
     *              be specified using one of the constant fields or a user 
     *              supplied string.
     * @param value the value of the property to be set
     *
     * @throws PropertyException when there is an error processing the given
     *                            property or value
     * @throws IllegalArgumentException
     *      If the name parameter is null
     * @deprecated since JAXB2.0
     */
    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 Jakarta XML Binding 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>.
     *
     * @param name the name of the property to retrieve
     * @return the value of the requested property
     *
     * @throws PropertyException
     *      when there is an error retrieving the given property or value
     *      property name
     * @throws IllegalArgumentException
     *      If the name parameter is null
     * @deprecated since JAXB2.0
     */
    public Object getProperty( String name ) throws PropertyException;
    
}
