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

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

ohair@286: * ohair@286: * Three Forms of Validation
ohair@286: *

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

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

ohair@286: * ohair@286: * Using the Default EventHandler
ohair@286: *

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

ohair@286: * ohair@286: * Handling Validation Events
ohair@286: *

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

ohair@286: * Validation and Well-Formedness
ohair@286: *

ohair@286: *

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

ohair@286: * ohair@286: *

ohair@286: * ohair@286: * Supported Properties
ohair@286: *

ohair@286: *

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

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

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

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

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

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