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