View Javadoc
1   /*
2    * reserved comment block
3    * DO NOT REMOVE OR ALTER!
4    */
5   /*
6    * Copyright 2001, 2002,2004 The Apache Software Foundation.
7    *
8    * Licensed under the Apache License, Version 2.0 (the "License");
9    * you may not use this file except in compliance with the License.
10   * You may obtain a copy of the License at
11   *
12   *      http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  
21  package com.sun.org.apache.xerces.internal.xni.parser;
22  
23  import com.sun.org.apache.xerces.internal.xni.XNIException;
24  
25  /**
26   * An interface for handling errors. If the application is interested
27   * in error notifications, then it can register an error handler object
28   * that implements this interface with the parser configuration.
29   *
30   * @see XMLParserConfiguration
31   *
32   * @author Andy Clark, IBM
33   *
34   */
35  public interface XMLErrorHandler {
36  
37      //
38      // XMLErrorHandler methods
39      //
40  
41      /**
42       * Reports a warning. Warnings are non-fatal and can be safely ignored
43       * by most applications.
44       *
45       * @param domain    The domain of the warning. The domain can be any
46       *                  string but is suggested to be a valid URI. The
47       *                  domain can be used to conveniently specify a web
48       *                  site location of the relevent specification or
49       *                  document pertaining to this warning.
50       * @param key       The warning key. This key can be any string and
51       *                  is implementation dependent.
52       * @param exception Exception.
53       *
54       * @throws XNIException Thrown to signal that the parser should stop
55       *                      parsing the document.
56       */
57      public void warning(String domain, String key,
58                          XMLParseException exception) throws XNIException;
59  
60      /**
61       * Reports an error. Errors are non-fatal and usually signify that the
62       * document is invalid with respect to its grammar(s).
63       *
64       * @param domain    The domain of the error. The domain can be any
65       *                  string but is suggested to be a valid URI. The
66       *                  domain can be used to conveniently specify a web
67       *                  site location of the relevent specification or
68       *                  document pertaining to this error.
69       * @param key       The error key. This key can be any string and
70       *                  is implementation dependent.
71       * @param exception Exception.
72       *
73       * @throws XNIException Thrown to signal that the parser should stop
74       *                      parsing the document.
75       */
76      public void error(String domain, String key,
77                        XMLParseException exception) throws XNIException;
78  
79      /**
80       * Report a fatal error. Fatal errors usually occur when the document
81       * is not well-formed and signifies that the parser cannot continue
82       * normal operation.
83       * <p>
84       * <strong>Note:</strong> The error handler should <em>always</em>
85       * throw an <code>XNIException</code> from this method. This exception
86       * can either be the same exception that is passed as a parameter to
87       * the method or a new XNI exception object. If the registered error
88       * handler fails to throw an exception, the continuing operation of
89       * the parser is undetermined.
90       *
91       * @param domain    The domain of the fatal error. The domain can be
92       *                  any string but is suggested to be a valid URI. The
93       *                  domain can be used to conveniently specify a web
94       *                  site location of the relevent specification or
95       *                  document pertaining to this fatal error.
96       * @param key       The fatal error key. This key can be any string
97       *                  and is implementation dependent.
98       * @param exception Exception.
99       *
100      * @throws XNIException Thrown to signal that the parser should stop
101      *                      parsing the document.
102      */
103     public void fatalError(String domain, String key,
104                            XMLParseException exception) throws XNIException;
105 
106 } // interface XMLErrorHandler