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 }