01: /*
02: * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
03: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
04: */
05:
06: package javax.xml.bind;
07:
08: /**
09: * 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.1 $
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: }
|