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