1 /* 2 * Copyright (c) 2000, 2005, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * 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 * implementation 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 }