Validator


1   // $Id: Validator.java,v 1.18.14.1.2.4 2004/07/13 22:27:52 jsuttor Exp $
2   /*
3    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
4    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
5    */
6   
7   package javax.xml.validation;
8   
9   import java.io.IOException  ;
10  
11  import javax.xml.transform.Result  ;
12  import javax.xml.transform.Source  ;
13  
14  import org.w3c.dom.ls.LSResourceResolver  ;
15  import org.xml.sax.ErrorHandler  ;
16  import org.xml.sax.SAXException  ;
17  import org.xml.sax.SAXNotRecognizedException  ;
18  import org.xml.sax.SAXNotSupportedException  ;
19  
20  /**
21   * <p>A processor that checks an XML document against {@link Schema}.</p>
22   * 
23   * <p>
24   * A validator is a thread-unsafe and non-reentrant object.
25   * In other words, it is the application's responsibility to make
26   * sure that one {@link Validator} object is not used from
27   * more than one thread at any given time, and while the <tt>validate</tt>
28   * method is invoked, applications may not recursively call
29   * the <tt>validate</tt> method.
30   * <p>
31   *
32   * Note that while the {@link #validate(javax.xml.transform.Source)} and {@link #validate(javax.xml.transform.Source, javax.xml.transform.Result)}
33   * methods take a {@link Source} instance, the <code>Source</code>
34   * instance must be a <code>SAXSource</code> or <code>DOMSource</code>.
35   *
36   * @author  <a HREF="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
37   * @version $Revision: 1.18.14.1.2.4 $, $Date: 2004/07/13 22:27:52 $
38   * @since 1.5
39   */
40  public abstract class Validator {
41      
42      /**
43       * Constructor for derived classes.
44       * 
45       * <p>
46       * The constructor does nothing.
47       * 
48       * <p>
49       * Derived classes must create {@link Validator} objects that have
50       * <tt>null</tt> {@link ErrorHandler} and
51       * <tt>null</tt> {@link LSResourceResolver}.
52       */
53      protected Validator() {
54      }
55      
56      /**
57       * <p>Reset this <code>Validator</code> to its original configuration.</p>
58       * 
59       * <p><code>Validator</code> is reset to the same state as when it was created with
60       * {@link Schema#newValidator()}.
61       * <code>reset()</code> is designed to allow the reuse of existing <code>Validator</code>s
62       * thus saving resources associated with the creation of new <code>Validator</code>s.</p>
63       * 
64       * <p>The reset <code>Validator</code> is not guaranteed to have the same {@link LSResourceResolver} or {@link ErrorHandler}
65       * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}.  It is guaranteed to have a functionally equal
66       * <code>LSResourceResolver</code> and <code>ErrorHandler</code>.</p>
67       */
68      public abstract void reset();
69  
70      /**
71       * Validates the specified input.
72       * 
73       * <p>
74       * This is just a convenience method of:
75       * <pre>
76       * validate(source,null);
77       * </pre>
78       * 
79       * @see #setErrorHandler(ErrorHandler)
80       */
81      public void validate(Source   source) throws SAXException  , IOException   {
82          validate(source, null);
83      }
84      
85      /**
86       * Validates the specified input and send the augmented validation
87       * result to the specified output.
88       * 
89       * <p>
90       * This method places the following restrictions on the types of
91       * the {@link Source}/{@link Result} accepted.
92       * 
93       * <h4>{@link Source}/{@link Result} accepted:</h4>
94       * <table border=1>
95       * <thead>
96       *  <tr>
97       *   <td></td>
98       *   <td>{@link javax.xml.transform.sax.SAXSource}</td>
99       *   <td>{@link javax.xml.transform.dom.DOMSource}</td>
100      *  </tr>
101      * </thead>
102      * <tbody>
103      *  <tr>
104      *   <td><tt>null</tt></td>
105      *   <td>OK</td>
106      *   <td>OK</td>
107      *  </tr>
108      *  <tr>
109      *   <td>{@link javax.xml.transform.sax.SAXResult}</td>
110      *   <td>OK</td>
111      *   <td>Err</td>
112      *  </tr>
113      *  <tr>
114      *   <td>{@link javax.xml.transform.dom.DOMResult}</td>
115      *   <td>Err</td>
116      *   <td>OK</td>
117      *  </tr>
118      * </tbody>
119      * </table>
120      *
121      * <p>
122      * <strong>Note that {@link javax.xml.transform.stream.StreamSource} instances are not allowed.</strong> To process
123      * a <code>StreamSource</code>, or to validate one {@link Source} into another kind of {@link Result}, use the identity transformer
124      * (see {@link javax.xml.transform.TransformerFactory#newTransformer()}).
125      * 
126      * <p>
127      * Errors found during the validation is sent to the specified
128      * {@link ErrorHandler}.
129      * 
130      * <p>
131      * If a document is valid, or if a document contains some errors
132      * but none of them were fatal and the {@link ErrorHandler} didn't
133      * throw any exception, then the method returns normally.
134      * 
135      * @param source
136      *      XML to be validated. Must not be null.
137      * 
138      * @param result
139      *      The {@link Result} object that receives (possibly augmented)
140      *      XML. This parameter can be null if the caller is not interested
141      *      in it.
142      *      
143      *      Note that when a {@link javax.xml.transform.dom.DOMResult} is used,
144      *      a validator might just pass the same DOM node from
145      *      {@link javax.xml.transform.dom.DOMSource} to
146      *      {@link javax.xml.transform.dom.DOMResult}
147      *      (in which case <tt>source.getNode()==result.getNode()</tt>),
148      *      it might copy the entire DOM tree, or it might alter the
149      *      node given by the source.
150      * 
151      * @throws IllegalArgumentException
152      *      If the {@link Result} type doesn't match the {@link Source} type,
153      *      or if the specified source is neither
154      *      {@link javax.xml.transform.sax.SAXSource} nor
155      *      {@link javax.xml.transform.dom.DOMSource}. 
156      * 
157      * @throws SAXException
158      *      If the {@link ErrorHandler} throws a {@link SAXException} or
159      *      if a fatal error is found and the {@link ErrorHandler} returns
160      *      normally.
161      * 
162      * @throws IOException
163      *      If the validator is processing a
164      *      {@link javax.xml.transform.sax.SAXSource} and the
165      *      underlying {@link org.xml.sax.XMLReader} throws an
166      *      {@link IOException}.
167      * 
168      * @throws NullPointerException
169      *      If the <tt>source</tt> parameter is null.
170      * 
171      * @see #validate(Source)
172      */
173     public abstract void validate(Source   source, Result   result) throws SAXException  , IOException  ;
174     
175     /**
176      * Sets the {@link ErrorHandler} to receive errors encountered
177      * during the <code>validate</code> method invocation.
178      * 
179      * <p>
180      * Error handler can be used to customize the error handling process
181      * during a validation. When an {@link ErrorHandler} is set,
182      * errors found during the validation will be first sent
183      * to the {@link ErrorHandler}.
184      * 
185      * <p>
186      * The error handler can abort further validation immediately
187      * by throwing {@link SAXException} from the handler. Or for example
188      * it can print an error to the screen and try to continue the
189      * validation by returning normally from the {@link ErrorHandler} 
190      * 
191      * <p>
192      * If any {@link Throwable} is thrown from an {@link ErrorHandler},
193      * the caller of the <code>validate</code> method will be thrown
194      * the same {@link Throwable} object.
195      * 
196      * <p>
197      * {@link Validator} is not allowed to
198      * throw {@link SAXException} without first reporting it to
199      * {@link ErrorHandler}.
200      * 
201      * <p>
202      * When the {@link ErrorHandler} is null, the implementation will
203      * behave as if the following {@link ErrorHandler} is set:
204      * <pre>
205      * class DraconianErrorHandler implements {@link ErrorHandler} {
206      *     public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
207      *         throw e;
208      *     }
209      *     public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
210      *         throw e;
211      *     }
212      *     public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {
213      *         // noop
214      *     }
215      * }
216      * </pre>
217      * 
218      * <p>
219      * When a new {@link Validator} object is created, initially
220      * this field is set to null.
221      * 
222      * @param   errorHandler
223      *      A new error handler to be set. This parameter can be null.
224      */
225     public abstract void setErrorHandler(ErrorHandler   errorHandler);
226     
227     /**
228      * Gets the current {@link ErrorHandler} set to this {@link Validator}.
229      * 
230      * @return
231      *      This method returns the object that was last set through
232      *      the {@link #setErrorHandler(ErrorHandler)} method, or null
233      *      if that method has never been called since this {@link Validator}
234      *      has created.
235      * 
236      * @see #setErrorHandler(ErrorHandler)
237      */
238     public abstract ErrorHandler   getErrorHandler();
239     
240     /**
241      * Sets the {@link LSResourceResolver} to customize
242      * resource resolution while in a validation episode.
243      * 
244      * <p>
245      * {@link Validator} uses a {@link LSResourceResolver}
246      * when it needs to locate external resources while a validation,
247      * although exactly what constitutes "locating external resources" is
248      * up to each schema language.
249      * 
250      * <p>
251      * When the {@link LSResourceResolver} is null, the implementation will
252      * behave as if the following {@link LSResourceResolver} is set:
253      * <pre>
254      * class DumbLSResourceResolver implements {@link LSResourceResolver} {
255      *     public {@link org.w3c.dom.ls.LSInput} resolveResource(
256      *         String publicId, String systemId, String baseURI) {
257      *         
258      *         return null; // always return null
259      *     }
260      * }
261      * </pre>
262      * 
263      * <p>
264      * If a {@link LSResourceResolver} throws a {@link RuntimeException}
265      *  (or instances of its derived classes),
266      * then the {@link Validator} will abort the parsing and  
267      * the caller of the <code>validate</code> method will receive
268      * the same {@link RuntimeException}. 
269      * 
270      * <p>
271      * When a new {@link Validator} object is created, initially
272      * this field is set to null.
273      * 
274      * @param   resourceResolver
275      *      A new resource resolver to be set. This parameter can be null.
276      */
277     public abstract void setResourceResolver(LSResourceResolver   resourceResolver);
278     
279     /**
280      * Gets the current {@link LSResourceResolver} set to this {@link Validator}.
281      * 
282      * @return
283      *      This method returns the object that was last set through
284      *      the {@link #setResourceResolver(LSResourceResolver)} method, or null
285      *      if that method has never been called since this {@link Validator}
286      *      has created.
287      * 
288      * @see #setErrorHandler(ErrorHandler)
289      */
290     public abstract LSResourceResolver   getResourceResolver();
291     
292     
293     
294     /**
295      * Look up the value of a feature flag.
296      *
297      * <p>The feature name is any fully-qualified URI.  It is
298      * possible for a {@link Validator} to recognize a feature name but
299      * temporarily be unable to return its value.
300      * Some feature values may be available only in specific
301      * contexts, such as before, during, or after a validation.
302      *
303      * <p>Implementors are free (and encouraged) to invent their own features,
304      * using names built on their own URIs.</p>
305      *
306      * @param name The feature name, which is a non-null fully-qualified URI.
307      * @return The current value of the feature (true or false).
308      * @exception org.xml.sax.SAXNotRecognizedException If the feature
309      *            value can't be assigned or retrieved.
310      * @exception org.xml.sax.SAXNotSupportedException When the
311      *            {@link Validator} recognizes the feature name but 
312      *            cannot determine its value at this time.
313      * @throws NullPointerException
314      *          When the name parameter is null.
315      * @see #setFeature(String, boolean)
316      */
317     public boolean getFeature(String   name) throws SAXNotRecognizedException  , SAXNotSupportedException   {
318         if(name==null) throw new NullPointerException  ("the name parameter is null");
319         throw new SAXNotRecognizedException  (name);
320     }
321     
322     /**
323      * Set the value of a feature flag.
324      *
325      * <p>
326      * Feature can be used to control the way a {@link Validator}
327      * parses schemas, although {@link Validator}s are not required
328      * to recognize any specific property names.</p>
329      *
330      * <p>The feature name is any fully-qualified URI.  It is
331      * possible for a {@link Validator} to expose a feature value but
332      * to be unable to change the current value.
333      * Some feature values may be immutable or mutable only 
334      * in specific contexts, such as before, during, or after 
335      * a validation.</p>
336      *
337      * @param name The feature name, which is a non-null fully-qualified URI.
338      * @param value The requested value of the feature (true or false).
339      * 
340      * @exception org.xml.sax.SAXNotRecognizedException If the feature
341      *            value can't be assigned or retrieved.
342      * @exception org.xml.sax.SAXNotSupportedException When the
343      *            {@link Validator} recognizes the feature name but 
344      *            cannot set the requested value.
345      * @throws NullPointerException
346      *          When the name parameter is null.
347      * 
348      * @see #getFeature(String)
349      */
350     public void setFeature(String   name, boolean value) throws SAXNotRecognizedException  , SAXNotSupportedException   {
351         if(name==null) throw new NullPointerException  ("the name parameter is null");
352         throw new SAXNotRecognizedException  (name);
353     }
354     
355     /**
356      * Set the value of a property.
357      *
358      * <p>The property name is any fully-qualified URI.  It is
359      * possible for a {@link Validator} to recognize a property name but
360      * to be unable to change the current value.
361      * Some property values may be immutable or mutable only 
362      * in specific contexts, such as before, during, or after 
363      * a validation.</p>
364      *
365      * <p>{@link Validator}s are not required to recognize setting
366      * any specific property names.</p>
367      *
368      * @param name The property name, which is a non-null fully-qualified URI.
369      * @param object The requested value for the property.
370      * @exception org.xml.sax.SAXNotRecognizedException If the property
371      *            value can't be assigned or retrieved.
372      * @exception org.xml.sax.SAXNotSupportedException When the
373      *            {@link Validator} recognizes the property name but 
374      *            cannot set the requested value.
375      * @throws NullPointerException
376      *          When the name parameter is null.
377      */
378     public void setProperty(String   name, Object   object) throws SAXNotRecognizedException  , SAXNotSupportedException   {
379         if(name==null) throw new NullPointerException  ("the name parameter is null");
380         throw new SAXNotRecognizedException  (name);
381     }
382     
383     /**
384      * Look up the value of a property.
385      *
386      * <p>The property name is any fully-qualified URI.  It is
387      * possible for a {@link Validator} to recognize a property name but
388      * temporarily be unable to return its value.
389      * Some property values may be available only in specific
390      * contexts, such as before, during, or after a validation.</p>
391      *
392      * <p>{@link Validator}s are not required to recognize any specific
393      * property names.</p>
394      *
395      * <p>Implementors are free (and encouraged) to invent their own properties,
396      * using names built on their own URIs.</p>
397      *
398      * @param name The property name, which is a non-null fully-qualified URI.
399      * @return The current value of the property.
400      * @exception org.xml.sax.SAXNotRecognizedException If the property
401      *            value can't be assigned or retrieved.
402      * @exception org.xml.sax.SAXNotSupportedException When the
403      *            XMLReader recognizes the property name but 
404      *            cannot determine its value at this time.
405      * @throws NullPointerException
406      *          When the name parameter is null.
407      * @see #setProperty(String, Object)
408      */
409     public Object   getProperty(String   name) throws SAXNotRecognizedException  , SAXNotSupportedException   {
410         if(name==null) throw new NullPointerException  ("the name parameter is null");
411         throw new SAXNotRecognizedException  (name);
412     }
413 }
414
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags