/*

 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

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>

 * <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.  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.

 *        </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).

 * </blockquote>

 *

 * <p>

 * <a name="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 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>

 * <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 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>

 * <b>Supported Properties</b><br>

 * <blockquote>

 * <p>

 * There currently are not any properties required to be supported by all

 * JAXB 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 javax.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 JAXB 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 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>.

     *

     * @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 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>.

     *

     * @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;

}