aoqi@0: /* aoqi@0: * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. aoqi@0: * aoqi@0: * This code is free software; you can redistribute it and/or modify it aoqi@0: * under the terms of the GNU General Public License version 2 only, as aoqi@0: * published by the Free Software Foundation. Oracle designates this aoqi@0: * particular file as subject to the "Classpath" exception as provided aoqi@0: * by Oracle in the LICENSE file that accompanied this code. aoqi@0: * aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that aoqi@0: * accompanied this code). aoqi@0: * aoqi@0: * You should have received a copy of the GNU General Public License version aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation, aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. aoqi@0: * aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA aoqi@0: * or visit www.oracle.com if you need additional information or have any aoqi@0: * questions. aoqi@0: */ aoqi@0: aoqi@0: package javax.xml.bind; aoqi@0: aoqi@0: /** aoqi@0: * As of JAXB 2.0, this class is deprecated and optional. aoqi@0: *

aoqi@0: * The Validator class is responsible for controlling the validation aoqi@0: * of content trees during runtime. aoqi@0: * aoqi@0: *

aoqi@0: * aoqi@0: * Three Forms of Validation
aoqi@0: *

aoqi@0: *
aoqi@0: *
Unmarshal-Time Validation
aoqi@0: *
This form of validation enables a client application to receive aoqi@0: * information about validation errors and warnings detected while aoqi@0: * unmarshalling XML data into a Java content tree and is completely aoqi@0: * orthogonal to the other types of validation. To enable or disable aoqi@0: * it, see the javadoc for aoqi@0: * {@link Unmarshaller#setValidating(boolean) Unmarshaller.setValidating}. aoqi@0: * All JAXB 1.0 Providers are required to support this operation. aoqi@0: *
aoqi@0: * aoqi@0: *
On-Demand Validation
aoqi@0: *
This form of validation enables a client application to receive aoqi@0: * information about validation errors and warnings detected in the aoqi@0: * Java content tree. At any point, client applications can call aoqi@0: * the {@link Validator#validate(Object) Validator.validate} method aoqi@0: * on the Java content tree (or any sub-tree of it). All JAXB 1.0 aoqi@0: * Providers are required to support this operation. aoqi@0: *
aoqi@0: * aoqi@0: *
Fail-Fast Validation
aoqi@0: *
This form of validation enables a client application to receive aoqi@0: * immediate feedback about modifications to the Java content tree aoqi@0: * that violate type constraints on Java Properties as defined in aoqi@0: * the specification. JAXB Providers are not required support aoqi@0: * this type of validation. Of the JAXB Providers that do support aoqi@0: * this type of validation, some may require you to decide at schema aoqi@0: * compile time whether or not a client application will be allowed aoqi@0: * to request fail-fast validation at runtime. aoqi@0: *
aoqi@0: *
aoqi@0: *
aoqi@0: * aoqi@0: *

aoqi@0: * The Validator class is responsible for managing On-Demand Validation. aoqi@0: * The Unmarshaller class is responsible for managing Unmarshal-Time aoqi@0: * Validation during the unmarshal operations. Although there is no formal aoqi@0: * method of enabling validation during the marshal operations, the aoqi@0: * Marshaller may detect errors, which will be reported to the aoqi@0: * ValidationEventHandler registered on it. aoqi@0: * aoqi@0: *

aoqi@0: * aoqi@0: * Using the Default EventHandler
aoqi@0: *

aoqi@0: * If the client application does not set an event handler on their aoqi@0: * Validator, Unmarshaller, or Marshaller prior to aoqi@0: * calling the validate, unmarshal, or marshal methods, then a default event aoqi@0: * handler will receive notification of any errors or warnings encountered. aoqi@0: * The default event handler will cause the current operation to halt after aoqi@0: * encountering the first error or fatal error (but will attempt to continue aoqi@0: * after receiving warnings). aoqi@0: *
aoqi@0: * aoqi@0: *

aoqi@0: * aoqi@0: * Handling Validation Events
aoqi@0: *

aoqi@0: * There are three ways to handle events encountered during the unmarshal, aoqi@0: * validate, and marshal operations: aoqi@0: *
aoqi@0: *
Use the default event handler
aoqi@0: *
The default event handler will be used if you do not specify one aoqi@0: * via the setEventHandler API's on Validator, aoqi@0: * Unmarshaller, or Marshaller. aoqi@0: *
aoqi@0: * aoqi@0: *
Implement and register a custom event handler
aoqi@0: *
Client applications that require sophisticated event processing aoqi@0: * can implement the ValidationEventHandler interface and aoqi@0: * register it with the Unmarshaller and/or aoqi@0: * Validator. aoqi@0: *
aoqi@0: * aoqi@0: *
Use the {@link javax.xml.bind.util.ValidationEventCollector ValidationEventCollector} aoqi@0: * utility
aoqi@0: *
For convenience, a specialized event handler is provided that aoqi@0: * simply collects any ValidationEvent objects created aoqi@0: * during the unmarshal, validate, and marshal operations and aoqi@0: * returns them to the client application as a aoqi@0: * java.util.Collection. aoqi@0: *
aoqi@0: *
aoqi@0: *
aoqi@0: * aoqi@0: *

aoqi@0: * Validation and Well-Formedness
aoqi@0: *

aoqi@0: *

aoqi@0: * Validation events are handled differently depending on how the client aoqi@0: * application is configured to process them as described in the previous aoqi@0: * section. However, there are certain cases where a JAXB Provider indicates aoqi@0: * that it is no longer able to reliably detect and report errors. In these aoqi@0: * cases, the JAXB Provider will set the severity of the ValidationEvent to aoqi@0: * FATAL_ERROR to indicate that the unmarshal, validate, or marshal operations aoqi@0: * should be terminated. The default event handler and aoqi@0: * ValidationEventCollector utility class must terminate processing aoqi@0: * after being notified of a fatal error. Client applications that supply their aoqi@0: * own ValidationEventHandler should also terminate processing after aoqi@0: * being notified of a fatal error. If not, unexpected behaviour may occur. aoqi@0: *

aoqi@0: * aoqi@0: *

aoqi@0: * aoqi@0: * Supported Properties
aoqi@0: *

aoqi@0: *

aoqi@0: * There currently are not any properties required to be supported by all aoqi@0: * JAXB Providers on Validator. However, some providers may support aoqi@0: * their own set of provider specific properties. aoqi@0: *

aoqi@0: * aoqi@0: * aoqi@0: * @author aoqi@0: * @see JAXBContext aoqi@0: * @see Unmarshaller aoqi@0: * @see ValidationEventHandler aoqi@0: * @see ValidationEvent aoqi@0: * @see javax.xml.bind.util.ValidationEventCollector aoqi@0: * @since JAXB1.0 aoqi@0: * @deprecated since JAXB 2.0 aoqi@0: */ aoqi@0: public interface Validator { aoqi@0: aoqi@0: /** aoqi@0: * Allow an application to register a validation event handler. aoqi@0: *

aoqi@0: * The validation event handler will be called by the JAXB Provider if any aoqi@0: * validation errors are encountered during calls to aoqi@0: * {@link #validate(Object) validate}. If the client application does not aoqi@0: * register a validation event handler before invoking the validate method, aoqi@0: * then validation events will be handled by the default event handler which aoqi@0: * will terminate the validate operation after the first error or fatal error aoqi@0: * is encountered. aoqi@0: *

aoqi@0: * Calling this method with a null parameter will cause the Validator aoqi@0: * to revert back to the default default event handler. aoqi@0: * aoqi@0: * @param handler the validation event handler aoqi@0: * @throws JAXBException if an error was encountered while setting the aoqi@0: * event handler aoqi@0: * @deprecated since JAXB2.0 aoqi@0: */ aoqi@0: public void setEventHandler( ValidationEventHandler handler ) aoqi@0: throws JAXBException; aoqi@0: aoqi@0: /** aoqi@0: * Return the current event handler or the default event handler if one aoqi@0: * hasn't been set. aoqi@0: * aoqi@0: * @return the current ValidationEventHandler or the default event handler aoqi@0: * if it hasn't been set aoqi@0: * @throws JAXBException if an error was encountered while getting the aoqi@0: * current event handler aoqi@0: * @deprecated since JAXB2.0 aoqi@0: */ aoqi@0: public ValidationEventHandler getEventHandler() aoqi@0: throws JAXBException; aoqi@0: aoqi@0: /** aoqi@0: * Validate the Java content tree starting at subrootObj. aoqi@0: *

aoqi@0: * Client applications can use this method to validate Java content trees aoqi@0: * on-demand at runtime. This method can be used to validate any arbitrary aoqi@0: * subtree of the Java content tree. Global constraint checking will not aoqi@0: * be performed as part of this operation (i.e. ID/IDREF constraints). aoqi@0: * aoqi@0: * @param subrootObj the obj to begin validation at aoqi@0: * @throws JAXBException if any unexpected problem occurs during validation aoqi@0: * @throws ValidationException aoqi@0: * If the {@link ValidationEventHandler ValidationEventHandler} aoqi@0: * returns false from its handleEvent method or the aoqi@0: * Validator is unable to validate the content tree rooted aoqi@0: * at subrootObj aoqi@0: * @throws IllegalArgumentException aoqi@0: * If the subrootObj parameter is null aoqi@0: * @return true if the subtree rooted at subrootObj is valid, false aoqi@0: * otherwise aoqi@0: * @deprecated since JAXB2.0 aoqi@0: */ aoqi@0: public boolean validate( Object subrootObj ) throws JAXBException; aoqi@0: aoqi@0: /** aoqi@0: * Validate the Java content tree rooted at rootObj. aoqi@0: *

aoqi@0: * Client applications can use this method to validate Java content trees aoqi@0: * on-demand at runtime. This method is used to validate an entire Java aoqi@0: * content tree. Global constraint checking will be performed as aoqi@0: * part of this operation (i.e. ID/IDREF constraints). aoqi@0: * aoqi@0: * @param rootObj the root obj to begin validation at aoqi@0: * @throws JAXBException if any unexpected problem occurs during validation aoqi@0: * @throws ValidationException aoqi@0: * If the {@link ValidationEventHandler ValidationEventHandler} aoqi@0: * returns false from its handleEvent method or the aoqi@0: * Validator is unable to validate the content tree rooted aoqi@0: * at rootObj aoqi@0: * @throws IllegalArgumentException aoqi@0: * If the rootObj parameter is null aoqi@0: * @return true if the tree rooted at rootObj is valid, false aoqi@0: * otherwise aoqi@0: * @deprecated since JAXB2.0 aoqi@0: */ aoqi@0: public boolean validateRoot( Object rootObj ) throws JAXBException; aoqi@0: aoqi@0: /** aoqi@0: * Set the particular property in the underlying implementation of aoqi@0: * Validator. This method can only be used to set one of aoqi@0: * the standard JAXB defined properties above or a provider specific aoqi@0: * property. Attempting to set an undefined property will result in aoqi@0: * a PropertyException being thrown. See aoqi@0: * Supported Properties. aoqi@0: * aoqi@0: * @param name the name of the property to be set. This value can either aoqi@0: * be specified using one of the constant fields or a user aoqi@0: * supplied string. aoqi@0: * @param value the value of the property to be set aoqi@0: * aoqi@0: * @throws PropertyException when there is an error processing the given aoqi@0: * property or value aoqi@0: * @throws IllegalArgumentException aoqi@0: * If the name parameter is null aoqi@0: * @deprecated since JAXB2.0 aoqi@0: */ aoqi@0: public void setProperty( String name, Object value ) aoqi@0: throws PropertyException; aoqi@0: aoqi@0: /** aoqi@0: * Get the particular property in the underlying implementation of aoqi@0: * Validator. This method can only be used to get one of aoqi@0: * the standard JAXB defined properties above or a provider specific aoqi@0: * property. Attempting to get an undefined property will result in aoqi@0: * a PropertyException being thrown. See aoqi@0: * Supported Properties. aoqi@0: * aoqi@0: * @param name the name of the property to retrieve aoqi@0: * @return the value of the requested property aoqi@0: * aoqi@0: * @throws PropertyException aoqi@0: * when there is an error retrieving the given property or value aoqi@0: * property name aoqi@0: * @throws IllegalArgumentException aoqi@0: * If the name parameter is null aoqi@0: * @deprecated since JAXB2.0 aoqi@0: */ aoqi@0: public Object getProperty( String name ) throws PropertyException; aoqi@0: aoqi@0: }