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 20 package 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 */ 47 public 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 */ warning(TransformerException exception)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 */ error(TransformerException exception)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 */ fatalError(TransformerException exception)107 public abstract void fatalError(TransformerException exception) 108 throws TransformerException; 109 } 110