1 /*

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

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

     4  *

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

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

     7  * published by the Free Software Foundation.  Oracle designates this

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

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

    10  *

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

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

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

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

    15  * accompanied this code).

    16  *

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

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

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

    20  *

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

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

    23  * questions.

    24  */

    25 

    26 package javax.xml.bind;

    27 

    28 /**

    29  * A basic event handler interface for validation errors.

    30  *

    31  * <p>

    32  * If an application needs to implement customized event handling, it must

    33  * implement this interface and then register it with either the

    34  * {@link Unmarshaller#setEventHandler(ValidationEventHandler) Unmarshaller},

    35  * the {@link Validator#setEventHandler(ValidationEventHandler) Validator}, or

    36  * the {@link Marshaller#setEventHandler(ValidationEventHandler) Marshaller}.

    37  * The JAXB Provider will then report validation errors and warnings encountered

    38  * during the unmarshal, marshal, and validate operations to these event

    39  * handlers.

    40  *

    41  * <p>

    42  * If the <tt>handleEvent</tt> method throws an unchecked runtime exception,

    43  * the JAXB Provider must treat that as if the method returned false, effectively

    44  * terminating whatever operation was in progress at the time (unmarshal,

    45  * validate, or marshal).

    46  *

    47  * <p>

    48  * Modifying the Java content tree within your event handler is undefined

    49  * by the specification and may result in unexpected behaviour.

    50  *

    51  * <p>

    52  * Failing to return false from the <tt>handleEvent</tt> method after

    53  * encountering a fatal error is undefined by the specification and may result

    54  * in unexpected behavior.

    55  *

    56  * <p>

    57  * <b>Default Event Handler</b>

    58  * <blockquote>

    59  *    See: <a href="Validator.html#defaulthandler">Validator javadocs</a>

    60  * </blockquote>

    61  *

    62  * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>

    63  * @see Unmarshaller

    64  * @see Validator

    65  * @see Marshaller

    66  * @see ValidationEvent

    67  * @see javax.xml.bind.util.ValidationEventCollector

    68  * @since 1.6, JAXB 1.0

    69  */

    70 public interface ValidationEventHandler {

    71     /**

    72      * Receive notification of a validation warning or error.

    73      *

    74      * The ValidationEvent will have a

    75      * {@link ValidationEventLocator ValidationEventLocator} embedded in it that

    76      * indicates where the error or warning occurred.

    77      *

    78      * <p>

    79      * If an unchecked runtime exception is thrown from this method, the JAXB

    80      * provider will treat it as if the method returned false and interrupt

    81      * the current unmarshal, validate, or marshal operation.

    82      *

    83      * @param event the encapsulated validation event information.  It is a

    84      * provider error if this parameter is null.

    85      * @return true if the JAXB Provider should attempt to continue the current

    86      *         unmarshal, validate, or marshal operation after handling this

    87      *         warning/error, false if the provider should terminate the current

    88      *         operation with the appropriate <tt>UnmarshalException</tt>,

    89      *         <tt>ValidationException</tt>, or <tt>MarshalException</tt>.

    90      * @throws IllegalArgumentException if the event object is null.

    91      */

    92     public boolean handleEvent( ValidationEvent event );

    93 

    94 }