1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/javax/xml/bind/Validator.java Wed Apr 27 01:27:09 2016 +0800
1.3 @@ -0,0 +1,285 @@
1.4 +/*
1.5 + * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package javax.xml.bind;
1.30 +
1.31 +/**
1.32 + * As of JAXB 2.0, this class is deprecated and optional.
1.33 + * <p>
1.34 + * The <tt>Validator</tt> class is responsible for controlling the validation
1.35 + * of content trees during runtime.
1.36 + *
1.37 + * <p>
1.38 + * <a name="validationtypes"></a>
1.39 + * <b>Three Forms of Validation</b><br>
1.40 + * <blockquote>
1.41 + * <dl>
1.42 + * <dt><b>Unmarshal-Time Validation</b></dt>
1.43 + * <dd>This form of validation enables a client application to receive
1.44 + * information about validation errors and warnings detected while
1.45 + * unmarshalling XML data into a Java content tree and is completely
1.46 + * orthogonal to the other types of validation. To enable or disable
1.47 + * it, see the javadoc for
1.48 + * {@link Unmarshaller#setValidating(boolean) Unmarshaller.setValidating}.
1.49 + * All JAXB 1.0 Providers are required to support this operation.
1.50 + * </dd>
1.51 + *
1.52 + * <dt><b>On-Demand Validation</b></dt>
1.53 + * <dd> This form of validation enables a client application to receive
1.54 + * information about validation errors and warnings detected in the
1.55 + * Java content tree. At any point, client applications can call
1.56 + * the {@link Validator#validate(Object) Validator.validate} method
1.57 + * on the Java content tree (or any sub-tree of it). All JAXB 1.0
1.58 + * Providers are required to support this operation.
1.59 + * </dd>
1.60 + *
1.61 + * <dt><b>Fail-Fast Validation</b></dt>
1.62 + * <dd> This form of validation enables a client application to receive
1.63 + * immediate feedback about modifications to the Java content tree
1.64 + * that violate type constraints on Java Properties as defined in
1.65 + * the specification. JAXB Providers are not required support
1.66 + * this type of validation. Of the JAXB Providers that do support
1.67 + * this type of validation, some may require you to decide at schema
1.68 + * compile time whether or not a client application will be allowed
1.69 + * to request fail-fast validation at runtime.
1.70 + * </dd>
1.71 + * </dl>
1.72 + * </blockquote>
1.73 + *
1.74 + * <p>
1.75 + * The <tt>Validator</tt> class is responsible for managing On-Demand Validation.
1.76 + * The <tt>Unmarshaller</tt> class is responsible for managing Unmarshal-Time
1.77 + * Validation during the unmarshal operations. Although there is no formal
1.78 + * method of enabling validation during the marshal operations, the
1.79 + * <tt>Marshaller</tt> may detect errors, which will be reported to the
1.80 + * <tt>ValidationEventHandler</tt> registered on it.
1.81 + *
1.82 + * <p>
1.83 + * <a name="defaulthandler"></a>
1.84 + * <b>Using the Default EventHandler</b><br>
1.85 + * <blockquote>
1.86 + * If the client application does not set an event handler on their
1.87 + * <tt>Validator</tt>, <tt>Unmarshaller</tt>, or <tt>Marshaller</tt> prior to
1.88 + * calling the validate, unmarshal, or marshal methods, then a default event
1.89 + * handler will receive notification of any errors or warnings encountered.
1.90 + * The default event handler will cause the current operation to halt after
1.91 + * encountering the first error or fatal error (but will attempt to continue
1.92 + * after receiving warnings).
1.93 + * </blockquote>
1.94 + *
1.95 + * <p>
1.96 + * <a name="handlingevents"></a>
1.97 + * <b>Handling Validation Events</b><br>
1.98 + * <blockquote>
1.99 + * There are three ways to handle events encountered during the unmarshal,
1.100 + * validate, and marshal operations:
1.101 + * <dl>
1.102 + * <dt>Use the default event handler</dt>
1.103 + * <dd>The default event handler will be used if you do not specify one
1.104 + * via the <tt>setEventHandler</tt> API's on <tt>Validator</tt>,
1.105 + * <tt>Unmarshaller</tt>, or <tt>Marshaller</tt>.
1.106 + * </dd>
1.107 + *
1.108 + * <dt>Implement and register a custom event handler</dt>
1.109 + * <dd>Client applications that require sophisticated event processing
1.110 + * can implement the <tt>ValidationEventHandler</tt> interface and
1.111 + * register it with the <tt>Unmarshaller</tt> and/or
1.112 + * <tt>Validator</tt>.
1.113 + * </dd>
1.114 + *
1.115 + * <dt>Use the {@link javax.xml.bind.util.ValidationEventCollector ValidationEventCollector}
1.116 + * utility</dt>
1.117 + * <dd>For convenience, a specialized event handler is provided that
1.118 + * simply collects any <tt>ValidationEvent</tt> objects created
1.119 + * during the unmarshal, validate, and marshal operations and
1.120 + * returns them to the client application as a
1.121 + * <tt>java.util.Collection</tt>.
1.122 + * </dd>
1.123 + * </dl>
1.124 + * </blockquote>
1.125 + *
1.126 + * <p>
1.127 + * <b>Validation and Well-Formedness</b><br>
1.128 + * <blockquote>
1.129 + * <p>
1.130 + * Validation events are handled differently depending on how the client
1.131 + * application is configured to process them as described in the previous
1.132 + * section. However, there are certain cases where a JAXB Provider indicates
1.133 + * that it is no longer able to reliably detect and report errors. In these
1.134 + * cases, the JAXB Provider will set the severity of the ValidationEvent to
1.135 + * FATAL_ERROR to indicate that the unmarshal, validate, or marshal operations
1.136 + * should be terminated. The default event handler and
1.137 + * <tt>ValidationEventCollector</tt> utility class must terminate processing
1.138 + * after being notified of a fatal error. Client applications that supply their
1.139 + * own <tt>ValidationEventHandler</tt> should also terminate processing after
1.140 + * being notified of a fatal error. If not, unexpected behaviour may occur.
1.141 + * </blockquote>
1.142 + *
1.143 + * <p>
1.144 + * <a name="supportedProps"></a>
1.145 + * <b>Supported Properties</b><br>
1.146 + * <blockquote>
1.147 + * <p>
1.148 + * There currently are not any properties required to be supported by all
1.149 + * JAXB Providers on Validator. However, some providers may support
1.150 + * their own set of provider specific properties.
1.151 + * </blockquote>
1.152 + *
1.153 + *
1.154 + * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
1.155 + * @see JAXBContext
1.156 + * @see Unmarshaller
1.157 + * @see ValidationEventHandler
1.158 + * @see ValidationEvent
1.159 + * @see javax.xml.bind.util.ValidationEventCollector
1.160 + * @since JAXB1.0
1.161 + * @deprecated since JAXB 2.0
1.162 + */
1.163 +public interface Validator {
1.164 +
1.165 + /**
1.166 + * Allow an application to register a validation event handler.
1.167 + * <p>
1.168 + * The validation event handler will be called by the JAXB Provider if any
1.169 + * validation errors are encountered during calls to
1.170 + * {@link #validate(Object) validate}. If the client application does not
1.171 + * register a validation event handler before invoking the validate method,
1.172 + * then validation events will be handled by the default event handler which
1.173 + * will terminate the validate operation after the first error or fatal error
1.174 + * is encountered.
1.175 + * <p>
1.176 + * Calling this method with a null parameter will cause the Validator
1.177 + * to revert back to the default default event handler.
1.178 + *
1.179 + * @param handler the validation event handler
1.180 + * @throws JAXBException if an error was encountered while setting the
1.181 + * event handler
1.182 + * @deprecated since JAXB2.0
1.183 + */
1.184 + public void setEventHandler( ValidationEventHandler handler )
1.185 + throws JAXBException;
1.186 +
1.187 + /**
1.188 + * Return the current event handler or the default event handler if one
1.189 + * hasn't been set.
1.190 + *
1.191 + * @return the current ValidationEventHandler or the default event handler
1.192 + * if it hasn't been set
1.193 + * @throws JAXBException if an error was encountered while getting the
1.194 + * current event handler
1.195 + * @deprecated since JAXB2.0
1.196 + */
1.197 + public ValidationEventHandler getEventHandler()
1.198 + throws JAXBException;
1.199 +
1.200 + /**
1.201 + * Validate the Java content tree starting at <tt>subrootObj</tt>.
1.202 + * <p>
1.203 + * Client applications can use this method to validate Java content trees
1.204 + * on-demand at runtime. This method can be used to validate any arbitrary
1.205 + * subtree of the Java content tree. Global constraint checking <b>will not
1.206 + * </b> be performed as part of this operation (i.e. ID/IDREF constraints).
1.207 + *
1.208 + * @param subrootObj the obj to begin validation at
1.209 + * @throws JAXBException if any unexpected problem occurs during validation
1.210 + * @throws ValidationException
1.211 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.212 + * returns false from its <tt>handleEvent</tt> method or the
1.213 + * <tt>Validator</tt> is unable to validate the content tree rooted
1.214 + * at <tt>subrootObj</tt>
1.215 + * @throws IllegalArgumentException
1.216 + * If the subrootObj parameter is null
1.217 + * @return true if the subtree rooted at <tt>subrootObj</tt> is valid, false
1.218 + * otherwise
1.219 + * @deprecated since JAXB2.0
1.220 + */
1.221 + public boolean validate( Object subrootObj ) throws JAXBException;
1.222 +
1.223 + /**
1.224 + * Validate the Java content tree rooted at <tt>rootObj</tt>.
1.225 + * <p>
1.226 + * Client applications can use this method to validate Java content trees
1.227 + * on-demand at runtime. This method is used to validate an entire Java
1.228 + * content tree. Global constraint checking <b>will</b> be performed as
1.229 + * part of this operation (i.e. ID/IDREF constraints).
1.230 + *
1.231 + * @param rootObj the root obj to begin validation at
1.232 + * @throws JAXBException if any unexpected problem occurs during validation
1.233 + * @throws ValidationException
1.234 + * If the {@link ValidationEventHandler ValidationEventHandler}
1.235 + * returns false from its <tt>handleEvent</tt> method or the
1.236 + * <tt>Validator</tt> is unable to validate the content tree rooted
1.237 + * at <tt>rootObj</tt>
1.238 + * @throws IllegalArgumentException
1.239 + * If the rootObj parameter is null
1.240 + * @return true if the tree rooted at <tt>rootObj</tt> is valid, false
1.241 + * otherwise
1.242 + * @deprecated since JAXB2.0
1.243 + */
1.244 + public boolean validateRoot( Object rootObj ) throws JAXBException;
1.245 +
1.246 + /**
1.247 + * Set the particular property in the underlying implementation of
1.248 + * <tt>Validator</tt>. This method can only be used to set one of
1.249 + * the standard JAXB defined properties above or a provider specific
1.250 + * property. Attempting to set an undefined property will result in
1.251 + * a PropertyException being thrown. See <a href="#supportedProps">
1.252 + * Supported Properties</a>.
1.253 + *
1.254 + * @param name the name of the property to be set. This value can either
1.255 + * be specified using one of the constant fields or a user
1.256 + * supplied string.
1.257 + * @param value the value of the property to be set
1.258 + *
1.259 + * @throws PropertyException when there is an error processing the given
1.260 + * property or value
1.261 + * @throws IllegalArgumentException
1.262 + * If the name parameter is null
1.263 + * @deprecated since JAXB2.0
1.264 + */
1.265 + public void setProperty( String name, Object value )
1.266 + throws PropertyException;
1.267 +
1.268 + /**
1.269 + * Get the particular property in the underlying implementation of
1.270 + * <tt>Validator</tt>. This method can only be used to get one of
1.271 + * the standard JAXB defined properties above or a provider specific
1.272 + * property. Attempting to get an undefined property will result in
1.273 + * a PropertyException being thrown. See <a href="#supportedProps">
1.274 + * Supported Properties</a>.
1.275 + *
1.276 + * @param name the name of the property to retrieve
1.277 + * @return the value of the requested property
1.278 + *
1.279 + * @throws PropertyException
1.280 + * when there is an error retrieving the given property or value
1.281 + * property name
1.282 + * @throws IllegalArgumentException
1.283 + * If the name parameter is null
1.284 + * @deprecated since JAXB2.0
1.285 + */
1.286 + public Object getProperty( String name ) throws PropertyException;
1.287 +
1.288 +}
