Source Home >> Java Source 1.6.0 >> javax.xml.transform.ErrorListener V 0.09

001/*
002 * The contents of this file are subject to the terms
003 * of the Common Development and Distribution License
004 * (the "License").  You may not use this file except
005 * in compliance with the License.
006 *
007 * You can obtain a copy of the license at
008 * https://jaxp.dev.java.net/CDDLv1.0.html.
009 * See the License for the specific language governing
010 * permissions and limitations under the License.
011 *
012 * When distributing Covered Code, include this CDDL
013 * HEADER in each file and include the License file at
014 * https://jaxp.dev.java.net/CDDLv1.0.html
015 * If applicable add the following below this CDDL HEADER
016 * with the fields enclosed by brackets "[]" replaced with
017 * your own identifying information: Portions Copyright
018 * [year] [name of copyright owner]
019 */
020
021/*
022 * $Id: XMLEntityReader.java,v 1.3 2005/11/03 17:02:21 jeffsuttor Exp $
023 * @(#)ErrorListener.java	1.21 05/11/17
024 *
025 * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
026 */
027
028package javax.xml.transform;
029
030/**
031 * <p>To provide customized error handling, implement this interface and
032 * use the <code>setErrorListener</code> method to register an instance of the
033 * implmentation with the {@link javax.xml.transform.Transformer}.  The
034 * <code>Transformer</code> then reports all errors and warnings through this
035 * interface.</p>
036 *
037 * <p>If an application does <em>not</em> register its own custom
038 * <code>ErrorListener</code>, the default <code>ErrorListener</code>
039 * is used which reports all warnings and errors to <code>System.err</code>
040 * and does not throw any <code>Exception</code>s.
041 * Applications are <em>strongly</em> encouraged to register and use
042 * <code>ErrorListener</code>s that insure proper behavior for warnings and
043 * errors.</p>
044 *
045 * <p>For transformation errors, a <code>Transformer</code> must use this
046 * interface instead of throwing an <code>Exception</code>: it is up to the
047 * application to decide whether to throw an <code>Exception</code> for
048 * different types of errors and warnings.  Note however that the
049 * <code>Transformer</code> is not required to continue with the transformation
050 * after a call to {@link #fatalError(TransformerException exception)}.</p>
051 *
052 * <p><code>Transformer</code>s may use this mechanism to report XML parsing
053 * errors as well as transformation errors.</p>
054 */
055public interface ErrorListener {
056
057    /**
058     * Receive notification of a warning.
059     *
060     * <p>{@link javax.xml.transform.Transformer} can use this method to report
061     * conditions that are not errors or fatal errors.  The default behaviour
062     * is to take no action.</p>
063     *
064     * <p>After invoking this method, the Transformer must continue with
065     * the transformation. It should still be possible for the
066     * application to process the document through to the end.</p>
067     *
068     * @param exception The warning information encapsulated in a
069     *                  transformer exception.
070     *
071     * @throws javax.xml.transform.TransformerException if the application
072     * chooses to discontinue the transformation.
073     *
074     * @see javax.xml.transform.TransformerException
075     */
076    public abstract void warning(TransformerException exception)
077        throws TransformerException;
078
079    /**
080     * Receive notification of a recoverable error.
081     *
082     * <p>The transformer must continue to try and provide normal transformation
083     * after invoking this method.  It should still be possible for the
084     * application to process the document through to the end if no other errors
085     * are encountered.</p>
086     *
087     * @param exception The error information encapsulated in a
088     *                  transformer exception.
089     *
090     * @throws javax.xml.transform.TransformerException if the application
091     * chooses to discontinue the transformation.
092     *
093     * @see javax.xml.transform.TransformerException
094     */
095    public abstract void error(TransformerException exception)
096        throws TransformerException;
097
098    /**
099     * <p>Receive notification of a non-recoverable error.</p>
100     *
101     * <p>The processor may choose to continue, but will not normally
102     * proceed to a successful completion.</p>
103     *
104     * <p>The method should throw an exception if it is unable to
105     * process the error, or if it wishes execution to terminate
106     * immediately. The processor will not necessarily honor this
107     * request.</p>
108     *
109     * @param exception The error information encapsulated in a
110     *    <code>TransformerException</code>.
111     *
112     * @throws javax.xml.transform.TransformerException if the application
113     * chooses to discontinue the transformation.
114     *
115     * @see javax.xml.transform.TransformerException
116     */
117    public abstract void fatalError(TransformerException exception)
118        throws TransformerException;
119}