001    /*
002     * $Id: ValidationEventHandler.java,v 1.8 2002/11/11 18:52:20 ryans Exp $
003     *
004     * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
005     * 
006     * This software is the proprietary information of Sun Microsystems, Inc.  
007     * Use is subject to license terms.
008     * 
009     */
010    
011    package javax.xml.bind;
012    
013    /**
014     * A basic event handler interface for validation errors.
015     *
016     * <p>
017     * If an application needs to implement customized event handling, it must
018     * implement this interface and then register it with either the 
019     * {@link Unmarshaller#setEventHandler(ValidationEventHandler) Unmarshaller}, 
020     * the {@link Validator#setEventHandler(ValidationEventHandler) Validator}, or 
021     * the {@link Marshaller#setEventHandler(ValidationEventHandler) Marshaller}.  
022     * The JAXB Provider will then report validation errors and warnings encountered
023     * during the unmarshal, marshal, and validate operations to these event 
024     * handlers.
025     *
026     * <p>
027     * If the <tt>handleEvent</tt> method throws an unchecked runtime exception,
028     * the JAXB Provider must treat that as if the method returned false, effectively
029     * terminating whatever operation was in progress at the time (unmarshal, 
030     * validate, or marshal).
031     * 
032     * <p>
033     * Modifying the Java content tree within your event handler is undefined
034     * by the specification and may result in unexpected behaviour.
035     *
036     * <p>
037     * Failing to return false from the <tt>handleEvent</tt> method after 
038     * encountering a fatal error is undefined by the specification and may result 
039     * in unexpected behavior.
040     *
041     * <p>
042     * <b>Default Event Handler</b>
043     * <blockquote>
044     *    See: <a href="Validator.html#defaulthandler">Validator javadocs</a>
045     * </blockquote>
046     *
047     * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 
048     * @version $Revision: 1.8 $
049     * @see Unmarshaller
050     * @see Validator
051     * @see Marshaller
052     * @see ValidationEvent
053     * @see javax.xml.bind.util.ValidationEventCollector
054     * @since JAXB1.0
055     */
056    public interface ValidationEventHandler {
057        /**
058         * Receive notification of a validation warning or error.  
059         * 
060         * The ValidationEvent will have a 
061         * {@link ValidationEventLocator ValidationEventLocator} embedded in it that 
062         * indicates where the error or warning occurred.
063         *
064         * <p>
065         * If an unchecked runtime exception is thrown from this method, the JAXB
066         * provider will treat it as if the method returned false and interrupt
067         * the current unmarshal, validate, or marshal operation.
068         * 
069         * @param event the encapsulated validation event information.  It is a 
070         * provider error if this parameter is null.
071         * @return true if the JAXB Provider should attempt to continue the current
072         *         unmarshal, validate, or marshal operation after handling this 
073         *         warning/error, false if the provider should terminate the current 
074         *         operation with the appropriate <tt>UnmarshalException</tt>, 
075         *         <tt>ValidationException</tt>, or <tt>MarshalException</tt>.
076         * @throws IllegalArgumentException if the event object is null.
077         */
078        public boolean handleEvent( ValidationEvent event );
079        
080    }
081