001 /* 002 * $Id: Validator.java,v 1.19 2002/11/21 00:21:57 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 * The <tt>Validator</tt> class is responsible for controlling the validation 015 * of content trees during runtime. 016 * 017 * <p> 018 * <a name="validationtypes"></a> 019 * <b>Three Forms of Validation</b><br> 020 * <blockquote> 021 * <dl> 022 * <dt><b>Unmarshal-Time Validation</b></dt> 023 * <dd>This form of validation enables a client application to receive 024 * information about validation errors and warnings detected while 025 * unmarshalling XML data into a Java content tree and is completely 026 * orthogonal to the other types of validation. To enable or disable 027 * it, see the javadoc for 028 * {@link Unmarshaller#setValidating(boolean) Unmarhaller.setValidating}. 029 * All JAXB Providers are required to support this operation. 030 * </dd> 031 * 032 * <dt><b>On-Demand Validation</b></dt> 033 * <dd> This form of validation enables a client application to receive 034 * information about validation errors and warnings detected in the 035 * Java content tree. At any point, client applications can call 036 * the {@link Validator#validate(Object) Validator.validate} method 037 * on the Java content tree (or any sub-tree of it). All JAXB 038 * Providers are required to support this operation. 039 * </dd> 040 * 041 * <dt><b>Fail-Fast Validation</b></dt> 042 * <dd> This form of validation enables a client application to receive 043 * immediate feedback about modifications to the Java content tree 044 * that violate type constraints on Java Properties as defined in 045 * the specification. JAXB Providers are not required support 046 * this type of validation. Of the JAXB Providers that do support 047 * this type of validation, some may require you to decide at schema 048 * compile time whether or not a client application will be allowed 049 * to request fail-fast validation at runtime. 050 * </dd> 051 * </dl> 052 * </blockquote> 053 * 054 * <p> 055 * The <tt>Validator</tt> class is responsible for managing On-Demand Validation. 056 * The <tt>Unmarshaller</tt> class is responsible for managing Unmarshal-Time 057 * Validation during the unmarshal operations. Although there is no formal 058 * method of enabling validation during the marshal operations, the 059 * <tt>Marshaller</tt> may detect errors, which will be reported to the 060 * <tt>ValidationEventHandler</tt> registered on it. 061 * 062 * <p> 063 * <a name="defaulthandler"></a> 064 * <b>Using the Default EventHandler</b><br> 065 * <blockquote> 066 * If the client application does not set an event handler on their 067 * <tt>Validator</tt>, <tt>Unmarshaller</tt>, or <tt>MArshaller</tt> prior to 068 * calling the validate, unmarshal, or marshal methods, then a default event 069 * handler will receive notification of any errors or warnings encountered. 070 * The default event handler will cause the current operation to halt after 071 * encountering the first error or fatal error (but will attempt to continue 072 * after receiving warnings). 073 * </blockquote> 074 * 075 * <p> 076 * <a name="handlingevents"></a> 077 * <b>Handling Validation Events</b><br> 078 * <blockquote> 079 * There are three ways to handle events encountered during the unmarshal, 080 * validate, and marshal operations: 081 * <dl> 082 * <dt>Use the default event handler</dt> 083 * <dd>The default event handler will be used if you do not specify one 084 * via the <tt>setEventHandler</tt> API's on <tt>Validator</tt>, 085 * <tt>Unmarshaller</tt>, or <tt>Marshaller</tt>. 086 * </dd> 087 * 088 * <dt>Implement and register a custom event handler</dt> 089 * <dd>Client applications that require sophisticated event processing 090 * can implement the <tt>ValidationEventHandler</tt> interface and 091 * register it with the <tt>Unmarshaller</tt> and/or 092 * <tt>Validator</tt>. 093 * </dd> 094 * 095 * <dt>Use the {@link javax.xml.bind.util.ValidationEventCollector ValidationEventCollector} 096 * utility</dt> 097 * <dd>For convenience, a specialized event handler is provided that 098 * simply collects any <tt>ValidationEvent</tt> objects created 099 * during the unmarshal, validate, and marshal operations and 100 * returns them to the client application as a 101 * <tt>java.util.Collection</tt>. 102 * </dd> 103 * </dl> 104 * </blockquote> 105 * 106 * <p> 107 * <b>Validation and Well-Formedness</b><br> 108 * <blockquote> 109 * <p> 110 * Validation events are handled differently depending on how the client 111 * application is configured to process them as described in the previous 112 * section. However, there are certain cases where a JAXB Provider indicates 113 * that it is no longer able to reliably detect and report errors. In these 114 * cases, the JAXB Provider will set the severity of the ValidationEvent to 115 * FATAL_ERROR to indicate that the unmarshal, validate, or marshal operations 116 * should be terminated. The default event handler and 117 * <tt>ValidationEventCollector</tt> utility class must terminate processing 118 * after being notified of a fatal error. Client applications that supply their 119 * own <tt>ValidationEventHandler</tt> should also terminate processing after 120 * being notified of a fatal error. If not, unexpected behaviour may occur. 121 * </blockquote> 122 * 123 * <p> 124 * <a name="supportedProps"></a> 125 * <b>Supported Properties</b><br> 126 * <blockquote> 127 * <p> 128 * There currently are not any properties required to be supported by all 129 * JAXB Providers on Validator. However, some providers may support 130 * their own set of provider specific properties. 131 * </blockquote> 132 * 133 * 134 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 135 * @version $Revision: 1.19 $ $Date: 2002/11/21 00:21:57 $ 136 * @see JAXBContext 137 * @see Unmarshaller 138 * @see ValidationEventHandler 139 * @see ValidationEvent 140 * @see javax.xml.bind.util.ValidationEventCollector 141 * @since JAXB1.0 142 */ 143 public interface Validator { 144 145 /** 146 * Allow an application to register a validation event handler. 147 * <p> 148 * The validation event handler will be called by the JAXB Provider if any 149 * validation errors are encountered during calls to 150 * {@link #validate(Object) validate}. If the client application does not 151 * register a validation event handler before invoking the validate method, 152 * then validation events will be handled by the default event handler which 153 * will terminate the validate operation after the first error or fatal error 154 * is encountered. 155 * <p> 156 * Calling this method with a null parameter will cause the Validator 157 * to revert back to the default vefault event handler. 158 * 159 * @param handler the validation event handler 160 * @throws JAXBException if an error was encountered while setting the 161 * event handler 162 */ 163 public void setEventHandler( ValidationEventHandler handler ) 164 throws JAXBException; 165 166 /** 167 * Return the current event handler or the default event handler if one 168 * hasn't been set. 169 * 170 * @return the current ValidationEventHandler or the default event handler 171 * if it hasn't been set 172 * @throws JAXBException if an error was encountered while getting the 173 * current event handler 174 */ 175 public ValidationEventHandler getEventHandler() 176 throws JAXBException; 177 178 /** 179 * Validate the Java content tree starting at <tt>subrootObj</tt>. 180 * <p> 181 * Client applications can use this method to validate Java content trees 182 * on-demand at runtime. This method can be used to validate any arbitrary 183 * subtree of the Java content tree. Global constraint checking <b>will not 184 * </b> be performed as part of this operation (i.e. ID/IDREF constraints). 185 * 186 * @param subrootObj the obj to begin validation at 187 * @throws JAXBException if any unexpected problem occurs during validation 188 * @throws ValidationException 189 * If the {@link ValidationEventHandler ValidationEventHandler} 190 * returns false from its <tt>handleEvent</tt> method or the 191 * <tt>Validator</tt> is unable to validate the content tree rooted 192 * at <tt>subrootObj</tt> 193 * @throws IllegalArgumentException 194 * If the subrootObj parameter is null 195 * @return true if the subtree rooted at <tt>subrootObj</tt> is valid, false 196 * otherwise 197 */ 198 public boolean validate( Object subrootObj ) throws JAXBException; 199 200 /** 201 * Validate the Java content tree rooted at <tt>rootObj</tt>. 202 * <p> 203 * Client applications can use this method to validate Java content trees 204 * on-demand at runtime. This method is used to validate an entire Java 205 * content tree. Global constraint checking <b>will</b> be performed as 206 * part of this operation (i.e. ID/IDREF constraints). 207 * 208 * @param rootObj the root obj to begin validation at 209 * @throws JAXBException if any unexpected problem occurs during validation 210 * @throws ValidationException 211 * If the {@link ValidationEventHandler ValidationEventHandler} 212 * returns false from its <tt>handleEvent</tt> method or the 213 * <tt>Validator</tt> is unable to validate the content tree rooted 214 * at <tt>rootObj</tt> 215 * @throws IllegalArgumentException 216 * If the rootObj parameter is null 217 * @return true if the tree rooted at <tt>rootObj</tt> is valid, false 218 * otherwise 219 */ 220 public boolean validateRoot( Object rootObj ) throws JAXBException; 221 222 /** 223 * Set the particular property in the underlying implementation of 224 * <tt>Validator</tt>. This method can only be used to set one of 225 * the standard JAXB defined properties above or a provider specific 226 * property. Attempting to set an undefined property will result in 227 * a PropertyException being thrown. See <a href="#supportedProps"> 228 * Supported Properties</a>. 229 * 230 * @param name the name of the property to be set. This value can either 231 * be specified using one of the constant fields or a user 232 * supplied string. 233 * @param value the value of the property to be set 234 * 235 * @throws PropertyException when there is an error processing the given 236 * property or value 237 * @throws IllegalArgumentException 238 * If the name parameter is null 239 */ 240 public void setProperty( String name, Object value ) 241 throws PropertyException; 242 243 /** 244 * Get the particular property in the underlying implementation of 245 * <tt>Validator</tt>. This method can only be used to get one of 246 * the standard JAXB defined properties above or a provider specific 247 * property. Attempting to get an undefined property will result in 248 * a PropertyException being thrown. See <a href="#supportedProps"> 249 * Supported Properties</a>. 250 * 251 * @param name the name of the property to retrieve 252 * @return the value of the requested property 253 * 254 * @throws PropertyException 255 * when there is an error retrieving the given property or value 256 * property name 257 * @throws IllegalArgumentException 258 * If the name parameter is null 259 */ 260 public Object getProperty( String name ) throws PropertyException; 261 262 }