Validator


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