jdk8-mips64-public/jaxws: src/share/jaxws_classes/javax/xml/bind/Validator.java@b0610cd08440 (annotated)

src/share/jaxws_classes/javax/xml/bind/Validator.java@b0610cd08440 (annotated)

src/share/jaxws_classes/javax/xml/bind/Validator.java

Fri, 04 Oct 2013 16:21:34 +0100

author: mkos
date: Fri, 04 Oct 2013 16:21:34 +0100
changeset 408: b0610cd08440
parent 397: b99d7e355d4b
child 637: 9c07ef4934dd
permissions: -rw-r--r--

8025054: Update JAX-WS RI integration to 2.2.9-b130926.1035
Reviewed-by: chegar

 /*
  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * version 2 for more details (a copy is included in the LICENSE file that
  * accompanied this code).
  *
  * You should have received a copy of the GNU General Public License version
  * 2 along with this work; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  *
  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
 package javax.xml.bind;
 /**
  * As of JAXB 2.0, this class is deprecated and optional.
  * <p>
  * The <tt>Validator</tt> class is responsible for controlling the validation
  * of content trees during runtime.
  *
  * <p>
  * <a name="validationtypes"></a>
  * <b>Three Forms of Validation</b><br>
  * <blockquote>
  *    <dl>
  *        <dt><b>Unmarshal-Time Validation</b></dt>
  *        <dd>This form of validation enables a client application to receive
  *            information about validation errors and warnings detected while
  *            unmarshalling XML data into a Java content tree and is completely
  *            orthogonal to the other types of validation.  To enable or disable
  *            it, see the javadoc for
  *            {@link Unmarshaller#setValidating(boolean) Unmarshaller.setValidating}.
  *            All JAXB 1.0 Providers are required to support this operation.
  *        </dd>
  *
  *        <dt><b>On-Demand Validation</b></dt>
  *        <dd> This form of validation enables a client application to receive
  *             information about validation errors and warnings detected in the
  *             Java content tree.  At any point, client applications can call
  *             the {@link Validator#validate(Object) Validator.validate} method
  *             on the Java content tree (or any sub-tree of it).  All JAXB 1.0
  *             Providers are required to support this operation.
  *        </dd>
  *
  *        <dt><b>Fail-Fast Validation</b></dt>
  *        <dd> This form of validation enables a client application to receive
  *             immediate feedback about modifications to the Java content tree
  *             that violate type constraints on Java Properties as defined in
  *             the specification.  JAXB Providers are not required support
  *             this type of validation.  Of the JAXB Providers that do support
  *             this type of validation, some may require you to decide at schema
  *             compile time whether or not a client application will be allowed
  *             to request fail-fast validation at runtime.
  *        </dd>
  *    </dl>
  * </blockquote>
  *
  * <p>
  * The <tt>Validator</tt> class is responsible for managing On-Demand Validation.
  * The <tt>Unmarshaller</tt> class is responsible for managing Unmarshal-Time
  * Validation during the unmarshal operations.  Although there is no formal
  * method of enabling validation during the marshal operations, the
  * <tt>Marshaller</tt> may detect errors, which will be reported to the
  * <tt>ValidationEventHandler</tt> registered on it.
  *
  * <p>
  * <a name="defaulthandler"></a>
  * <b>Using the Default EventHandler</b><br>
  * <blockquote>
  *   If the client application does not set an event handler on their
  *   <tt>Validator</tt>, <tt>Unmarshaller</tt>, or <tt>Marshaller</tt> prior to
  *   calling the validate, unmarshal, or marshal methods, then a default event
  *   handler will receive notification of any errors or warnings encountered.
  *   The default event handler will cause the current operation to halt after
  *   encountering the first error or fatal error (but will attempt to continue
  *   after receiving warnings).
  * </blockquote>
  *
  * <p>
  * <a name="handlingevents"></a>
  * <b>Handling Validation Events</b><br>
  * <blockquote>
  *   There are three ways to handle events encountered during the unmarshal,
  *   validate, and marshal operations:
  *    <dl>
  *        <dt>Use the default event handler</dt>
  *        <dd>The default event handler will be used if you do not specify one
  *            via the <tt>setEventHandler</tt> API's on <tt>Validator</tt>,
  *            <tt>Unmarshaller</tt>, or <tt>Marshaller</tt>.
  *        </dd>
  *
  *        <dt>Implement and register a custom event handler</dt>
  *        <dd>Client applications that require sophisticated event processing
  *            can implement the <tt>ValidationEventHandler</tt> interface and
  *            register it with the <tt>Unmarshaller</tt> and/or
  *            <tt>Validator</tt>.
  *        </dd>
  *
  *        <dt>Use the {@link javax.xml.bind.util.ValidationEventCollector ValidationEventCollector}
  *            utility</dt>
  *        <dd>For convenience, a specialized event handler is provided that
  *            simply collects any <tt>ValidationEvent</tt> objects created
  *            during the unmarshal, validate, and marshal operations and
  *            returns them to the client application as a
  *            <tt>java.util.Collection</tt>.
  *        </dd>
  *    </dl>
  * </blockquote>
  *
  * <p>
  * <b>Validation and Well-Formedness</b><br>
  * <blockquote>
  * <p>
  * Validation events are handled differently depending on how the client
  * application is configured to process them as described in the previous
  * section.  However, there are certain cases where a JAXB Provider indicates
  * that it is no longer able to reliably detect and report errors.  In these
  * cases, the JAXB Provider will set the severity of the ValidationEvent to
  * FATAL_ERROR to indicate that the unmarshal, validate, or marshal operations
  * should be terminated.  The default event handler and
  * <tt>ValidationEventCollector</tt> utility class must terminate processing
  * after being notified of a fatal error.  Client applications that supply their
  * own <tt>ValidationEventHandler</tt> should also terminate processing after
  * being notified of a fatal error.  If not, unexpected behaviour may occur.
  * </blockquote>
  *
  * <p>
  * <a name="supportedProps"></a>
  * <b>Supported Properties</b><br>
  * <blockquote>
  * <p>
  * There currently are not any properties required to be supported by all
  * JAXB Providers on Validator.  However, some providers may support
  * their own set of provider specific properties.
  * </blockquote>
  *
  *
  * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
  * @see JAXBContext
  * @see Unmarshaller
  * @see ValidationEventHandler
  * @see ValidationEvent
  * @see javax.xml.bind.util.ValidationEventCollector
  * @since JAXB1.0
  * @deprecated since JAXB 2.0
  */
 public interface Validator {
     /**
      * Allow an application to register a validation event handler.
      * <p>
      * The validation event handler will be called by the JAXB Provider if any
      * validation errors are encountered during calls to
      * {@link #validate(Object) validate}.  If the client application does not
      * register a validation event handler before invoking the validate method,
      * then validation events will be handled by the default event handler which
      * will terminate the validate operation after the first error or fatal error
      * is encountered.
      * <p>
      * Calling this method with a null parameter will cause the Validator
      * to revert back to the default default event handler.
      *
      * @param handler the validation event handler
      * @throws JAXBException if an error was encountered while setting the
      *         event handler
      * @deprecated since JAXB2.0
      */
     public void setEventHandler( ValidationEventHandler handler )
         throws JAXBException;
     /**
      * Return the current event handler or the default event handler if one
      * hasn't been set.
      *
      * @return the current ValidationEventHandler or the default event handler
      *         if it hasn't been set
      * @throws JAXBException if an error was encountered while getting the
      *         current event handler
      * @deprecated since JAXB2.0
      */
     public ValidationEventHandler getEventHandler()
         throws JAXBException;
     /**
      * Validate the Java content tree starting at <tt>subrootObj</tt>.
      * <p>
      * Client applications can use this method to validate Java content trees
      * on-demand at runtime.  This method can be used to validate any arbitrary
      * subtree of the Java content tree.  Global constraint checking <b>will not
      * </b> be performed as part of this operation (i.e. ID/IDREF constraints).
      *
      * @param subrootObj the obj to begin validation at
      * @throws JAXBException if any unexpected problem occurs during validation
      * @throws ValidationException
      *     If the {@link ValidationEventHandler ValidationEventHandler}
      *     returns false from its <tt>handleEvent</tt> method or the
      *     <tt>Validator</tt> is unable to validate the content tree rooted
      *     at <tt>subrootObj</tt>
      * @throws IllegalArgumentException
      *      If the subrootObj parameter is null
      * @return true if the subtree rooted at <tt>subrootObj</tt> is valid, false
      *         otherwise
      * @deprecated since JAXB2.0
      */
     public boolean validate( Object subrootObj ) throws JAXBException;
     /**
      * Validate the Java content tree rooted at <tt>rootObj</tt>.
      * <p>
      * Client applications can use this method to validate Java content trees
      * on-demand at runtime.  This method is used to validate an entire Java
      * content tree.  Global constraint checking <b>will</b> be performed as
      * part of this operation (i.e. ID/IDREF constraints).
      *
      * @param rootObj the root obj to begin validation at
      * @throws JAXBException if any unexpected problem occurs during validation
      * @throws ValidationException
      *     If the {@link ValidationEventHandler ValidationEventHandler}
      *     returns false from its <tt>handleEvent</tt> method or the
      *     <tt>Validator</tt> is unable to validate the content tree rooted
      *     at <tt>rootObj</tt>
      * @throws IllegalArgumentException
      *      If the rootObj parameter is null
      * @return true if the tree rooted at <tt>rootObj</tt> is valid, false
      *         otherwise
      * @deprecated since JAXB2.0
      */
     public boolean validateRoot( Object rootObj ) throws JAXBException;
     /**
      * Set the particular property in the underlying implementation of
      * <tt>Validator</tt>.  This method can only be used to set one of
      * the standard JAXB defined properties above or a provider specific
      * property.  Attempting to set an undefined property will result in
      * a PropertyException being thrown.  See <a href="#supportedProps">
      * Supported Properties</a>.
      *
      * @param name the name of the property to be set. This value can either
      *              be specified using one of the constant fields or a user
      *              supplied string.
      * @param value the value of the property to be set
      *
      * @throws PropertyException when there is an error processing the given
      *                            property or value
      * @throws IllegalArgumentException
      *      If the name parameter is null
      * @deprecated since JAXB2.0
      */
     public void setProperty( String name, Object value )
         throws PropertyException;
     /**
      * Get the particular property in the underlying implementation of
      * <tt>Validator</tt>.  This method can only be used to get one of
      * the standard JAXB defined properties above or a provider specific
      * property.  Attempting to get an undefined property will result in
      * a PropertyException being thrown.  See <a href="#supportedProps">
      * Supported Properties</a>.
      *
      * @param name the name of the property to retrieve
      * @return the value of the requested property
      *
      * @throws PropertyException
      *      when there is an error retrieving the given property or value
      *      property name
      * @throws IllegalArgumentException
      *      If the name parameter is null
      * @deprecated since JAXB2.0
      */
     public Object getProperty( String name ) throws PropertyException;
 }

Mercurial > jdk8-mips64-public > jaxws / annotate

src/share/jaxws_classes/javax/xml/bind/Validator.java@b0610cd08440 (annotated)

src/share/jaxws_classes/javax/xml/bind/Validator.java