View Javadoc
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 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 }