001    /*
002     * $Id: Validator.java,v 1.19 2002/11/21 00:21:57 ryans Exp $
003     *
004     * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
005     * 
006     * This software is the proprietary information of Sun Microsystems, Inc.  
007     * Use is subject to license terms.
008     * 
009     */
010    
011    package javax.xml.bind;
012    
013    /**
014     * The <tt>Validator</tt> class is responsible for controlling the validation
015     * of content trees during runtime.
016     *
017     * <p>
018     * <a name="validationtypes"></a>
019     * <b>Three Forms of Validation</b><br>
020     * <blockquote>
021     *    <dl>
022     *        <dt><b>Unmarshal-Time Validation</b></dt>
023     *        <dd>This form of validation enables a client application to receive 
024     *            information about validation errors and warnings detected while
025     *            unmarshalling XML data into a Java content tree and is completely 
026     *            orthogonal to the other types of validation.  To enable or disable 
027     *            it, see the javadoc for 
028     *            {@link Unmarshaller#setValidating(boolean) Unmarhaller.setValidating}.
029     *            All JAXB Providers are required to support this operation.
030     *        </dd>
031     *
032     *        <dt><b>On-Demand Validation</b></dt>
033     *        <dd> This form of validation enables a client application to receive 
034     *             information about validation errors and warnings detected in the 
035     *             Java content tree.  At any point, client applications can call
036     *             the {@link Validator#validate(Object) Validator.validate} method
037     *             on the Java content tree (or any sub-tree of it).  All JAXB
038     *             Providers are required to support this operation.
039     *        </dd>
040     *
041     *        <dt><b>Fail-Fast Validation</b></dt>
042     *        <dd> This form of validation enables a client application to receive 
043     *             immediate feedback about modifications to the Java content tree 
044     *             that violate type constraints on Java Properties as defined in 
045     *             the specification.  JAXB Providers are not required support
046     *             this type of validation.  Of the JAXB Providers that do support
047     *             this type of validation, some may require you to decide at schema
048     *             compile time whether or not a client application will be allowed
049     *             to request fail-fast validation at runtime.
050     *        </dd>
051     *    </dl>
052     * </blockquote>
053     *
054     * <p>
055     * The <tt>Validator</tt> class is responsible for managing On-Demand Validation.  
056     * The <tt>Unmarshaller</tt> class is responsible for managing Unmarshal-Time 
057     * Validation during the unmarshal operations.  Although there is no formal
058     * method of enabling validation during the marshal operations, the 
059     * <tt>Marshaller</tt> may detect errors, which will be reported to the 
060     * <tt>ValidationEventHandler</tt> registered on it.
061     *
062     * <p>
063     * <a name="defaulthandler"></a>
064     * <b>Using the Default EventHandler</b><br>
065     * <blockquote>
066     *   If the client application does not set an event handler on their 
067     *   <tt>Validator</tt>, <tt>Unmarshaller</tt>, or <tt>MArshaller</tt> prior to 
068     *   calling the validate, unmarshal, or marshal methods, then a default event 
069     *   handler will receive notification of any errors or warnings encountered.  
070     *   The default event handler will cause the current operation to halt after 
071     *   encountering the first error or fatal error (but will attempt to continue 
072     *   after receiving warnings).
073     * </blockquote>
074     *
075     * <p>
076     * <a name="handlingevents"></a>
077     * <b>Handling Validation Events</b><br>
078     * <blockquote>
079     *   There are three ways to handle events encountered during the unmarshal,
080     *   validate, and marshal operations:
081     *    <dl>
082     *        <dt>Use the default event handler</dt>
083     *        <dd>The default event handler will be used if you do not specify one
084     *            via the <tt>setEventHandler</tt> API's on <tt>Validator</tt>, 
085     *            <tt>Unmarshaller</tt>, or <tt>Marshaller</tt>.
086     *        </dd>
087     * 
088     *        <dt>Implement and register a custom event handler</dt>
089     *        <dd>Client applications that require sophisticated event processing
090     *            can implement the <tt>ValidationEventHandler</tt> interface and 
091     *            register it with the <tt>Unmarshaller</tt> and/or 
092     *            <tt>Validator</tt>.
093     *        </dd>
094     *
095     *        <dt>Use the {@link javax.xml.bind.util.ValidationEventCollector ValidationEventCollector} 
096     *            utility</dt>
097     *        <dd>For convenience, a specialized event handler is provided that
098     *            simply collects any <tt>ValidationEvent</tt> objects created 
099     *            during the unmarshal, validate, and marshal operations and 
100     *            returns them to the client application as a 
101     *            <tt>java.util.Collection</tt>.
102     *        </dd>
103     *    </dl>
104     * </blockquote>
105     *
106     * <p>
107     * <b>Validation and Well-Formedness</b><br>
108     * <blockquote>
109     * <p>
110     * Validation events are handled differently depending on how the client 
111     * application is configured to process them as described in the previous
112     * section.  However, there are certain cases where a JAXB Provider indicates
113     * that it is no longer able to reliably detect and report errors.  In these
114     * cases, the JAXB Provider will set the severity of the ValidationEvent to
115     * FATAL_ERROR to indicate that the unmarshal, validate, or marshal operations 
116     * should be terminated.  The default event handler and 
117     * <tt>ValidationEventCollector</tt> utility class must terminate processing 
118     * after being notified of a fatal error.  Client applications that supply their 
119     * own <tt>ValidationEventHandler</tt> should also terminate processing after
120     * being notified of a fatal error.  If not, unexpected behaviour may occur.
121     * </blockquote>
122     *
123     * <p>
124     * <a name="supportedProps"></a>
125     * <b>Supported Properties</b><br>
126     * <blockquote>
127     * <p>
128     * There currently are not any properties required to be supported by all 
129     * JAXB Providers on Validator.  However, some providers may support 
130     * their own set of provider specific properties.
131     * </blockquote>
132     * 
133     * 
134     * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul> 
135     * @version $Revision: 1.19 $ $Date: 2002/11/21 00:21:57 $
136     * @see JAXBContext
137     * @see Unmarshaller
138     * @see ValidationEventHandler
139     * @see ValidationEvent
140     * @see javax.xml.bind.util.ValidationEventCollector
141     * @since JAXB1.0
142     */
143    public interface Validator {
144    
145        /**
146         * Allow an application to register a validation event handler.
147         * <p>
148         * The validation event handler will be called by the JAXB Provider if any
149         * validation errors are encountered during calls to 
150         * {@link #validate(Object) validate}.  If the client application does not 
151         * register a validation event handler before invoking the validate method, 
152         * then validation events will be handled by the default event handler which
153         * will terminate the validate operation after the first error or fatal error
154         * is encountered.
155         * <p>
156         * Calling this method with a null parameter will cause the Validator
157         * to revert back to the default vefault event handler.
158         *
159         * @param handler the validation event handler
160         * @throws JAXBException if an error was encountered while setting the
161         *         event handler
162         */
163        public void setEventHandler( ValidationEventHandler handler )
164            throws JAXBException;
165    
166        /**
167         * Return the current event handler or the default event handler if one
168         * hasn't been set.
169         *
170         * @return the current ValidationEventHandler or the default event handler
171         *         if it hasn't been set
172         * @throws JAXBException if an error was encountered while getting the 
173         *         current event handler
174         */
175        public ValidationEventHandler getEventHandler()
176            throws JAXBException;
177            
178        /**
179         * Validate the Java content tree starting at <tt>subrootObj</tt>.
180         * <p>
181         * Client applications can use this method to validate Java content trees
182         * on-demand at runtime.  This method can be used to validate any arbitrary
183         * subtree of the Java content tree.  Global constraint checking <b>will not
184         * </b> be performed as part of this operation (i.e. ID/IDREF constraints).
185         *
186         * @param subrootObj the obj to begin validation at
187         * @throws JAXBException if any unexpected problem occurs during validation
188         * @throws ValidationException 
189         *     If the {@link ValidationEventHandler ValidationEventHandler}
190         *     returns false from its <tt>handleEvent</tt> method or the 
191         *     <tt>Validator</tt> is unable to validate the content tree rooted 
192         *     at <tt>subrootObj</tt>
193         * @throws IllegalArgumentException
194         *      If the subrootObj parameter is null
195         * @return true if the subtree rooted at <tt>subrootObj</tt> is valid, false
196         *         otherwise
197         */
198        public boolean validate( Object subrootObj ) throws JAXBException;
199        
200        /**
201         * Validate the Java content tree rooted at <tt>rootObj</tt>.
202         * <p>
203         * Client applications can use this method to validate Java content trees
204         * on-demand at runtime.  This method is used to validate an entire Java
205         * content tree.  Global constraint checking <b>will</b> be performed as 
206         * part of this operation (i.e. ID/IDREF constraints).
207         *
208         * @param rootObj the root obj to begin validation at
209         * @throws JAXBException if any unexpected problem occurs during validation
210         * @throws ValidationException 
211         *     If the {@link ValidationEventHandler ValidationEventHandler}
212         *     returns false from its <tt>handleEvent</tt> method or the 
213         *     <tt>Validator</tt> is unable to validate the content tree rooted 
214         *     at <tt>rootObj</tt>
215         * @throws IllegalArgumentException
216         *      If the rootObj parameter is null
217         * @return true if the tree rooted at <tt>rootObj</tt> is valid, false
218         *         otherwise
219         */
220        public boolean validateRoot( Object rootObj ) throws JAXBException;
221    
222        /**
223         * Set the particular property in the underlying implementation of 
224         * <tt>Validator</tt>.  This method can only be used to set one of
225         * the standard JAXB defined properties above or a provider specific
226         * property.  Attempting to set an undefined property will result in
227         * a PropertyException being thrown.  See <a href="#supportedProps">
228         * Supported Properties</a>.
229         *
230         * @param name the name of the property to be set. This value can either
231         *              be specified using one of the constant fields or a user 
232         *              supplied string.
233         * @param value the value of the property to be set
234         *
235         * @throws PropertyException when there is an error processing the given
236         *                            property or value
237         * @throws IllegalArgumentException
238         *      If the name parameter is null
239         */
240        public void setProperty( String name, Object value ) 
241            throws PropertyException;
242        
243        /**
244         * Get the particular property in the underlying implementation of 
245         * <tt>Validator</tt>.  This method can only be used to get one of
246         * the standard JAXB defined properties above or a provider specific
247         * property.  Attempting to get 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 retrieve
252         * @return the value of the requested property
253         *
254         * @throws PropertyException
255         *      when there is an error retrieving the given property or value
256         *      property name
257         * @throws IllegalArgumentException
258         *      If the name parameter is null
259         */
260        public Object getProperty( String name ) throws PropertyException;
261        
262    }