KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > bind > ValidationEventHandler


1 /*
2  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
3  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4  */
5
6 package javax.xml.bind;
7
8 /**
9  * A basic event handler interface for validation errors.
10  *
11  * <p>
12  * If an application needs to implement customized event handling, it must
13  * implement this interface and then register it with either the
14  * {@link Unmarshaller#setEventHandler(ValidationEventHandler) Unmarshaller},
15  * the {@link Validator#setEventHandler(ValidationEventHandler) Validator}, or
16  * the {@link Marshaller#setEventHandler(ValidationEventHandler) Marshaller}.
17  * The JAXB Provider will then report validation errors and warnings encountered
18  * during the unmarshal, marshal, and validate operations to these event
19  * handlers.
20  *
21  * <p>
22  * If the <tt>handleEvent</tt> method throws an unchecked runtime exception,
23  * the JAXB Provider must treat that as if the method returned false, effectively
24  * terminating whatever operation was in progress at the time (unmarshal,
25  * validate, or marshal).
26  *
27  * <p>
28  * Modifying the Java content tree within your event handler is undefined
29  * by the specification and may result in unexpected behaviour.
30  *
31  * <p>
32  * Failing to return false from the <tt>handleEvent</tt> method after
33  * encountering a fatal error is undefined by the specification and may result
34  * in unexpected behavior.
35  *
36  * <p>
37  * <b>Default Event Handler</b>
38  * <blockquote>
39  * See: <a HREF="Validator.html#defaulthandler">Validator javadocs</a>
40  * </blockquote>
41  *
42  * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
43  * @version $Revision: 1.2 $
44  * @see Unmarshaller
45  * @see Validator
46  * @see Marshaller
47  * @see ValidationEvent
48  * @see javax.xml.bind.util.ValidationEventCollector
49  * @since JAXB1.0
50  */
51 public interface ValidationEventHandler {
52     /**
53      * Receive notification of a validation warning or error.
54      *
55      * The ValidationEvent will have a
56      * {@link ValidationEventLocator ValidationEventLocator} embedded in it that
57      * indicates where the error or warning occurred.
58      *
59      * <p>
60      * If an unchecked runtime exception is thrown from this method, the JAXB
61      * provider will treat it as if the method returned false and interrupt
62      * the current unmarshal, validate, or marshal operation.
63      *
64      * @param event the encapsulated validation event information. It is a
65      * provider error if this parameter is null.
66      * @return true if the JAXB Provider should attempt to continue the current
67      * unmarshal, validate, or marshal operation after handling this
68      * warning/error, false if the provider should terminate the current
69      * operation with the appropriate <tt>UnmarshalException</tt>,
70      * <tt>ValidationException</tt>, or <tt>MarshalException</tt>.
71      * @throws IllegalArgumentException if the event object is null.
72      */
73     public boolean handleEvent( ValidationEvent event );
74     
75 }
76
77
Popular Tags