001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.bind;
027
028 /**
029 * As of JAXB 2.0, this class is deprecated and optional.
030 * <p>
031 * The <tt>Validator</tt> class is responsible for controlling the validation
032 * of content trees during runtime.
033 *
034 * <p>
035 * <a name="validationtypes"></a>
036 * <b>Three Forms of Validation</b><br>
037 * <blockquote>
038 * <dl>
039 * <dt><b>Unmarshal-Time Validation</b></dt>
040 * <dd>This form of validation enables a client application to receive
041 * information about validation errors and warnings detected while
042 * unmarshalling XML data into a Java content tree and is completely
043 * orthogonal to the other types of validation. To enable or disable
044 * it, see the javadoc for
045 * {@link Unmarshaller#setValidating(boolean) Unmarshaller.setValidating}.
046 * All JAXB 1.0 Providers are required to support this operation.
047 * </dd>
048 *
049 * <dt><b>On-Demand Validation</b></dt>
050 * <dd> This form of validation enables a client application to receive
051 * information about validation errors and warnings detected in the
052 * Java content tree. At any point, client applications can call
053 * the {@link Validator#validate(Object) Validator.validate} method
054 * on the Java content tree (or any sub-tree of it). All JAXB 1.0
055 * Providers are required to support this operation.
056 * </dd>
057 *
058 * <dt><b>Fail-Fast Validation</b></dt>
059 * <dd> This form of validation enables a client application to receive
060 * immediate feedback about modifications to the Java content tree
061 * that violate type constraints on Java Properties as defined in
062 * the specification. JAXB Providers are not required support
063 * this type of validation. Of the JAXB Providers that do support
064 * this type of validation, some may require you to decide at schema
065 * compile time whether or not a client application will be allowed
066 * to request fail-fast validation at runtime.
067 * </dd>
068 * </dl>
069 * </blockquote>
070 *
071 * <p>
072 * The <tt>Validator</tt> class is responsible for managing On-Demand Validation.
073 * The <tt>Unmarshaller</tt> class is responsible for managing Unmarshal-Time
074 * Validation during the unmarshal operations. Although there is no formal
075 * method of enabling validation during the marshal operations, the
076 * <tt>Marshaller</tt> may detect errors, which will be reported to the
077 * <tt>ValidationEventHandler</tt> registered on it.
078 *
079 * <p>
080 * <a name="defaulthandler"></a>
081 * <b>Using the Default EventHandler</b><br>
082 * <blockquote>
083 * If the client application does not set an event handler on their
084 * <tt>Validator</tt>, <tt>Unmarshaller</tt>, or <tt>Marshaller</tt> prior to
085 * calling the validate, unmarshal, or marshal methods, then a default event
086 * handler will receive notification of any errors or warnings encountered.
087 * The default event handler will cause the current operation to halt after
088 * encountering the first error or fatal error (but will attempt to continue
089 * after receiving warnings).
090 * </blockquote>
091 *
092 * <p>
093 * <a name="handlingevents"></a>
094 * <b>Handling Validation Events</b><br>
095 * <blockquote>
096 * There are three ways to handle events encountered during the unmarshal,
097 * validate, and marshal operations:
098 * <dl>
099 * <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 * @version $Revision: 1.3 $ $Date: 2005/06/06 15:04:03 $
153 * @see JAXBContext
154 * @see Unmarshaller
155 * @see ValidationEventHandler
156 * @see ValidationEvent
157 * @see javax.xml.bind.util.ValidationEventCollector
158 * @since JAXB1.0
159 * @deprecated since JAXB 2.0
160 */
161 public interface Validator {
162
163 /**
164 * Allow an application to register a validation event handler.
165 * <p>
166 * The validation event handler will be called by the JAXB Provider if any
167 * validation errors are encountered during calls to
168 * {@link #validate(Object) validate}. If the client application does not
169 * register a validation event handler before invoking the validate method,
170 * then validation events will be handled by the default event handler which
171 * will terminate the validate operation after the first error or fatal error
172 * is encountered.
173 * <p>
174 * Calling this method with a null parameter will cause the Validator
175 * to revert back to the default default event handler.
176 *
177 * @param handler the validation event handler
178 * @throws JAXBException if an error was encountered while setting the
179 * event handler
180 * @deprecated since JAXB2.0
181 */
182 public void setEventHandler(ValidationEventHandler handler)
183 throws JAXBException;
184
185 /**
186 * Return the current event handler or the default event handler if one
187 * hasn't been set.
188 *
189 * @return the current ValidationEventHandler or the default event handler
190 * if it hasn't been set
191 * @throws JAXBException if an error was encountered while getting the
192 * current event handler
193 * @deprecated since JAXB2.0
194 */
195 public ValidationEventHandler getEventHandler()
196 throws JAXBException;
197
198 /**
199 * Validate the Java content tree starting at <tt>subrootObj</tt>.
200 * <p>
201 * Client applications can use this method to validate Java content trees
202 * on-demand at runtime. This method can be used to validate any arbitrary
203 * subtree of the Java content tree. Global constraint checking <b>will not
204 * </b> be performed as part of this operation (i.e. ID/IDREF constraints).
205 *
206 * @param subrootObj the obj to begin validation at
207 * @throws JAXBException if any unexpected problem occurs during validation
208 * @throws ValidationException
209 * If the {@link ValidationEventHandler ValidationEventHandler}
210 * returns false from its <tt>handleEvent</tt> method or the
211 * <tt>Validator</tt> is unable to validate the content tree rooted
212 * at <tt>subrootObj</tt>
213 * @throws IllegalArgumentException
214 * If the subrootObj parameter is null
215 * @return true if the subtree rooted at <tt>subrootObj</tt> is valid, false
216 * otherwise
217 * @deprecated since JAXB2.0
218 */
219 public boolean validate(Object subrootObj) throws JAXBException;
220
221 /**
222 * Validate the Java content tree rooted at <tt>rootObj</tt>.
223 * <p>
224 * Client applications can use this method to validate Java content trees
225 * on-demand at runtime. This method is used to validate an entire Java
226 * content tree. Global constraint checking <b>will</b> be performed as
227 * part of this operation (i.e. ID/IDREF constraints).
228 *
229 * @param rootObj the root obj to begin validation at
230 * @throws JAXBException if any unexpected problem occurs during validation
231 * @throws ValidationException
232 * If the {@link ValidationEventHandler ValidationEventHandler}
233 * returns false from its <tt>handleEvent</tt> method or the
234 * <tt>Validator</tt> is unable to validate the content tree rooted
235 * at <tt>rootObj</tt>
236 * @throws IllegalArgumentException
237 * If the rootObj parameter is null
238 * @return true if the tree rooted at <tt>rootObj</tt> is valid, false
239 * otherwise
240 * @deprecated since JAXB2.0
241 */
242 public boolean validateRoot(Object rootObj) throws JAXBException;
243
244 /**
245 * Set the particular property in the underlying implementation of
246 * <tt>Validator</tt>. This method can only be used to set one of
247 * the standard JAXB defined properties above or a provider specific
248 * property. Attempting to set an undefined property will result in
249 * a PropertyException being thrown. See <a href="#supportedProps">
250 * Supported Properties</a>.
251 *
252 * @param name the name of the property to be set. This value can either
253 * be specified using one of the constant fields or a user
254 * supplied string.
255 * @param value the value of the property to be set
256 *
257 * @throws PropertyException when there is an error processing the given
258 * property or value
259 * @throws IllegalArgumentException
260 * If the name parameter is null
261 * @deprecated since JAXB2.0
262 */
263 public void setProperty(String name, Object value)
264 throws PropertyException;
265
266 /**
267 * Get the particular property in the underlying implementation of
268 * <tt>Validator</tt>. This method can only be used to get one of
269 * the standard JAXB defined properties above or a provider specific
270 * property. Attempting to get an undefined property will result in
271 * a PropertyException being thrown. See <a href="#supportedProps">
272 * Supported Properties</a>.
273 *
274 * @param name the name of the property to retrieve
275 * @return the value of the requested property
276 *
277 * @throws PropertyException
278 * when there is an error retrieving the given property or value
279 * property name
280 * @throws IllegalArgumentException
281 * If the name parameter is null
282 * @deprecated since JAXB2.0
283 */
284 public Object getProperty(String name) throws PropertyException;
285
286 }
|