1 /*
2 * Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 JAXB1.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 }
Save This Page