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