1 /*
2 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.xml.transform;
27
28 /**
29 * <p>To provide customized error handling, implement this interface and
30 * use the <code>setErrorListener</code> method to register an instance of the
31 * implmentation with the {@link javax.xml.transform.Transformer}. The
32 * <code>Transformer</code> then reports all errors and warnings through this
33 * interface.</p>
34 *
35 * <p>If an application does <em>not</em> register its own custom
36 * <code>ErrorListener</code>, the default <code>ErrorListener</code>
37 * is used which reports all warnings and errors to <code>System.err</code>
38 * and does not throw any <code>Exception</code>s.
39 * Applications are <em>strongly</em> encouraged to register and use
40 * <code>ErrorListener</code>s that insure proper behavior for warnings and
41 * errors.</p>
42 *
43 * <p>For transformation errors, a <code>Transformer</code> must use this
44 * interface instead of throwing an <code>Exception</code>: it is up to the
45 * application to decide whether to throw an <code>Exception</code> for
46 * different types of errors and warnings. Note however that the
47 * <code>Transformer</code> is not required to continue with the transformation
48 * after a call to {@link #fatalError(TransformerException exception)}.</p>
49 *
50 * <p><code>Transformer</code>s may use this mechanism to report XML parsing
51 * errors as well as transformation errors.</p>
52 */
53 public interface ErrorListener {
54
55 /**
56 * Receive notification of a warning.
57 *
58 * <p>{@link javax.xml.transform.Transformer} can use this method to report
59 * conditions that are not errors or fatal errors. The default behaviour
60 * is to take no action.</p>
61 *
62 * <p>After invoking this method, the Transformer must continue with
63 * the transformation. It should still be possible for the
64 * application to process the document through to the end.</p>
65 *
66 * @param exception The warning information encapsulated in a
67 * transformer exception.
68 *
69 * @throws javax.xml.transform.TransformerException if the application
70 * chooses to discontinue the transformation.
71 *
72 * @see javax.xml.transform.TransformerException
73 */
74 public abstract void warning(TransformerException exception)
75 throws TransformerException;
76
77 /**
78 * Receive notification of a recoverable error.
79 *
80 * <p>The transformer must continue to try and provide normal transformation
81 * after invoking this method. It should still be possible for the
82 * application to process the document through to the end if no other errors
83 * are encountered.</p>
84 *
85 * @param exception The error information encapsulated in a
86 * transformer exception.
87 *
88 * @throws javax.xml.transform.TransformerException if the application
89 * chooses to discontinue the transformation.
90 *
91 * @see javax.xml.transform.TransformerException
92 */
93 public abstract void error(TransformerException exception)
94 throws TransformerException;
95
96 /**
97 * <p>Receive notification of a non-recoverable error.</p>
98 *
99 * <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 }
Save This Page