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 * As of JAXB 2.0, this class is deprecated and optional. 30 * <p> 31 * The <tt>Validator</tt> class is responsible for controlling the validation 32 * of content trees during runtime. 33 * 34 * <p> 35 * <a name="validationtypes"></a> 36 * <b>Three Forms of Validation</b><br> 37 * <blockquote> 38 * <dl> 39 * <dt><b>Unmarshal-Time Validation</b></dt> 40 * <dd>This form of validation enables a client application to receive 41 * information about validation errors and warnings detected while 42 * unmarshalling XML data into a Java content tree and is completely 43 * orthogonal to the other types of validation. To enable or disable 44 * it, see the javadoc for 45 * {@link Unmarshaller#setValidating(boolean) Unmarshaller.setValidating}. 46 * All JAXB 1.0 Providers are required to support this operation. 47 * </dd> 48 * 49 * <dt><b>On-Demand Validation</b></dt> 50 * <dd> This form of validation enables a client application to receive 51 * information about validation errors and warnings detected in the 52 * Java content tree. At any point, client applications can call 53 * the {@link Validator#validate(Object) Validator.validate} method 54 * on the Java content tree (or any sub-tree of it). All JAXB 1.0 55 * Providers are required to support this operation. 56 * </dd> 57 * 58 * <dt><b>Fail-Fast Validation</b></dt> 59 * <dd> This form of validation enables a client application to receive 60 * immediate feedback about modifications to the Java content tree 61 * that violate type constraints on Java Properties as defined in 62 * the specification. JAXB Providers are not required support 63 * this type of validation. Of the JAXB Providers that do support 64 * this type of validation, some may require you to decide at schema 65 * compile time whether or not a client application will be allowed 66 * to request fail-fast validation at runtime. 67 * </dd> 68 * </dl> 69 * </blockquote> 70 * 71 * <p> 72 * The <tt>Validator</tt> class is responsible for managing On-Demand Validation. 73 * The <tt>Unmarshaller</tt> class is responsible for managing Unmarshal-Time 74 * Validation during the unmarshal operations. Although there is no formal 75 * method of enabling validation during the marshal operations, the 76 * <tt>Marshaller</tt> may detect errors, which will be reported to the 77 * <tt>ValidationEventHandler</tt> registered on it. 78 * 79 * <p> 80 * <a name="defaulthandler"></a> 81 * <b>Using the Default EventHandler</b><br> 82 * <blockquote> 83 * If the client application does not set an event handler on their 84 * <tt>Validator</tt>, <tt>Unmarshaller</tt>, or <tt>Marshaller</tt> prior to 85 * calling the validate, unmarshal, or marshal methods, then a default event 86 * handler will receive notification of any errors or warnings encountered. 87 * The default event handler will cause the current operation to halt after 88 * encountering the first error or fatal error (but will attempt to continue 89 * after receiving warnings). 90 * </blockquote> 91 * 92 * <p> 93 * <a name="handlingevents"></a> 94 * <b>Handling Validation Events</b><br> 95 * <blockquote> 96 * There are three ways to handle events encountered during the unmarshal, 97 * validate, and marshal operations: 98 * <dl> 99 * <dt>Use the default event handler</dt> 100 * <dd>The default event handler will be used if you do not specify one 101 * via the <tt>setEventHandler</tt> API's on <tt>Validator</tt>, 102 * <tt>Unmarshaller</tt>, or <tt>Marshaller</tt>. 103 * </dd> 104 * 105 * <dt>Implement and register a custom event handler</dt> 106 * <dd>Client applications that require sophisticated event processing 107 * can implement the <tt>ValidationEventHandler</tt> interface and 108 * register it with the <tt>Unmarshaller</tt> and/or 109 * <tt>Validator</tt>. 110 * </dd> 111 * 112 * <dt>Use the {@link javax.xml.bind.util.ValidationEventCollector ValidationEventCollector} 113 * utility</dt> 114 * <dd>For convenience, a specialized event handler is provided that 115 * simply collects any <tt>ValidationEvent</tt> objects created 116 * during the unmarshal, validate, and marshal operations and 117 * returns them to the client application as a 118 * <tt>java.util.Collection</tt>. 119 * </dd> 120 * </dl> 121 * </blockquote> 122 * 123 * <p> 124 * <b>Validation and Well-Formedness</b><br> 125 * <blockquote> 126 * <p> 127 * Validation events are handled differently depending on how the client 128 * application is configured to process them as described in the previous 129 * section. However, there are certain cases where a JAXB Provider indicates 130 * that it is no longer able to reliably detect and report errors. In these 131 * cases, the JAXB Provider will set the severity of the ValidationEvent to 132 * FATAL_ERROR to indicate that the unmarshal, validate, or marshal operations 133 * should be terminated. The default event handler and 134 * <tt>ValidationEventCollector</tt> utility class must terminate processing 135 * after being notified of a fatal error. Client applications that supply their 136 * own <tt>ValidationEventHandler</tt> should also terminate processing after 137 * being notified of a fatal error. If not, unexpected behaviour may occur. 138 * </blockquote> 139 * 140 * <p> 141 * <a name="supportedProps"></a> 142 * <b>Supported Properties</b><br> 143 * <blockquote> 144 * <p> 145 * There currently are not any properties required to be supported by all 146 * JAXB Providers on Validator. However, some providers may support 147 * their own set of provider specific properties. 148 * </blockquote> 149 * 150 * 151 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 152 * @see JAXBContext 153 * @see Unmarshaller 154 * @see ValidationEventHandler 155 * @see ValidationEvent 156 * @see javax.xml.bind.util.ValidationEventCollector 157 * @since 1.6, JAXB 1.0 158 * @deprecated since JAXB 2.0 159 */ 160 public interface Validator { 161 162 /** 163 * Allow an application to register a validation event handler. 164 * <p> 165 * The validation event handler will be called by the JAXB Provider if any 166 * validation errors are encountered during calls to 167 * {@link #validate(Object) validate}. If the client application does not 168 * register a validation event handler before invoking the validate method, 169 * then validation events will be handled by the default event handler which 170 * will terminate the validate operation after the first error or fatal error 171 * is encountered. 172 * <p> 173 * Calling this method with a null parameter will cause the Validator 174 * to revert back to the default default event handler. 175 * 176 * @param handler the validation event handler 177 * @throws JAXBException if an error was encountered while setting the 178 * event handler 179 * @deprecated since JAXB2.0 180 */ 181 public void setEventHandler( ValidationEventHandler handler ) 182 throws JAXBException; 183 184 /** 185 * Return the current event handler or the default event handler if one 186 * hasn't been set. 187 * 188 * @return the current ValidationEventHandler or the default event handler 189 * if it hasn't been set 190 * @throws JAXBException if an error was encountered while getting the 191 * current event handler 192 * @deprecated since JAXB2.0 193 */ 194 public ValidationEventHandler getEventHandler() 195 throws JAXBException; 196 197 /** 198 * Validate the Java content tree starting at <tt>subrootObj</tt>. 199 * <p> 200 * Client applications can use this method to validate Java content trees 201 * on-demand at runtime. This method can be used to validate any arbitrary 202 * subtree of the Java content tree. Global constraint checking <b>will not 203 * </b> be performed as part of this operation (i.e. ID/IDREF constraints). 204 * 205 * @param subrootObj the obj to begin validation at 206 * @throws JAXBException if any unexpected problem occurs during validation 207 * @throws ValidationException 208 * If the {@link ValidationEventHandler ValidationEventHandler} 209 * returns false from its <tt>handleEvent</tt> method or the 210 * <tt>Validator</tt> is unable to validate the content tree rooted 211 * at <tt>subrootObj</tt> 212 * @throws IllegalArgumentException 213 * If the subrootObj parameter is null 214 * @return true if the subtree rooted at <tt>subrootObj</tt> is valid, false 215 * otherwise 216 * @deprecated since JAXB2.0 217 */ 218 public boolean validate( Object subrootObj ) throws JAXBException; 219 220 /** 221 * Validate the Java content tree rooted at <tt>rootObj</tt>. 222 * <p> 223 * Client applications can use this method to validate Java content trees 224 * on-demand at runtime. This method is used to validate an entire Java 225 * content tree. Global constraint checking <b>will</b> be performed as 226 * part of this operation (i.e. ID/IDREF constraints). 227 * 228 * @param rootObj the root obj to begin validation at 229 * @throws JAXBException if any unexpected problem occurs during validation 230 * @throws ValidationException 231 * If the {@link ValidationEventHandler ValidationEventHandler} 232 * returns false from its <tt>handleEvent</tt> method or the 233 * <tt>Validator</tt> is unable to validate the content tree rooted 234 * at <tt>rootObj</tt> 235 * @throws IllegalArgumentException 236 * If the rootObj parameter is null 237 * @return true if the tree rooted at <tt>rootObj</tt> is valid, false 238 * otherwise 239 * @deprecated since JAXB2.0 240 */ 241 public boolean validateRoot( Object rootObj ) throws JAXBException; 242 243 /** 244 * Set the particular property in the underlying implementation of 245 * <tt>Validator</tt>. This method can only be used to set one of 246 * the standard JAXB defined properties above or a provider specific 247 * property. Attempting to set 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 be set. This value can either 252 * be specified using one of the constant fields or a user 253 * supplied string. 254 * @param value the value of the property to be set 255 * 256 * @throws PropertyException when there is an error processing the given 257 * property or value 258 * @throws IllegalArgumentException 259 * If the name parameter is null 260 * @deprecated since JAXB2.0 261 */ 262 public void setProperty( String name, Object value ) 263 throws PropertyException; 264 265 /** 266 * Get the particular property in the underlying implementation of 267 * <tt>Validator</tt>. This method can only be used to get one of 268 * the standard JAXB defined properties above or a provider specific 269 * property. Attempting to get an undefined property will result in 270 * a PropertyException being thrown. See <a href="#supportedProps"> 271 * Supported Properties</a>. 272 * 273 * @param name the name of the property to retrieve 274 * @return the value of the requested property 275 * 276 * @throws PropertyException 277 * when there is an error retrieving the given property or value 278 * property name 279 * @throws IllegalArgumentException 280 * If the name parameter is null 281 * @deprecated since JAXB2.0 282 */ 283 public Object getProperty( String name ) throws PropertyException; 284 285 }