ErrorListener


1   // $Id: ErrorListener.java,v 1.2 2003/09/19 10:10:13 jsuttor Exp $
2   /*
3    * @(#)ErrorListener.java   1.12 04/07/26
4    * 
5    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
6    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
7    */
8   
9   package javax.xml.transform;
10  
11  /**
12   * <p>To provide customized error handling, implement this interface and
13   * use the <code>setErrorListener</code> method to register an instance of the
14   * implmentation with the {@link javax.xml.transform.Transformer}.  The
15   * <code>Transformer</code> then reports all errors and warnings through this
16   * interface.</p>
17   *
18   * <p>If an application does <em>not</em> register its own custom
19   * <code>ErrorListener</code>, the default <code>ErrorListener</code>
20   * is used which reports all warnings and errors to <code>System.err</code>
21   * and does not throw any <code>Exception</code>s.
22   * Applications are <em>strongly</em> encouraged to register and use
23   * <code>ErrorListener</code>s that insure proper behavior for warnings and
24   * errors.</p>
25   *
26   * <p>For transformation errors, a <code>Transformer</code> must use this
27   * interface instead of throwing an <code>Exception</code>: it is up to the
28   * application to decide whether to throw an <code>Exception</code> for
29   * different types of errors and warnings.  Note however that the
30   * <code>Transformer</code> is not required to continue with the transformation
31   * after a call to {@link #fatalError(TransformerException exception)}.</p>
32   *
33   * <p><code>Transformer</code>s may use this mechanism to report XML parsing
34   * errors as well as transformation errors.</p>
35   */
36  public interface ErrorListener {
37  
38      /**
39       * Receive notification of a warning.
40       *
41       * <p>{@link javax.xml.transform.Transformer} can use this method to report
42       * conditions that are not errors or fatal errors.  The default behaviour
43       * is to take no action.</p>
44       *
45       * <p>After invoking this method, the Transformer must continue with
46       * the transformation. It should still be possible for the
47       * application to process the document through to the end.</p>
48       *
49       * @param exception The warning information encapsulated in a
50       *                  transformer exception.
51       *
52       * @throws javax.xml.transform.TransformerException if the application
53       * chooses to discontinue the transformation.
54       *
55       * @see javax.xml.transform.TransformerException
56       */
57      public abstract void warning(TransformerException   exception)
58          throws TransformerException  ;
59  
60      /**
61       * Receive notification of a recoverable error.
62       *
63       * <p>The transformer must continue to try and provide normal transformation
64       * after invoking this method.  It should still be possible for the
65       * application to process the document through to the end if no other errors
66       * are encountered.</p>
67       *
68       * @param exception The error information encapsulated in a
69       *                  transformer exception.
70       *
71       * @throws javax.xml.transform.TransformerException if the application
72       * chooses to discontinue the transformation.
73       *
74       * @see javax.xml.transform.TransformerException
75       */
76      public abstract void error(TransformerException   exception)
77          throws TransformerException  ;
78  
79      /**
80       * <p>Receive notification of a non-recoverable error.</p>
81       *
82       * <p>The <code>Transformer</code> must continue to try and provide normal
83       * transformation after invoking this method.  It should still be possible for the
84       * application to process the document through to the end if no other errors
85       * are encountered, but there is no guarantee that the output will be
86       * useable.</p>
87       *
88       * @param exception The error information encapsulated in a
89       *    <code>TransformerException</code>.
90       *
91       * @throws javax.xml.transform.TransformerException if the application
92       * chooses to discontinue the transformation.
93       *
94       * @see javax.xml.transform.TransformerException
95       */
96      public abstract void fatalError(TransformerException   exception)
97          throws TransformerException  ;
98  }
99
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags