1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18// $Id: ErrorListener.java 569994 2007-08-27 04:28:57Z mrglavas $
19
20package javax.xml.transform;
21
22/**
23 * <p>To provide customized error handling, implement this interface and
24 * use the <code>setErrorListener</code> method to register an instance of the
25 * implementation with the {@link javax.xml.transform.Transformer}.  The
26 * <code>Transformer</code> then reports all errors and warnings through this
27 * interface.</p>
28 *
29 * <p>If an application does <em>not</em> register its own custom
30 * <code>ErrorListener</code>, the default <code>ErrorListener</code>
31 * is used which reports all warnings and errors to <code>System.err</code>
32 * and does not throw any <code>Exception</code>s.
33 * Applications are <em>strongly</em> encouraged to register and use
34 * <code>ErrorListener</code>s that insure proper behavior for warnings and
35 * errors.</p>
36 *
37 * <p>For transformation errors, a <code>Transformer</code> must use this
38 * interface instead of throwing an <code>Exception</code>: it is up to the
39 * application to decide whether to throw an <code>Exception</code> for
40 * different types of errors and warnings.  Note however that the
41 * <code>Transformer</code> is not required to continue with the transformation
42 * after a call to {@link #fatalError(TransformerException exception)}.</p>
43 *
44 * <p><code>Transformer</code>s may use this mechanism to report XML parsing
45 * errors as well as transformation errors.</p>
46 */
47public interface ErrorListener {
48
49    /**
50     * Receive notification of a warning.
51     *
52     * <p>{@link javax.xml.transform.Transformer} can use this method to report
53     * conditions that are not errors or fatal errors.  The default behavior
54     * is to take no action.</p>
55     *
56     * <p>After invoking this method, the Transformer must continue with
57     * the transformation. It should still be possible for the
58     * application to process the document through to the end.</p>
59     *
60     * @param exception The warning information encapsulated in a
61     *                  transformer exception.
62     *
63     * @throws javax.xml.transform.TransformerException if the application
64     * chooses to discontinue the transformation.
65     *
66     * @see javax.xml.transform.TransformerException
67     */
68    public abstract void warning(TransformerException exception)
69        throws TransformerException;
70
71    /**
72     * Receive notification of a recoverable error.
73     *
74     * <p>The transformer must continue to try and provide normal transformation
75     * after invoking this method.  It should still be possible for the
76     * application to process the document through to the end if no other errors
77     * are encountered.</p>
78     *
79     * @param exception The error information encapsulated in a
80     *                  transformer exception.
81     *
82     * @throws javax.xml.transform.TransformerException if the application
83     * chooses to discontinue the transformation.
84     *
85     * @see javax.xml.transform.TransformerException
86     */
87    public abstract void error(TransformerException exception)
88        throws TransformerException;
89
90    /**
91     * <p>Receive notification of a non-recoverable error.</p>
92     *
93     * <p>The <code>Transformer</code> must continue to try and provide normal
94     * transformation after invoking this method.  It should still be possible for the
95     * application to process the document through to the end if no other errors
96     * are encountered, but there is no guarantee that the output will be
97     * useable.</p>
98     *
99     * @param exception The error information encapsulated in a
100     *    <code>TransformerException</code>.
101     *
102     * @throws javax.xml.transform.TransformerException if the application
103     * chooses to discontinue the transformation.
104     *
105     * @see javax.xml.transform.TransformerException
106     */
107    public abstract void fatalError(TransformerException exception)
108        throws TransformerException;
109}
110