ValidatorHandler


1   // $Id: ValidatorHandler.java,v 1.23.16.1 2004/06/28 18:26:43 ndw Exp $
2   
3   /*
4    * @(#)ValidatorHandler.java    1.7 04/07/26
5    * 
6    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
7    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
8    */
9   
10  package javax.xml.validation;
11  
12  import org.w3c.dom.ls.LSResourceResolver  ;
13  import org.xml.sax.ContentHandler  ;
14  import org.xml.sax.ErrorHandler  ;
15  import org.xml.sax.SAXNotRecognizedException  ;
16  import org.xml.sax.SAXNotSupportedException  ;
17  
18  /**
19   * Streaming validator that works on SAX stream.
20   * 
21   * <p>
22   * A {@link ValidatorHandler} object is a thread-unsafe, non-reentrant object.
23   * In other words, it is the application's responsibility to make
24   * sure that one {@link ValidatorHandler} object is not used from
25   * more than one thread at any given time.
26   * 
27   * <p>
28   * {@link ValidatorHandler} checks if the SAX events follow 
29   * the set of constraints described in the associated {@link Schema},
30   * and additionally it may modify the SAX events (for example
31   * by adding default values, etc.)
32   * 
33   * <p>
34   * {@link ValidatorHandler} extends from {@link ContentHandler},
35   * but it refines the underlying {@link ContentHandler} in
36   * the following way:
37   * <ol>
38   *  <li>startElement/endElement events must receive non-null String
39   *      for <code>uri</code>, <code>localName</code>, and <code>qname</code>,
40   *      even though SAX allows some of them to be null.
41   *      Similarly, the user-specified {@link ContentHandler} will receive non-null
42   *      Strings for all three parameters.
43   * 
44   *  <li>Applications must ensure that {@link ValidatorHandler}'s
45   *      {@link ContentHandler#startPrefixMapping(String,String)} and
46   *      {@link ContentHandler#endPrefixMapping(String)} are invoked
47   *      properly. Similarly, the user-specified {@link ContentHandler}
48   *      will receive startPrefixMapping/endPrefixMapping events.
49   *      If the {@link ValidatorHandler} introduces additional namespace
50   *      bindings, the user-specified {@link ContentHandler} will receive
51   *      additional startPrefixMapping/endPrefixMapping events.
52   * 
53   *  <li>{@link org.xml.sax.Attributes} for the
54   *      {@link ContentHandler#startElement(String,String,String,Attributes)} method
55   *      may or may not include xmlns* attributes.
56   * </ol>
57   * 
58   * <p>
59   * A {@link ValidatorHandler} is automatically reset every time
60   * the startDocument method is invoked.
61   * 
62   * <h2>Recognized Properties and Features</h2>
63   * <p>
64   * This spec defines the following feature that must be recognized
65   * by all {@link ValidatorHandler} implementations.
66   * 
67   * <h3><code>http://xml.org/sax/features/namespace-prefixes</code></h3>
68   * <p>
69   * This feature controls how a {@link ValidatorHandler} introduces
70   * namespace bindings that were not present in the original SAX event
71   * stream.
72   * When this feature is set to true, it must make
73   * sure that the user's {@link ContentHandler} will see 
74   * the corresponding <code>xmlns*</code> attribute in
75   * the {@link org.xml.sax.Attributes} object of the
76   * {@link ContentHandler#startElement(String,String,String,Attributes)}
77   * callback. Otherwise, <code>xmlns*</code> attributes must not be
78   * added to {@link org.xml.sax.Attributes} that's passed to the
79   * user-specified {@link ContentHandler}.
80   * <p> 
81   * (Note that regardless of this switch, namespace bindings are
82   * always notified to applications through 
83   * {@link ContentHandler#startPrefixMapping(String,String)} and
84   * {@link ContentHandler#endPrefixMapping(String)} methods of the
85   * {@link ContentHandler} specified by the user.)
86   * 
87   * <p>
88   * Note that this feature does <em>NOT</em> affect the way
89   * a {@link ValidatorHandler} receives SAX events. It merely
90   * changes the way it augments SAX events.
91   * 
92   * <p>This feature is set to <code>false</code> by default.</p>
93   * 
94   * @author  <a HREF="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
95   * @version $Revision: 1.23.16.1 $, $Date: 2004/06/28 18:26:43 $
96   * @since 1.5
97   */
98  public abstract class ValidatorHandler implements ContentHandler   {
99      
100     /**
101      * Constructor for derived classes.
102      * 
103      * <p>
104      * The constructor does nothing.
105      * 
106      * <p>
107      * Derived classes must create {@link ValidatorHandler} objects that have
108      * <tt>null</tt> {@link ErrorHandler} and
109      * <tt>null</tt> {@link LSResourceResolver}.
110      */
111     protected ValidatorHandler() {
112     }
113     
114     /**
115      * Sets the {@link ContentHandler} which receives
116      * the augmented validation result.
117      *
118      * <p>
119      * When a {@link ContentHandler} is specified, a
120      * {@link ValidatorHandler} will work as a filter
121      * and basically copy the incoming events to the
122      * specified {@link ContentHandler}.
123      * 
124      * <p>
125      * In doing so, a {@link ValidatorHandler} may modify
126      * the events, for example by adding defaulted attributes.
127      * 
128      * <p>
129      * A {@link ValidatorHandler} may buffer events to certain
130      * extent, but to allow {@link ValidatorHandler} to be used
131      * by a parser, the following requirement has to be met.
132      * 
133      * <ol>
134      *  <li>When
135      *      {@link ContentHandler#startElement(String, String, String, Attributes)},
136      *      {@link ContentHandler#endElement(String, String, String)},
137      *      {@link ContentHandler#startDocument()}, or
138      *      {@link ContentHandler#endDocument()}
139      *      are invoked on a {@link ValidatorHandler},
140      *      the same method on the user-specified {@link ContentHandler}
141      *      must be invoked for the same event before the callback
142      *      returns.
143      *  <li>{@link ValidatorHandler} may not introduce new elements that
144      *      were not present in the input.
145      * 
146      *  <li>{@link ValidatorHandler} may not remove attributes that were
147      *      present in the input.
148      * </ol> 
149      * 
150      * <p>
151      * When a callback method on the specified {@link ContentHandler}
152      * throws an exception, the same exception object must be thrown
153      * from the {@link ValidatorHandler}. The {@link ErrorHandler}
154      * should not be notified of such an exception.
155      * 
156      * <p>
157      * This method can be called even during a middle of a validation.
158      *
159      * @param receiver
160      *      A {@link ContentHandler} or a null value. 
161      */
162     public abstract void setContentHandler(ContentHandler   receiver);
163     
164     /**
165      * Gets the {@link ContentHandler} which receives the
166      * augmented validation result.
167      * 
168      * @return
169      *      This method returns the object that was last set through
170      *      the {@link #getContentHandler()} method, or null
171      *      if that method has never been called since this {@link ValidatorHandler}
172      *      has created.
173      * 
174      * @see #setContentHandler(ContentHandler)
175      */
176     public abstract ContentHandler   getContentHandler();
177     
178     /**
179      * Sets the {@link ErrorHandler} to receive errors encountered
180      * during the validation.
181      * 
182      * <p>
183      * Error handler can be used to customize the error handling process
184      * during a validation. When an {@link ErrorHandler} is set,
185      * errors found during the validation will be first sent
186      * to the {@link ErrorHandler}.
187      * 
188      * <p>
189      * The error handler can abort further validation immediately
190      * by throwing {@link org.xml.sax.SAXException} from the handler. Or for example
191      * it can print an error to the screen and try to continue the
192      * validation by returning normally from the {@link ErrorHandler} 
193      * 
194      * <p>
195      * If any {@link Throwable} is thrown from an {@link ErrorHandler},
196      * the same {@link Throwable} object will be thrown toward the
197      * root of the call stack.
198      * 
199      * <p>
200      * {@link ValidatorHandler} is not allowed to
201      * throw {@link org.xml.sax.SAXException} without first reporting it to
202      * {@link ErrorHandler}.
203      * 
204      * <p>
205      * When the {@link ErrorHandler} is null, the implementation will
206      * behave as if the following {@link ErrorHandler} is set:
207      * <pre>
208      * class DraconianErrorHandler implements {@link ErrorHandler} {
209      *     public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
210      *         throw e;
211      *     }
212      *     public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
213      *         throw e;
214      *     }
215      *     public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link org.xml.sax.SAXException} {
216      *         // noop
217      *     }
218      * }
219      * </pre>
220      * 
221      * <p>
222      * When a new {@link ValidatorHandler} object is created, initially
223      * this field is set to null.
224      * 
225      * @param   errorHandler
226      *      A new error handler to be set. This parameter can be null.
227      */
228     public abstract void setErrorHandler(ErrorHandler   errorHandler);
229     
230     /**
231      * Gets the current {@link ErrorHandler} set to this {@link ValidatorHandler}.
232      * 
233      * @return
234      *      This method returns the object that was last set through
235      *      the {@link #setErrorHandler(ErrorHandler)} method, or null
236      *      if that method has never been called since this {@link ValidatorHandler}
237      *      has created.
238      * 
239      * @see #setErrorHandler(ErrorHandler)
240      */
241     public abstract ErrorHandler   getErrorHandler();
242     
243     /**
244      * Sets the {@link LSResourceResolver} to customize
245      * resource resolution while in a validation episode.
246      * 
247      * <p>
248      * {@link ValidatorHandler} uses a {@link LSResourceResolver}
249      * when it needs to locate external resources while a validation,
250      * although exactly what constitutes "locating external resources" is
251      * up to each schema language.
252      * 
253      * <p>
254      * When the {@link LSResourceResolver} is null, the implementation will
255      * behave as if the following {@link LSResourceResolver} is set:
256      * <pre>
257      * class DumbLSResourceResolver implements {@link LSResourceResolver} {
258      *     public {@link org.w3c.dom.ls.LSInput} resolveResource(
259      *         String publicId, String systemId, String baseURI) {
260      *         
261      *         return null; // always return null
262      *     }
263      * }
264      * </pre>
265      * 
266      * <p>
267      * If a {@link LSResourceResolver} throws a {@link RuntimeException}
268      *  (or instances of its derived classes),
269      * then the {@link ValidatorHandler} will abort the parsing and  
270      * the caller of the <code>validate</code> method will receive
271      * the same {@link RuntimeException}. 
272      * 
273      * <p>
274      * When a new {@link ValidatorHandler} object is created, initially
275      * this field is set to null.
276      * 
277      * @param   resourceResolver
278      *      A new resource resolver to be set. This parameter can be null.
279      */
280     public abstract void setResourceResolver(LSResourceResolver   resourceResolver);
281     
282     /**
283      * Gets the current {@link LSResourceResolver} set to this {@link ValidatorHandler}.
284      * 
285      * @return
286      *      This method returns the object that was last set through
287      *      the {@link #setResourceResolver(LSResourceResolver)} method, or null
288      *      if that method has never been called since this {@link ValidatorHandler}
289      *      has created.
290      * 
291      * @see #setErrorHandler(ErrorHandler)
292      */
293     public abstract LSResourceResolver   getResourceResolver();
294     
295     /**
296      * Obtains the {@link TypeInfoProvider} implementation of this
297      * {@link ValidatorHandler}.
298      * 
299      * <p>
300      * The obtained {@link TypeInfoProvider} can be queried during a parse
301      * to access the type information determined by the validator.
302      * 
303      * <p>
304      * Some schema languages do not define the notion of type,
305      * for those languages, this method may not be supported.
306      * However, to be compliant with this specification, implementations
307      * for W3C XML Schema 1.0 must support this operation. 
308      * 
309      * @return
310      *      null if the validator / schema language does not support
311      *      the notion of {@link org.w3c.dom.TypeInfo}.
312      *      Otherwise a non-null valid {@link TypeInfoProvider}.
313      */
314     public abstract TypeInfoProvider   getTypeInfoProvider();
315     
316     
317     /**
318      * Look up the value of a feature flag.
319      *
320      * <p>The feature name is any fully-qualified URI.  It is
321      * possible for a {@link ValidatorHandler} to recognize a feature name but
322      * temporarily be unable to return its value.
323      * Some feature values may be available only in specific
324      * contexts, such as before, during, or after a validation.
325      *
326      * <p>Implementors are free (and encouraged) to invent their own features,
327      * using names built on their own URIs.</p>
328      *
329      * @param name The feature name, which is a non-null fully-qualified URI.
330      * @return The current value of the feature (true or false).
331      * @exception org.xml.sax.SAXNotRecognizedException If the feature
332      *            value can't be assigned or retrieved.
333      * @exception org.xml.sax.SAXNotSupportedException When the
334      *            {@link ValidatorHandler} recognizes the feature name but 
335      *            cannot determine its value at this time.
336      * @throws NullPointerException
337      *          When the name parameter is null.
338      * @see #setFeature(String, boolean)
339      */
340     public boolean getFeature(String   name) throws SAXNotRecognizedException  , SAXNotSupportedException   {
341         if(name==null)
342             throw new NullPointerException  ();
343         throw new SAXNotRecognizedException  (name);
344     }
345     
346     /**
347      * Set the value of a feature flag.
348      *
349      * <p>
350      * Feature can be used to control the way a {@link ValidatorHandler}
351      * parses schemas, although {@link ValidatorHandler}s are not required
352      * to recognize any specific property names.</p>
353      *
354      * <p>The feature name is any fully-qualified URI.  It is
355      * possible for a {@link ValidatorHandler} to expose a feature value but
356      * to be unable to change the current value.
357      * Some feature values may be immutable or mutable only 
358      * in specific contexts, such as before, during, or after 
359      * a validation.</p>
360      *
361      * @param name The feature name, which is a non-null fully-qualified URI.
362      * @param value The requested value of the feature (true or false).
363      * 
364      * @exception org.xml.sax.SAXNotRecognizedException If the feature
365      *            value can't be assigned or retrieved.
366      * @exception org.xml.sax.SAXNotSupportedException When the
367      *            {@link ValidatorHandler} recognizes the feature name but 
368      *            cannot set the requested value.
369      * @throws NullPointerException
370      *          When the name parameter is null.
371      * 
372      * @see #getFeature(String)
373      */
374     public void setFeature(String   name, boolean value) throws SAXNotRecognizedException  , SAXNotSupportedException   {
375         if(name==null)
376             throw new NullPointerException  ();
377         throw new SAXNotRecognizedException  (name);
378     }
379     
380     /**
381      * Set the value of a property.
382      *
383      * <p>The property name is any fully-qualified URI.  It is
384      * possible for a {@link ValidatorHandler} to recognize a property name but
385      * to be unable to change the current value.
386      * Some property values may be immutable or mutable only 
387      * in specific contexts, such as before, during, or after 
388      * a validation.</p>
389      *
390      * <p>{@link ValidatorHandler}s are not required to recognize setting
391      * any specific property names.</p>
392      *
393      * @param name The property name, which is a non-null fully-qualified URI.
394      * @param object The requested value for the property.
395      * 
396      * @exception org.xml.sax.SAXNotRecognizedException If the property
397      *            value can't be assigned or retrieved.
398      * @exception org.xml.sax.SAXNotSupportedException When the
399      *            {@link ValidatorHandler} recognizes the property name but 
400      *            cannot set the requested value.
401      * @throws NullPointerException
402      *          When the name parameter is null.
403      */
404     public void setProperty(String   name, Object   object) throws SAXNotRecognizedException  , SAXNotSupportedException   {
405         if(name==null)
406             throw new NullPointerException  ();
407         throw new SAXNotRecognizedException  (name);
408     }
409     
410     /**
411      * Look up the value of a property.
412      *
413      * <p>The property name is any fully-qualified URI.  It is
414      * possible for a {@link ValidatorHandler} to recognize a property name but
415      * temporarily be unable to return its value.
416      * Some property values may be available only in specific
417      * contexts, such as before, during, or after a validation.</p>
418      *
419      * <p>{@link ValidatorHandler}s are not required to recognize any specific
420      * property names.</p>
421      *
422      * <p>Implementors are free (and encouraged) to invent their own properties,
423      * using names built on their own URIs.</p>
424      *
425      * @param name The property name, which is a non-null fully-qualified URI.
426      * @return The current value of the property.
427      * @exception org.xml.sax.SAXNotRecognizedException If the property
428      *            value can't be assigned or retrieved.
429      * @exception org.xml.sax.SAXNotSupportedException When the
430      *            XMLReader recognizes the property name but 
431      *            cannot determine its value at this time.
432      * @throws NullPointerException
433      *          When the name parameter is null.
434      * @see #setProperty(String, Object)
435      */
436     public Object   getProperty(String   name) throws SAXNotRecognizedException  , SAXNotSupportedException   {
437         if(name==null)
438             throw new NullPointerException  ();
439         throw new SAXNotRecognizedException  (name);
440     }
441 }
442
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags