001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.transform;
027
028 /**
029 * <p>To provide customized error handling, implement this interface and
030 * use the <code>setErrorListener</code> method to register an instance of the
031 * implmentation with the {@link javax.xml.transform.Transformer}. The
032 * <code>Transformer</code> then reports all errors and warnings through this
033 * interface.</p>
034 *
035 * <p>If an application does <em>not</em> register its own custom
036 * <code>ErrorListener</code>, the default <code>ErrorListener</code>
037 * is used which reports all warnings and errors to <code>System.err</code>
038 * and does not throw any <code>Exception</code>s.
039 * Applications are <em>strongly</em> encouraged to register and use
040 * <code>ErrorListener</code>s that insure proper behavior for warnings and
041 * errors.</p>
042 *
043 * <p>For transformation errors, a <code>Transformer</code> must use this
044 * interface instead of throwing an <code>Exception</code>: it is up to the
045 * application to decide whether to throw an <code>Exception</code> for
046 * different types of errors and warnings. Note however that the
047 * <code>Transformer</code> is not required to continue with the transformation
048 * after a call to {@link #fatalError(TransformerException exception)}.</p>
049 *
050 * <p><code>Transformer</code>s may use this mechanism to report XML parsing
051 * errors as well as transformation errors.</p>
052 */
053 public interface ErrorListener {
054
055 /**
056 * Receive notification of a warning.
057 *
058 * <p>{@link javax.xml.transform.Transformer} can use this method to report
059 * conditions that are not errors or fatal errors. The default behaviour
060 * is to take no action.</p>
061 *
062 * <p>After invoking this method, the Transformer must continue with
063 * the transformation. It should still be possible for the
064 * application to process the document through to the end.</p>
065 *
066 * @param exception The warning information encapsulated in a
067 * transformer exception.
068 *
069 * @throws javax.xml.transform.TransformerException if the application
070 * chooses to discontinue the transformation.
071 *
072 * @see javax.xml.transform.TransformerException
073 */
074 public abstract void warning(TransformerException exception)
075 throws TransformerException;
076
077 /**
078 * Receive notification of a recoverable error.
079 *
080 * <p>The transformer must continue to try and provide normal transformation
081 * after invoking this method. It should still be possible for the
082 * application to process the document through to the end if no other errors
083 * are encountered.</p>
084 *
085 * @param exception The error information encapsulated in a
086 * transformer exception.
087 *
088 * @throws javax.xml.transform.TransformerException if the application
089 * chooses to discontinue the transformation.
090 *
091 * @see javax.xml.transform.TransformerException
092 */
093 public abstract void error(TransformerException exception)
094 throws TransformerException;
095
096 /**
097 * <p>Receive notification of a non-recoverable error.</p>
098 *
099 * <p>The processor may choose to continue, but will not normally
100 * proceed to a successful completion.</p>
101 *
102 * <p>The method should throw an exception if it is unable to
103 * process the error, or if it wishes execution to terminate
104 * immediately. The processor will not necessarily honor this
105 * request.</p>
106 *
107 * @param exception The error information encapsulated in a
108 * <code>TransformerException</code>.
109 *
110 * @throws javax.xml.transform.TransformerException if the application
111 * chooses to discontinue the transformation.
112 *
113 * @see javax.xml.transform.TransformerException
114 */
115 public abstract void fatalError(TransformerException exception)
116 throws TransformerException;
117 }
|