1 /*

     2  * Copyright (c) 2003, 2005, 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.validation;

    27 

    28 import java.io.IOException;

    29 

    30 import javax.xml.transform.Result;

    31 import javax.xml.transform.Source;

    32 

    33 import org.w3c.dom.ls.LSResourceResolver;

    34 import org.xml.sax.ErrorHandler;

    35 import org.xml.sax.SAXException;

    36 import org.xml.sax.SAXNotRecognizedException;

    37 import org.xml.sax.SAXNotSupportedException;

    38 

    39 /**

    40  * <p>A processor that checks an XML document against {@link Schema}.</p>

    41  *

    42  * <p>

    43  * A validator object is not thread-safe and not reentrant.

    44  * In other words, it is the application's responsibility to make

    45  * sure that one {@link Validator} object is not used from

    46  * more than one thread at any given time, and while the <code>validate</code>

    47  * method is invoked, applications may not recursively call

    48  * the <code>validate</code> method.

    49  * <p>

    50  *

    51  *

    52  * @author  <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>

    53  * @since 1.5

    54  */

    55 public abstract class Validator {

    56 

    57     /**

    58      * Constructor for derived classes.

    59      *

    60      * <p>The constructor does nothing.</p>

    61      *

    62      * <p>Derived classes must create {@link Validator} objects that have

    63      * <code>null</code> {@link ErrorHandler} and

    64      * <code>null</code> {@link LSResourceResolver}.

    65      * </p>

    66      */

    67     protected Validator() {

    68     }

    69 

    70         /**

    71          * <p>Reset this <code>Validator</code> to its original configuration.</p>

    72          *

    73          * <p><code>Validator</code> is reset to the same state as when it was created with

    74          * {@link Schema#newValidator()}.

    75          * <code>reset()</code> is designed to allow the reuse of existing <code>Validator</code>s

    76          * thus saving resources associated with the creation of new <code>Validator</code>s.</p>

    77          *

    78          * <p>The reset <code>Validator</code> is not guaranteed to have the same {@link LSResourceResolver} or {@link ErrorHandler}

    79          * <code>Object</code>s, e.g. {@link Object#equals(Object obj)}.  It is guaranteed to have a functionally equal

    80          * <code>LSResourceResolver</code> and <code>ErrorHandler</code>.</p>

    81          */

    82         public abstract void reset();

    83 

    84     /**

    85      * Validates the specified input.

    86      *

    87      * <p>This is just a convenience method for

    88      * {@link #validate(Source source, Result result)}

    89      * with <code>result</code> of <code>null</code>.</p>

    90      *

    91      * @param source

    92      *      XML to be validated. Must be an XML document or

    93      *      XML element and must not be null. For backwards compatibility,

    94      *      the results of attempting to validate anything other than

    95      *      a document or element are implementation-dependent.

    96      *      Implementations must either recognize and process the input

    97      *      or throw an IllegalArgumentException.

    98      *

    99      * @throws IllegalArgumentException

   100      *      If the <code>Source</code>

   101      *      is an XML artifact that the implementation cannot

   102      *      validate (for example, a processing instruction).

   103      *

   104      * @throws SAXException

   105      *      If the {@link ErrorHandler} throws a {@link SAXException} or

   106      *      if a fatal error is found and the {@link ErrorHandler} returns

   107      *      normally.

   108      *

   109      * @throws IOException

   110      *      If the validator is processing a

   111      *      {@link javax.xml.transform.sax.SAXSource} and the

   112      *      underlying {@link org.xml.sax.XMLReader} throws an

   113      *      {@link IOException}.

   114      *

   115      *

   116      * @throws NullPointerException If <code>source</code> is

   117      *   <code>null</code>.

   118      *

   119      * @see #validate(Source source, Result result)

   120      */

   121     public void validate(Source source)

   122         throws SAXException, IOException {

   123 

   124         validate(source, null);

   125     }

   126 

   127     /**

   128      * <p>Validates the specified input and send the augmented validation

   129      * result to the specified output.</p>

   130      *

   131      * <p>This method places the following restrictions on the types of

   132      * the {@link Source}/{@link Result} accepted.</p>

   133      *

   134      * <table border=1>

   135      * <thead>

   136      *  <tr>

   137      *   <th colspan="5"><code>Source</code> / <code>Result</code> Accepted</th>

   138      *  </tr>

   139      *  <tr>

   140      *   <th></th>

   141      *   <th>{@link javax.xml.transform.stream.StreamSource}</th>

   142      *   <th>{@link javax.xml.transform.sax.SAXSource}</th>

   143      *   <th>{@link javax.xml.transform.dom.DOMSource}</th>

   144      *   <th>{@link javax.xml.transform.stax.StAXSource}</th>

   145      *  </tr>

   146      * </thead>

   147      * <tbody align="center">

   148      *  <tr>

   149      *   <td><code>null</code></td>

   150      *   <td>OK</td>

   151      *   <td>OK</td>

   152      *   <td>OK</td>

   153      *   <td>OK</td>

   154      *  </tr>

   155      *  <tr>

   156      *   <th>{@link javax.xml.transform.stream.StreamResult}</th>

   157      *   <td>OK</td>

   158      *   <td><code>IllegalArgumentException</code></td>

   159      *   <td><code>IllegalArgumentException</code></td>

   160      *   <td><code>IllegalArgumentException</code></td>

   161      *  </tr>

   162      *  <tr>

   163      *   <th>{@link javax.xml.transform.sax.SAXResult}</th>

   164      *   <td><code>IllegalArgumentException</code></td>

   165      *   <td>OK</td>

   166      *   <td><code>IllegalArgumentException</code></td>

   167      *   <td><code>IllegalArgumentException</code></td>

   168      *  </tr>

   169      *  <tr>

   170      *   <th>{@link javax.xml.transform.dom.DOMResult}</th>

   171      *   <td><code>IllegalArgumentException</code></td>

   172      *   <td><code>IllegalArgumentException</code></td>

   173      *   <td>OK</td>

   174      *   <td><code>IllegalArgumentException</code></td>

   175      *  </tr>

   176      *  <tr>

   177      *   <th>{@link javax.xml.transform.stax.StAXResult}</th>

   178      *   <td><code>IllegalArgumentException</code></td>

   179      *   <td><code>IllegalArgumentException</code></td>

   180      *   <td><code>IllegalArgumentException</code></td>

   181      *   <td>OK</td>

   182      *  </tr>

   183      * </tbody>

   184      * </table>

   185      *

   186      * <p>To validate one <code>Source</code> into another kind of

   187      * <code>Result</code>, use the identity transformer (see

   188      * {@link javax.xml.transform.TransformerFactory#newTransformer()}).</p>

   189      *

   190      * <p>Errors found during the validation is sent to the specified

   191      * {@link ErrorHandler}.</p>

   192      *

   193      * <p>If a document is valid, or if a document contains some errors

   194      * but none of them were fatal and the <code>ErrorHandler</code> didn't

   195      * throw any exception, then the method returns normally.</p>

   196      *

   197      * @param source

   198      *      XML to be validated. Must be an XML document or

   199      *      XML element and must not be null. For backwards compatibility,

   200      *      the results of attempting to validate anything other than

   201      *      a document or element are implementation-dependent.

   202      *      Implementations must either recognize and process the input

   203      *      or throw an IllegalArgumentException.

   204      *

   205      * @param result

   206      *      The <code>Result</code> object that receives (possibly augmented)

   207      *      XML. This parameter can be null if the caller is not interested

   208      *      in it.

   209      *

   210      *      Note that when a <code>DOMResult</code> is used,

   211      *      a validator might just pass the same DOM node from

   212      *      <code>DOMSource</code> to <code>DOMResult</code>

   213      *      (in which case <code>source.getNode()==result.getNode()</code>),

   214      *      it might copy the entire DOM tree, or it might alter the

   215      *      node given by the source.

   216      *

   217      * @throws IllegalArgumentException

   218      *      If the <code>Result</code> type doesn't match the

   219      *      <code>Source</code> type of if the <code>Source</code>

   220      *      is an XML artifact that the implementation cannot

   221      *      validate (for example, a processing instruction).

   222      * @throws SAXException

   223      *      If the <code>ErrorHandler</code> throws a

   224      *      <code>SAXException</code> or

   225      *      if a fatal error is found and the <code>ErrorHandler</code> returns

   226      *      normally.

   227      * @throws IOException

   228      *      If the validator is processing a

   229      *      <code>SAXSource</code> and the

   230      *      underlying {@link org.xml.sax.XMLReader} throws an

   231      *      <code>IOException</code>.

   232      * @throws NullPointerException

   233      *      If the <code>source</code> parameter is <code>null</code>.

   234      *

   235      * @see #validate(Source source)

   236      */

   237     public abstract void validate(Source source, Result result)

   238         throws SAXException, IOException;

   239 

   240     /**

   241      * Sets the {@link ErrorHandler} to receive errors encountered

   242      * during the <code>validate</code> method invocation.

   243      *

   244      * <p>

   245      * Error handler can be used to customize the error handling process

   246      * during a validation. When an {@link ErrorHandler} is set,

   247      * errors found during the validation will be first sent

   248      * to the {@link ErrorHandler}.

   249      *

   250      * <p>

   251      * The error handler can abort further validation immediately

   252      * by throwing {@link SAXException} from the handler. Or for example

   253      * it can print an error to the screen and try to continue the

   254      * validation by returning normally from the {@link ErrorHandler}

   255      *

   256      * <p>

   257      * If any {@link Throwable} is thrown from an {@link ErrorHandler},

   258      * the caller of the <code>validate</code> method will be thrown

   259      * the same {@link Throwable} object.

   260      *

   261      * <p>

   262      * {@link Validator} is not allowed to

   263      * throw {@link SAXException} without first reporting it to

   264      * {@link ErrorHandler}.

   265      *

   266      * <p>

   267      * When the {@link ErrorHandler} is null, the implementation will

   268      * behave as if the following {@link ErrorHandler} is set:

   269      * <pre>

   270      * class DraconianErrorHandler implements {@link ErrorHandler} {

   271      *     public void fatalError( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {

   272      *         throw e;

   273      *     }

   274      *     public void error( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {

   275      *         throw e;

   276      *     }

   277      *     public void warning( {@link org.xml.sax.SAXParseException} e ) throws {@link SAXException} {

   278      *         // noop

   279      *     }

   280      * }

   281      * </pre>

   282      *

   283      * <p>

   284      * When a new {@link Validator} object is created, initially

   285      * this field is set to null.

   286      *

   287      * @param   errorHandler

   288      *      A new error handler to be set. This parameter can be null.

   289      */

   290     public abstract void setErrorHandler(ErrorHandler errorHandler);

   291 

   292     /**

   293      * Gets the current {@link ErrorHandler} set to this {@link Validator}.

   294      *

   295      * @return

   296      *      This method returns the object that was last set through

   297      *      the {@link #setErrorHandler(ErrorHandler)} method, or null

   298      *      if that method has never been called since this {@link Validator}

   299      *      has created.

   300      *

   301      * @see #setErrorHandler(ErrorHandler)

   302      */

   303     public abstract ErrorHandler getErrorHandler();

   304 

   305     /**

   306      * Sets the {@link LSResourceResolver} to customize

   307      * resource resolution while in a validation episode.

   308      *

   309      * <p>

   310      * {@link Validator} uses a {@link LSResourceResolver}

   311      * when it needs to locate external resources while a validation,

   312      * although exactly what constitutes "locating external resources" is

   313      * up to each schema language.

   314      *

   315      * <p>

   316      * When the {@link LSResourceResolver} is null, the implementation will

   317      * behave as if the following {@link LSResourceResolver} is set:

   318      * <pre>

   319      * class DumbLSResourceResolver implements {@link LSResourceResolver} {

   320      *     public {@link org.w3c.dom.ls.LSInput} resolveResource(

   321      *         String publicId, String systemId, String baseURI) {

   322      *

   323      *         return null; // always return null

   324      *     }

   325      * }

   326      * </pre>

   327      *

   328      * <p>

   329      * If a {@link LSResourceResolver} throws a {@link RuntimeException}

   330      *  (or instances of its derived classes),

   331      * then the {@link Validator} will abort the parsing and

   332      * the caller of the <code>validate</code> method will receive

   333      * the same {@link RuntimeException}.

   334      *

   335      * <p>

   336      * When a new {@link Validator} object is created, initially

   337      * this field is set to null.

   338      *

   339      * @param   resourceResolver

   340      *      A new resource resolver to be set. This parameter can be null.

   341      */

   342     public abstract void setResourceResolver(LSResourceResolver resourceResolver);

   343 

   344     /**

   345      * Gets the current {@link LSResourceResolver} set to this {@link Validator}.

   346      *

   347      * @return

   348      *      This method returns the object that was last set through

   349      *      the {@link #setResourceResolver(LSResourceResolver)} method, or null

   350      *      if that method has never been called since this {@link Validator}

   351      *      has created.

   352      *

   353      * @see #setErrorHandler(ErrorHandler)

   354      */

   355     public abstract LSResourceResolver getResourceResolver();

   356 

   357 

   358 

   359     /**

   360      * Look up the value of a feature flag.

   361      *

   362      * <p>The feature name is any fully-qualified URI.  It is

   363      * possible for a {@link Validator} to recognize a feature name but

   364      * temporarily be unable to return its value.

   365      * Some feature values may be available only in specific

   366      * contexts, such as before, during, or after a validation.

   367      *

   368      * <p>Implementors are free (and encouraged) to invent their own features,

   369      * using names built on their own URIs.</p>

   370      *

   371      * @param name The feature name, which is a non-null fully-qualified URI.

   372      *

   373      * @return The current value of the feature (true or false).

   374      *

   375      * @throws SAXNotRecognizedException If the feature

   376      *   value can't be assigned or retrieved.

   377      * @throws SAXNotSupportedException When the

   378      *   {@link Validator} recognizes the feature name but

   379      *   cannot determine its value at this time.

   380      * @throws NullPointerException

   381      *   When the name parameter is null.

   382      *

   383      * @see #setFeature(String, boolean)

   384      */

   385     public boolean getFeature(String name)

   386         throws SAXNotRecognizedException, SAXNotSupportedException {

   387 

   388         if (name == null) {

   389             throw new NullPointerException("the name parameter is null");

   390         }

   391 

   392         throw new SAXNotRecognizedException(name);

   393     }

   394 

   395     /**

   396      * Set the value of a feature flag.

   397      *

   398      * <p>

   399      * Feature can be used to control the way a {@link Validator}

   400      * parses schemas, although {@link Validator}s are not required

   401      * to recognize any specific feature names.</p>

   402      *

   403      * <p>The feature name is any fully-qualified URI.  It is

   404      * possible for a {@link Validator} to expose a feature value but

   405      * to be unable to change the current value.

   406      * Some feature values may be immutable or mutable only

   407      * in specific contexts, such as before, during, or after

   408      * a validation.</p>

   409      *

   410      * @param name The feature name, which is a non-null fully-qualified URI.

   411      * @param value The requested value of the feature (true or false).

   412      *

   413      * @throws SAXNotRecognizedException If the feature

   414      *   value can't be assigned or retrieved.

   415      * @throws SAXNotSupportedException When the

   416      *   {@link Validator} recognizes the feature name but

   417      *   cannot set the requested value.

   418      * @throws NullPointerException

   419      *   When the name parameter is null.

   420      *

   421      * @see #getFeature(String)

   422      */

   423     public void setFeature(String name, boolean value)

   424         throws SAXNotRecognizedException, SAXNotSupportedException {

   425 

   426         if (name == null) {

   427             throw new NullPointerException("the name parameter is null");

   428         }

   429 

   430         throw new SAXNotRecognizedException(name);

   431     }

   432 

   433     /**

   434      * Set the value of a property.

   435      *

   436      * <p>The property name is any fully-qualified URI.  It is

   437      * possible for a {@link Validator} to recognize a property name but

   438      * to be unable to change the current value.

   439      * Some property values may be immutable or mutable only

   440      * in specific contexts, such as before, during, or after

   441      * a validation.</p>

   442      *

   443      * <p>{@link Validator}s are not required to recognize setting

   444      * any specific property names.</p>

   445      *

   446      * @param name The property name, which is a non-null fully-qualified URI.

   447      * @param object The requested value for the property.

   448      *

   449      * @throws SAXNotRecognizedException If the property

   450      *   value can't be assigned or retrieved.

   451      * @throws SAXNotSupportedException When the

   452      *   {@link Validator} recognizes the property name but

   453      *   cannot set the requested value.

   454      * @throws NullPointerException

   455      *   When the name parameter is null.

   456      */

   457     public void setProperty(String name, Object object)

   458         throws SAXNotRecognizedException, SAXNotSupportedException {

   459 

   460         if (name == null) {

   461             throw new NullPointerException("the name parameter is null");

   462         }

   463 

   464         throw new SAXNotRecognizedException(name);

   465     }

   466 

   467     /**

   468      * Look up the value of a property.

   469      *

   470      * <p>The property name is any fully-qualified URI.  It is

   471      * possible for a {@link Validator} to recognize a property name but

   472      * temporarily be unable to return its value.

   473      * Some property values may be available only in specific

   474      * contexts, such as before, during, or after a validation.</p>

   475      *

   476      * <p>{@link Validator}s are not required to recognize any specific

   477      * property names.</p>

   478      *

   479      * <p>Implementors are free (and encouraged) to invent their own properties,

   480      * using names built on their own URIs.</p>

   481      *

   482      * @param name The property name, which is a non-null fully-qualified URI.

   483      *

   484      * @return The current value of the property.

   485      *

   486      * @throws SAXNotRecognizedException If the property

   487      *   value can't be assigned or retrieved.

   488      * @throws SAXNotSupportedException When the

   489      *   XMLReader recognizes the property name but

   490      *   cannot determine its value at this time.

   491      * @throws NullPointerException

   492      *   When the name parameter is null.

   493      *

   494      * @see #setProperty(String, Object)

   495      */

   496     public Object getProperty(String name)

   497         throws SAXNotRecognizedException, SAXNotSupportedException {

   498 

   499         if (name == null) {

   500             throw new NullPointerException("the name parameter is null");

   501         }

   502 

   503         throw new SAXNotRecognizedException(name);

   504     }

   505 }