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