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