001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.xerces.xni.parser;
019:
020: import org.apache.xerces.xni.XNIException;
021:
022: /**
023: * An interface for handling errors. If the application is interested
024: * in error notifications, then it can register an error handler object
025: * that implements this interface with the parser configuration.
026: *
027: * @see XMLParserConfiguration
028: *
029: * @author Andy Clark, IBM
030: *
031: * @version $Id: XMLErrorHandler.java 570137 2007-08-27 14:17:57Z mrglavas $
032: */
033: public interface XMLErrorHandler {
034:
035: //
036: // XMLErrorHandler methods
037: //
038:
039: /**
040: * Reports a warning. Warnings are non-fatal and can be safely ignored
041: * by most applications.
042: *
043: * @param domain The domain of the warning. The domain can be any
044: * string but is suggested to be a valid URI. The
045: * domain can be used to conveniently specify a web
046: * site location of the relevant specification or
047: * document pertaining to this warning.
048: * @param key The warning key. This key can be any string and
049: * is implementation dependent.
050: * @param exception Exception.
051: *
052: * @throws XNIException Thrown to signal that the parser should stop
053: * parsing the document.
054: */
055: public void warning(String domain, String key,
056: XMLParseException exception) throws XNIException;
057:
058: /**
059: * Reports an error. Errors are non-fatal and usually signify that the
060: * document is invalid with respect to its grammar(s).
061: *
062: * @param domain The domain of the error. The domain can be any
063: * string but is suggested to be a valid URI. The
064: * domain can be used to conveniently specify a web
065: * site location of the relevant specification or
066: * document pertaining to this error.
067: * @param key The error key. This key can be any string and
068: * is implementation dependent.
069: * @param exception Exception.
070: *
071: * @throws XNIException Thrown to signal that the parser should stop
072: * parsing the document.
073: */
074: public void error(String domain, String key,
075: XMLParseException exception) throws XNIException;
076:
077: /**
078: * Report a fatal error. Fatal errors usually occur when the document
079: * is not well-formed and signifies that the parser cannot continue
080: * normal operation.
081: * <p>
082: * <strong>Note:</strong> The error handler should <em>always</em>
083: * throw an <code>XNIException</code> from this method. This exception
084: * can either be the same exception that is passed as a parameter to
085: * the method or a new XNI exception object. If the registered error
086: * handler fails to throw an exception, the continuing operation of
087: * the parser is undetermined.
088: *
089: * @param domain The domain of the fatal error. The domain can be
090: * any string but is suggested to be a valid URI. The
091: * domain can be used to conveniently specify a web
092: * site location of the relevant specification or
093: * document pertaining to this fatal error.
094: * @param key The fatal error key. This key can be any string
095: * and is implementation dependent.
096: * @param exception Exception.
097: *
098: * @throws XNIException Thrown to signal that the parser should stop
099: * parsing the document.
100: */
101: public void fatalError(String domain, String key,
102: XMLParseException exception) throws XNIException;
103:
104: } // interface XMLErrorHandler
|